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

workspaceId

required

The workspace to create the contact in.

string format: uuid

Example

a1b2c3d4-e5f6-7890-abcd-ef1234567890

name

required

Full name of the contact.

string

Example

Henrik Larsen

email

required

Email address of the contact.

string format: email

Example

henrik@example.dk

Responses

200

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

Jan

lastName

Last name of the contact.

string | null

Example

Mueller

email

Primary email address of the contact.

string | null

Example

jan.mueller@acme-customer.de

phone

Phone number of the contact in E.164 format.

string | null

Example

+4915112345678

companyName

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

string | null

Example

Acme Customer GmbH

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