Create a contact

POST

/api/contacts

• Production

Create a contact manually. oHallo auto-creates contacts from inbound messages, but you can also create them via the API — for example, when importing from an external CRM.

Authorizations

• bearerAuth

Request Body

object

firstName

The contact’s first name.

string

Example

Alex

lastName

The contact’s last name.

string

Example

Doe

companyName

The company the contact works for.

string

Example

Example Company

identities

The addresses the contact is known by, each with its channel: email for an email address, voice for a phone number the contact calls from, whatsapp for a WhatsApp number. A conversation from one of them reaches this contact.

Array<object>

object

channel

required

string

Example

email

identityValue

required

string

Example

alex.doe@example.com

Responses

201

The contact was created.

A contact represents an individual person who has communicated with your organization. Contacts are automatically created when a new sender is detected, and enriched over time with additional information from conversations and account resolution.

object

id

required

Unique identifier for the contact.

string format: uuid

Example

ct1a2b3c-5678-9abc-def0-1234567890ab

tenantId

required

The tenant this contact belongs to.

string format: uuid

Example

a0b1c2d3-4567-89ab-cdef-0123456789ab

externalRef

External CRM identifier. Set when this contact is resolved against a CRM system via an MCP server.

string | null

Example

CRM-CONTACT-78291

resolutionStatus

required

How the contact was identified. ‘unresolved’ means no CRM match was found yet. ‘crm_resolved’ means the contact was matched to a CRM record via an MCP server. ‘manually_resolved’ means a human agent linked the contact manually.

string

Example

crm_resolved

firstName

First name of the contact.

string | null

Example

Alex

lastName

Last name of the contact.

string | null

Example

Doe

email

Primary email address of the contact.

string | null

Example

alex.doe@example.com

givenEmail

The email address the visitor typed in a live chat, at its start or in the email field the chat shows. It is not verified. Present only when the visitor gave one.

string

Example

alex.doe@example.com

phone

Phone number of the contact in E.164 format.

string | null

companyName

Company name associated with this contact, derived from email domain or CRM resolution.

string | null

Example

Example Company

createdAt

required

Timestamp when the contact was first detected.

string format: date-time

Example

2026-02-10T14:30:00.000Z

updatedAt

required

Timestamp when the contact was last updated.

string format: date-time

Example

2026-03-20T09:15:00.000Z

422

Validation error. Required fields are missing or invalid.

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found

code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string

Example

key_lock

missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>

Example

[
  "mcp:write"
]

entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid

Example

11223344-5566-4788-99aa-bbccddeeff00

connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string

undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>

Example

[
  "get_orders"
]

declaredTools

On the same 422: the tools the connection declares.

Array<string>

Example

[
  "get_order",
  "search_orders"
]