Contacts and Accounts

oHallo automatically creates contacts and accounts from inbound messages. Contacts represent individual people; accounts represent the companies they belong to. Use the API to search, read, and manage these records.

Contacts

List contacts

Search contacts by name, email, or phone number.

Required scope: contacts:read

curl "https://api.ohallo.eu/api/contacts?q=alex" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Query parameters:

Parameter	Type	Required	Description
q	string	No	Search query: matches against name, email, and phone
limit	integer	No	Max items to return (default 50, max 100)
offset	integer	No	Number of items to skip (default 0)

Response:

{
  "items": [
    {
      "id": "f7e8d9c0-b1a2-3456-7890-abcdef123456",
      "tenantId": "00112233-4455-4788-9899-aabbccddeeff",
      "name": "Alex Doe",
      "email": "alex.doe@example.com",
      "phone": null,
      "accountId": "12345678-abcd-4f01-a345-678901234567",
      "accountName": "Example Company",
      "externalRef": null,
      "createdAt": "2026-02-10T08:30:00.000Z",
      "updatedAt": "2026-03-15T14:30:00.000Z"
    }
  ],
  "total": 1
}

Get contact

Retrieve a single contact by ID.

Required scope: contacts:read

curl "https://api.ohallo.eu/api/contacts/f7e8d9c0-b1a2-3456-7890-abcdef123456" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "id": "f7e8d9c0-b1a2-3456-7890-abcdef123456",
  "tenantId": "00112233-4455-4788-9899-aabbccddeeff",
  "name": "Alex Doe",
  "email": "alex.doe@example.com",
  "phone": null,
  "accountId": "12345678-abcd-4f01-a345-678901234567",
  "accountName": "Example Company",
  "externalRef": null,
  "identities": [
    {
      "channel": "email",
      "value": "alex.doe@example.com"
    }
  ],
  "createdAt": "2026-02-10T08:30:00.000Z",
  "updatedAt": "2026-03-15T14:30:00.000Z"
}

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.

Link contact to account

Associate a contact with an existing account. This is useful when oHallo could not automatically resolve the account, for example when the contact uses a personal email address.

Required scope: contacts:write

curl -X POST "https://api.ohallo.eu/api/contacts/f7e8d9c0-b1a2-3456-7890-abcdef123456/link-account" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "12345678-abcd-4f01-a345-678901234567"
  }'

Response:

{
  "ok": true
}

Create contact

Create a contact manually, for example when importing from an external CRM. Send firstName, lastName and companyName, and in identities each address the contact is known by, 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 those addresses reaches this contact.

Required scope: contacts:write

curl -X POST "https://api.ohallo.eu/api/contacts" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Alex",
    "lastName": "Doe",
    "companyName": "Example Company",
    "identities": [{ "channel": "email", "identityValue": "alex.doe@example.com" }]
  }'

Update contact

Update a contact’s details: firstName, lastName, companyName, and email and phone, the contact’s email address and phone number of record. Only included fields are changed; null removes an email address or phone number. An address or number that already identifies another contact answers 409.

Required scope: contacts:write

curl -X PATCH "https://api.ohallo.eu/api/contacts/f7e8d9c0-b1a2-3456-7890-abcdef123456" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx" \
  -H "Content-Type: application/json" \
  -d '{ "firstName": "Alexandra" }'

Delete contact

Delete a contact. Associated conversations are not deleted.

Required scope: contacts:write

curl -X DELETE "https://api.ohallo.eu/api/contacts/f7e8d9c0-b1a2-3456-7890-abcdef123456" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Accounts

List accounts

Search accounts by name, VAT number, or company registration number.

Required scope: accounts:read

curl "https://api.ohallo.eu/api/accounts?q=example" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Query parameters:

Parameter	Type	Required	Description
q	string	No	Search query: matches against name, VAT number, and registration number
limit	integer	No	Max items to return (default 50, max 100)
offset	integer	No	Number of items to skip (default 0)

Response:

{
  "items": [
    {
      "id": "12345678-abcd-4f01-a345-678901234567",
      "tenantId": "00112233-4455-4788-9899-aabbccddeeff",
      "name": "Example Company",
      "vatNumber": null,
      "address": null,
      "website": null,
      "industry": "Industrial equipment",
      "externalRef": null,
      "contactCount": 1,
      "createdAt": "2026-01-20T10:00:00.000Z",
      "updatedAt": "2026-03-10T11:15:00.000Z"
    }
  ],
  "total": 1
}

Get account

Retrieve a single account by ID.

Required scope: accounts:read

curl "https://api.ohallo.eu/api/accounts/12345678-abcd-4f01-a345-678901234567" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "id": "12345678-abcd-4f01-a345-678901234567",
  "tenantId": "00112233-4455-4788-9899-aabbccddeeff",
  "name": "Example Company",
  "vatNumber": null,
  "registrationNumber": null,
  "address": null,
  "website": null,
  "industry": "Industrial equipment",
  "externalRef": null,
  "enrichedAt": "2026-01-20T10:05:00.000Z",
  "createdAt": "2026-01-20T10:00:00.000Z",
  "updatedAt": "2026-03-10T11:15:00.000Z"
}

Get account contacts

List all contacts associated with an account.

Required scope: accounts:read

curl "https://api.ohallo.eu/api/accounts/12345678-abcd-4f01-a345-678901234567/contacts" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "items": [
    {
      "id": "f7e8d9c0-b1a2-3456-7890-abcdef123456",
      "name": "Alex Doe",
      "email": "alex.doe@example.com",
      "phone": null,
      "createdAt": "2026-02-10T08:30:00.000Z"
    }
  ],
  "total": 1
}

How contacts and accounts are resolved

When oHallo receives a message from an unknown sender, the following happens automatically:

1. Contact creation. A contact record is created using the sender’s email address, phone number, or chat identity.
2. Account resolution. For email, oHallo attempts to match the sender to an existing account:
   • By email domain (e.g., @example.com matches the Example Company account)
   • By VAT number or company registration number found in an email from a personal address
   • By CRM lookup if an external CRM is connected via MCP
3. Account enrichment. For newly created accounts, oHallo enriches the record with data from the company website.

If automatic resolution fails, the contact is created without an account link. You can then link it manually using the POST /api/contacts/{id}/link-account endpoint or via the dashboard.