EmpiraaEmpiraaDEVELOPERS Use cases Prompts Playground FAQ empiraa.com

Contacts

Create, read, update and delete the people at your Accounts.

View as MarkdownOpen in ClaudeOpen in ChatGPT

A Contact is a person at one of your Accounts. Every Contact belongs to an Account. For people you're still prospecting, use prospect contacts instead.

The Contact object#

Field Type Notes
id string UUID.
first_name string Can be empty.
last_name string Can be empty.
email string or null
phone string or null
mobile string or null
job_title string or null
department string or null
linkedin_url string or null
account_id string The Account the Contact belongs to.
is_primary boolean The Account's primary Contact. Read-only through the API.
is_champion boolean Marked as a champion. Read-only through the API.
created_at string ISO 8601 timestamp.
updated_at string ISO 8601 timestamp.
JSON
{
  "id": "a1d4e7b2-5c3f-4e8a-b9d6-0f2c7e1a3b54",
  "first_name": "Maria",
  "last_name": "Garcia",
  "email": "maria.garcia@contoso.example",
  "phone": "+1 312 555 0187",
  "mobile": null,
  "job_title": "Head of Procurement",
  "department": "Operations",
  "linkedin_url": null,
  "account_id": "3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10",
  "is_primary": false,
  "is_champion": false,
  "created_at": "2026-11-12T09:30:00.000Z",
  "updated_at": "2026-11-12T09:30:00.000Z"
}

List Contacts#

GET /contacts · Scope: contacts:read

Returns Contacts newest first. Archived Contacts and Contacts in Recently deleted aren't listed.

Query parameters#

Parameter Type Required Notes
limit integer No 1 to 100. Default 20.
cursor string No meta.cursor from the previous page.

Example#

curl "https://crm.empiraa.app/api/v1/contacts?limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200#

JSON
{
  "data": [
    {
      "id": "a1d4e7b2-5c3f-4e8a-b9d6-0f2c7e1a3b54",
      "first_name": "Maria",
      "last_name": "Garcia",
      "email": "maria.garcia@contoso.example",
      "phone": null,
      "mobile": null,
      "job_title": "Head of Procurement",
      "department": null,
      "linkedin_url": null,
      "account_id": "3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10",
      "is_primary": false,
      "is_champion": false,
      "created_at": "2026-11-12T09:30:00.000Z",
      "updated_at": "2026-11-12T09:30:00.000Z"
    }
  ],
  "meta": { "cursor": null, "total": 1, "hasMore": false },
  "error": null
}

meta.total is the number of Contacts in the workspace.

Create a Contact#

POST /contacts · Scope: contacts:write

Request body#

Field Type Required Notes
account_id string Yes The Account the Contact belongs to.
first_name string No Defaults to an empty string.
last_name string No Defaults to an empty string.
email string or null No
phone string or null No
mobile string or null No
job_title string or null No
department string or null No
linkedin_url string or null No

Example#

curl -X POST https://crm.empiraa.app/api/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10",
    "first_name": "Maria",
    "last_name": "Garcia",
    "email": "maria.garcia@contoso.example",
    "job_title": "Head of Procurement"
  }'

Response 201#

The new Contact object in data.

Errors#

Status Code When
400 INVALID_REQUEST account_id is missing or not a string.
404 NOT_FOUND account_id isn't an Account in your workspace ("Account not found").

Webhook events: contact.created.

Get a Contact#

GET /contacts/{id} · Scope: contacts:read

Path parameters#

Parameter Type Notes
id string Contact ID.

Example#

curl https://crm.empiraa.app/api/v1/contacts/a1d4e7b2-5c3f-4e8a-b9d6-0f2c7e1a3b54 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200#

The Contact object in data.

Errors#

Status Code When
404 NOT_FOUND No Contact with that ID in this workspace.

Update a Contact#

PATCH /contacts/{id} · Scope: contacts:write

Send only the fields you want to change.

Request body#

Field Type Notes
first_name string
last_name string
email string or null
phone string or null
job_title string or null
department string or null

Other fields, including mobile, linkedin_url and account_id, can't be changed through this endpoint and are ignored.

Example#

curl -X PATCH https://crm.empiraa.app/api/v1/contacts/a1d4e7b2-5c3f-4e8a-b9d6-0f2c7e1a3b54 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_title": "VP Procurement"}'

Response 200#

The updated Contact object in data.

Errors#

Status Code When
404 NOT_FOUND No Contact with that ID in this workspace.

Webhook events: none.

Delete a Contact#

DELETE /contacts/{id} · Scope: contacts:write

Moves the Contact to Recently deleted in Signal. It stays there for 30 days, during which it can be restored from Settings → Recently deleted. After 30 days it's removed for good.

Example#

curl -X DELETE https://crm.empiraa.app/api/v1/contacts/a1d4e7b2-5c3f-4e8a-b9d6-0f2c7e1a3b54 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 204#

No body.

Errors#

Status Code When
404 NOT_FOUND No Contact with that ID in this workspace.

Webhook events: contact.deleted.