---
title: Contacts
excerpt: Manage the contacts attached to the customer accounts of a workspace.
order: 7
---

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](/en/docs/cx-api/lookup). For Smart Routings contacts, see [Smart Routings contacts](/en/docs/cx-api/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

```json
{
  "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

```json
{
  "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`**

```json
{ "response": "element deleted" }
```