Contacts

Manage your CRM contacts, and read the organisations and groups they belong to. Reading requires contacts:read; creating, updating, deleting and (un)subscribing require contacts:write.

Where a contact came from

Every contact carries a source recording its origin: api, manual, import, form, email_ticket, instagram_message, messenger_message, whatsapp_message, or unknown. Contacts created through the API are stamped source: "api".

Creating contacts

POST /v1/contacts requires only email; everything else is optional.

Emails are unique per tenant. Creating a contact whose email already exists does not make a duplicate — you get 409 conflict carrying the existing contact’s id, so you can GET or PUT it instead:

{
  "error": "conflict",
  "message": "A contact with this email already exists.",
  "contactId": "1dcc380c-8076-2a37-5fb8-3a2265f83a67"
}

Shout also auto-matches a contact to an organisation by its email domain where it can, so a new contact may come back with an organisationId you didn’t set.

Updating contacts (partial semantics)

PUT /v1/contacts/{id} is a partial update — omit a field (or send null) to leave it unchanged. The one exception is groupIds:

null (or omitted) → keep the current group membership.
a non-null array (including []) → replaces the membership wholesale.

POST /v1/contacts/{id}/unsubscribe and .../subscribe each return the updated contact with unsubscribed flipped. Unsubscribing suppresses the contact from your email sends, honouring their consent — prefer this over deleting. (DELETE is available and returns 204.)

Organisations and groups (read-only)

Both are read-only and require contacts:read:

Organisations (GET /v1/organisations) — filterable by domain. Carry name, website, industry, country.
Groups / contact lists (GET /v1/groups) — small per tenant, so returned unpaginated. Group ids are integers, not UUIDs; use them in a contact’s groupIds. type is standard or all_contacts (the built-in list of everyone).