Contacts — Smart Analytics & Integrations for Business Phone Systems

A contact is a person attached to a customer account (or another entity) of your workspace: legal representative, technical contact, accountant, etc.

These are the workspace's own contacts. To search or create contacts in a connected CRM, use CRM Lookup. For Smart Routings contacts, see Smart Routings contacts.

All endpoints in this section are workspace-scoped and reserved to admin users.

Headers: Authorization: Bearer {workspace-token}

#Permissions

Endpoint	Required permission
`GET /api/contacts`	Admin user with `contact.view`
`GET /api/contacts/{id}`	`contact.view`
`POST /api/contacts`	Admin user with `contact.create`
`PUT /api/contacts/{id}`	Admin user with `contact.edit`
`DELETE /api/contacts/{id}`	Admin user with `contact.delete`

#The contact object

{
  "id": 41,
  "user_id": null,
  "contactable_type": "customer",
  "contactable_id": 12,
  "active": true,
  "profunction": "IT Manager",
  "first_name": "Alice",
  "last_name": "Martin",
  "email_address": "alice.martin@acme.com",
  "mobile_phone": "+33612345678",
  "landline_phone": "+33142000000",
  "is_legal": false,
  "is_technical": true,
  "is_accountant": false,
  "is_invoices_recipient": false,
  "is_sms_enabled": false,
  "cfd_token": null,
  "cfd_authorised_hosts": null,
  "comment": null,
  "created_at": "2024-03-01T09:00:00.000000Z",
  "updated_at": "2024-03-01T09:00:00.000000Z"
}

contactable_type and contactable_id identify the entity the contact belongs to. For a customer, use customer and the customer ID.

#GET /api/contacts

Returns every contact of the workspace as a plain JSON array (not paginated).

Response 200 — array of contact objects

#GET /api/contacts/{id}

Returns a single contact.

Response 200 — contact object

Response 403 — not authorized

#POST /api/contacts

Creates a contact. The body must be a JSON object.

Request body

Field	Type	Required	Description
`last_name`	string	yes	Last name (2–255 characters)
`email_address`	string	yes	Email address
`contactable_type`	string	yes	Type of the parent entity, e.g. `customer`
`contactable_id`	integer	yes	ID of the parent entity
`first_name`	string	no	First name (2–255 characters)
`profunction`	string	no	Job title
`active`	boolean	no	Whether the contact is active
`mobile_phone`	string	no	Mobile phone number
`landline_phone`	string	no	Landline phone number
`is_legal`	boolean	no	Legal representative
`is_technical`	boolean	no	Technical contact
`is_accountant`	boolean	no	Accounting contact
`is_invoices_recipient`	boolean	no	Receives invoices
`is_sms_enabled`	boolean	no	Can receive SMS
`comment`	string	no	Free-form comment

id, user_id, created_at and updated_at cannot be set.

Response 201 — the created contact object

Response 400 — validation failure

{
  "response": "bad request: please check body parameters.",
  "hint": ["The email address field is required."]
}

#PUT /api/contacts/{id}

Updates a contact. Accepts the same fields as POST /api/contacts, all optional. Only the fields you send are changed.

Response 201 — the updated contact object

#DELETE /api/contacts/{id}

Deletes a contact.

Response 200

{ "response": "element deleted" }