Create a contact

POST /v1/contacts

Adds a contact and sends contact.created.

Needs contacts:write.

A customer from your own system

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"
    ]
  }'

const res = await fetch('https://app.soosh.io/v1/contacts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SOOSH_API_KEY}`,
    'Idempotency-Key': 'create-contact-a-customer-from-your-1',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "phone": "+91 98765 43210",
    "name": "Priya Sharma",
    "attributes": {
      "customer_id": "8812",
      "city": "Pune",
      "orders": 3
    },
    "tags": [
      "VIP"
    ]
  }),
});
console.log(await res.json());

import os
import requests

res = requests.post(
    "https://app.soosh.io/v1/contacts",
    headers={"Authorization": f"Bearer {os.environ['SOOSH_API_KEY']}", "Idempotency-Key": "create-contact-a-customer-from-your-1"},
    json={
        "phone": "+91 98765 43210",
        "name": "Priya Sharma",
        "attributes": {
            "customer_id": "8812",
            "city": "Pune",
            "orders": 3,
        },
        "tags": [
            "VIP",
        ],
    },
)
print(res.json())

Response201

{
  "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"
}

Every field of the contact object

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.

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.

Returns

201 The contact object. The contact, new or brought back.

Errors

Besides the ones every request can get:

409conflictThe number already belongs to a contact. error.details.id is that contact.

422invalid_phoneThe phone isn’t a valid number.

422invalid_fieldA 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.

422limit_reachedYour workspace is at its contacts limit.

409idempotency_in_progressA request with the same Idempotency-Key is still running.

422idempotency_mismatchThe Idempotency-Key was used before for a different request, or by another of your API keys.