# Create a contact

`POST /v1/contacts`

Adds a contact and sends `contact.created`.

Needs `contacts:write`.

## Body

- `phone` (string, required): The number with its country code, with or without `+`. Spaces, dashes, dots and brackets are ignored, and a leading `00` counts as `+`.
- `name` (string): The name your business gives the contact. A new WhatsApp profile name never replaces it: `whatsapp_name` follows the customer. Up to 255 characters.
- `attributes` (object): Your own fields on the contact. Names are 1 to 64 letters, digits or underscores, and can't start with `__`. A string value is up to 1024 characters. A contact can have at most 50. A map; each value is a string or number or boolean.
- `tags` (array of strings): The contact's tags. New tags join your workspace's tag list in grey. Up to 50 items. Each 1 to 50 characters.
- `number_id` (string, uuid): The number to message the contact from, from `GET /v1/numbers`.
- `marketing_opt_out` (boolean): Set to `true` if the contact opted out of marketing messages.

## Headers

- `Idempotency-Key` (string): Send one so a retry doesn't add the contact twice. See [Retrying safely](/reference/api/#retrying-safely). 1 to 255 characters.

## Bringing back a deleted contact

If the number belongs to a contact you deleted, that contact is brought back with its history, and the fields you send are applied. That also returns `201`.

## Example

```sh
curl -X POST https://app.soosh.io/v1/contacts \
  -H "Authorization: Bearer $SOOSH_API_KEY" \
  -H "Idempotency-Key: create-contact-a-customer-from-your-1" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+91 98765 43210",
    "name": "Priya Sharma",
    "attributes": {
      "customer_id": "8812",
      "city": "Pune",
      "orders": 3
    },
    "tags": [
      "VIP"
    ]
  }'
```

Response 201:

```json
{
  "id": "4ea0d485-435d-407f-837a-c7d67095f23a",
  "phone": "+919876543210",
  "whatsapp_user_id": null,
  "name": "Priya Sharma",
  "whatsapp_name": null,
  "attributes": {
    "customer_id": "8812",
    "city": "Pune",
    "orders": 3
  },
  "tags": [
    "VIP"
  ],
  "marketing_opt_out": false,
  "number_id": null,
  "chat": {
    "status": "open",
    "assigned_agent_id": null,
    "last_message_at": null,
    "last_inbound_at": null
  },
  "created_at": "2026-10-14T09:05:11.420Z",
  "updated_at": "2026-10-14T09:05:11.420Z"
}
```

## Returns

201. The contact, new or brought back.

## Errors

Besides the ones every request can get (https://docs.soosh.io/reference/api/errors/):

- 409 `conflict`: The number already belongs to a contact. `error.details.id` is that contact.
- 422 `invalid_phone`: The `phone` isn't a valid number.
- 422 `invalid_field`: A field breaks a rule: for example an attribute name with a space, a tag that is too long, or a `number_id` that isn't in your workspace.
- 422 `limit_reached`: Your workspace is at its `contacts` limit.
- 409 `idempotency_in_progress`: A request with the same `Idempotency-Key` is still running.
- 422 `idempotency_mismatch`: The `Idempotency-Key` was used before for a different request, or by another of your API keys.