API reference

Contacts

Contacts are the people you work with: customers, prospects, partners. A contact can belong to a company, has an owner, and carries tags and custom fields. Every plan includes them.

Scopes: contacts:read · contacts:write
Plan: Every plan
Events: contact.*

The contact object

Lists, creates and updates all return this shape. Fields you do not have a value for are null; tags is an empty list and custom_fields an empty object.

Attributes

iduuidRead-only
Unique identifier of the contact.
first_namestring
First name.
last_namestringNullable
Last name.
full_namestringRead-only
First and last name, as the app shows it.
emailstringNullable
Email address. Validated on write.
phonestringNullable
Phone number, as entered.
positionstringNullable
Job title.
company_iduuidNullable
The company the contact works for.
companyobjectRead-onlyNullable
The company’s ID and name, so a list can show it without a second request.
- iduuid
  Company ID.
- namestring
  Company name.
owner_iduuid
The user who owns the record. On create it defaults to the API key’s owner. See Users.
tagsstring[]
Labels, by name. Writing tags replaces the whole list. A name the workspace doesn’t have yet is created if the key’s owner may manage fields; otherwise the request fails with 400 validation_failed.
sourcestringNullable
Where the contact came from, as free text — for example website, referral or form.
custom_fieldsobject
Custom-field values keyed by field key. Updates merge into the stored values; send null for a key to clear it. See Custom fields.
last_activity_atdate-timeRead-onlyNullable
When activity was last logged on the contact: a note, an email, a call or a meeting.
created_atdate-timeRead-only
When the record was created (UTC).
updated_atdate-timeRead-only
When the record last changed (UTC).

The contact object

{
  "id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
  "first_name": "Ada",
  "last_name": "Brennan",
  "full_name": "Ada Brennan",
  "email": "[email protected]",
  "phone": "+44 20 7946 0958",
  "position": "Head of Operations",
  "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
  "company": {
    "id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "name": "Northwind Analytics"
  },
  "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
  "tags": [
    "enterprise",
    "renewal-2027"
  ],
  "source": "website",
  "custom_fields": {
    "region": "emea"
  },
  "last_activity_at": "2026-10-08T14:12:09Z",
  "created_at": "2026-09-14T09:30:00Z",
  "updated_at": "2026-10-08T14:12:09Z"
}

List contacts

GET/api/v1/contacts

Requires contacts:read

Returns the contacts the key’s owner can see, newest first. Filter on the fields below, combine them with q, and follow meta.next_cursor for more.

Query parameters

limitinteger
Page size, from 1 to 100.
Default50
cursorstring
The meta.next_cursor of the previous page. Omit it for the first page.
qstring
Search first and last name, email and phone.
sortenum
The field to sort by. Any other value is a 400 validation_failed.
One ofcreated_atupdated_atfirst_namelast_nameemaillast_activity_at
Defaultcreated_at
orderenum
Sort direction.
One ofascdesc
Defaultdesc
filterstring (JSON)
An advanced filter: conditions joined with and or or. See the JSON filter.

Filters

Add ?field=value or ?field[operator]=value — operators.

emailstring
Exact match. [like] matches a case-insensitive substring.
phonestring
Exact match. [like] matches a case-insensitive substring.
company_iduuid
Exact match, or several IDs with [in].
owner_iduuid
Exact match, or several IDs with [in].
sourcestring
Exact match. [like] matches a case-insensitive substring.
tagsstring[]
tags=vip returns contacts tagged vip. Records whose list contains this value.
created_atdate-time
An ISO 8601 timestamp. Use a range: [gt], [gte], [lt], [lte].
updated_atdate-time
An ISO 8601 timestamp. Use a range: [gt], [gte], [lt], [lte].

Returns

A list of contact objects and meta. meta.next_cursor is null on the last page.

GET/api/v1/contacts

curl -G https://acme.nextora.co/api/v1/contacts \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -d q=brennan \
  -d limit=20

Response200 OK

{
  "data": [
    {
      "id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
      "first_name": "Ada",
      "last_name": "Brennan",
      "full_name": "Ada Brennan",
      "email": "[email protected]",
      "phone": "+44 20 7946 0958",
      "position": "Head of Operations",
      "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
      "company": {
        "id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
        "name": "Northwind Analytics"
      },
      "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
      "tags": [
        "enterprise",
        "renewal-2027"
      ],
      "source": "website",
      "custom_fields": {
        "region": "emea"
      },
      "last_activity_at": "2026-10-08T14:12:09Z",
      "created_at": "2026-09-14T09:30:00Z",
      "updated_at": "2026-10-08T14:12:09Z"
    }
  ],
  "meta": {
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  }
}

Create a contact

POST/api/v1/contacts

Requires contacts:write

Creates a contact. It goes through the same path as the app, so workflows, the activity log and webhooks behave as they do for a contact created by hand.

Body parameters

first_namestringRequired
First name.
last_namestringNullable
Last name.
emailstringNullable
Email address. Validated on write.
phonestringNullable
Phone number, as entered.
positionstringNullable
Job title.
company_iduuidNullable
The company the contact works for.
owner_iduuid
The user who owns the record. On create it defaults to the API key’s owner. See Users.
tagsstring[]
Labels, by name. Writing tags replaces the whole list. A name the workspace doesn’t have yet is created if the key’s owner may manage fields; otherwise the request fails with 400 validation_failed.
sourcestringNullable
Where the contact came from, as free text — for example website, referral or form.
custom_fieldsobject
Custom-field values keyed by field key. Updates merge into the stored values; send null for a key to clear it. See Custom fields.

Returns

The new contact, with 201 Created.

POST/api/v1/contacts

curl -X POST https://acme.nextora.co/api/v1/contacts \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ada",
    "last_name": "Brennan",
    "email": "[email protected]",
    "phone": "+44 20 7946 0958",
    "position": "Head of Operations",
    "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "tags": [
      "enterprise"
    ],
    "source": "website",
    "custom_fields": {
      "region": "emea"
    }
  }'

Response201 Created

{
  "data": {
    "id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "first_name": "Ada",
    "last_name": "Brennan",
    "full_name": "Ada Brennan",
    "email": "[email protected]",
    "phone": "+44 20 7946 0958",
    "position": "Head of Operations",
    "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "company": {
      "id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
      "name": "Northwind Analytics"
    },
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "tags": [
      "enterprise"
    ],
    "source": "website",
    "custom_fields": {
      "region": "emea"
    },
    "last_activity_at": null,
    "created_at": "2026-10-10T09:24:11Z",
    "updated_at": "2026-10-10T09:24:11Z"
  }
}

Retrieve a contact

GET/api/v1/contacts/{id}

Requires contacts:read

Returns one contact by ID.

Path parameters

iduuidRequired
The contact’s ID.

Returns

The contact. 404 not_found when it does not exist or the key’s owner cannot see it.

GET/api/v1/contacts/{id}

curl https://acme.nextora.co/api/v1/contacts/3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "first_name": "Ada",
    "last_name": "Brennan",
    "full_name": "Ada Brennan",
    "email": "[email protected]",
    "phone": "+44 20 7946 0958",
    "position": "Head of Operations",
    "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "company": {
      "id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
      "name": "Northwind Analytics"
    },
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "tags": [
      "enterprise",
      "renewal-2027"
    ],
    "source": "website",
    "custom_fields": {
      "region": "emea"
    },
    "last_activity_at": "2026-10-08T14:12:09Z",
    "created_at": "2026-09-14T09:30:00Z",
    "updated_at": "2026-10-08T14:12:09Z"
  }
}

Update a contact

PATCH/api/v1/contacts/{id}

Requires contacts:write

Changes the fields you send and leaves the rest as they are. PUT does the same as PATCH.

Path parameters

iduuidRequired
The contact’s ID.

Body parameters

first_namestring
First name.
last_namestringNullable
Last name.
emailstringNullable
Email address. Validated on write.
phonestringNullable
Phone number, as entered.
positionstringNullable
Job title.
company_iduuidNullable
The company the contact works for.
owner_iduuid
The user who owns the record. On create it defaults to the API key’s owner. See Users.
tagsstring[]
Labels, by name. Writing tags replaces the whole list. A name the workspace doesn’t have yet is created if the key’s owner may manage fields; otherwise the request fails with 400 validation_failed.
sourcestringNullable
Where the contact came from, as free text — for example website, referral or form.
custom_fieldsobject
Custom-field values keyed by field key. Updates merge into the stored values; send null for a key to clear it. See Custom fields.

Returns

The updated contact.

PATCH/api/v1/contacts/{id}

curl -X PATCH https://acme.nextora.co/api/v1/contacts/3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "position": "Chief Operating Officer"
  }'

Response200 OK

{
  "data": {
    "id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "first_name": "Ada",
    "last_name": "Brennan",
    "full_name": "Ada Brennan",
    "email": "[email protected]",
    "phone": "+44 20 7946 0958",
    "position": "Chief Operating Officer",
    "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "company": {
      "id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
      "name": "Northwind Analytics"
    },
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "tags": [
      "enterprise",
      "renewal-2027"
    ],
    "source": "website",
    "custom_fields": {
      "region": "emea"
    },
    "last_activity_at": "2026-10-08T14:12:09Z",
    "created_at": "2026-09-14T09:30:00Z",
    "updated_at": "2026-10-10T09:31:48Z"
  }
}

Delete a contact

DELETE/api/v1/contacts/{id}

Requires contacts:write

Moves the contact to the workspace Trash, as deleting it in the app does. It disappears from lists; restore it to bring it back.

Path parameters

iduuidRequired
The contact’s ID.

Returns

{ "data": { "id": "…", "deleted": true } }. 404 not_found when there is nothing to delete.

DEL/api/v1/contacts/{id}

curl -X DELETE https://acme.nextora.co/api/v1/contacts/3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "deleted": true
  }
}

Restore a contact

POST/api/v1/contacts/{id}/restore

Requires contacts:write

Brings a contact back from Trash, with its fields and links as they were.

Path parameters

iduuidRequired
The contact’s ID.

Returns

The restored contact.

POST/api/v1/contacts/{id}/restore

curl -X POST https://acme.nextora.co/api/v1/contacts/3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f/restore \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "first_name": "Ada",
    "last_name": "Brennan",
    "full_name": "Ada Brennan",
    "email": "[email protected]",
    "phone": "+44 20 7946 0958",
    "position": "Head of Operations",
    "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "company": {
      "id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
      "name": "Northwind Analytics"
    },
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "tags": [
      "enterprise",
      "renewal-2027"
    ],
    "source": "website",
    "custom_fields": {
      "region": "emea"
    },
    "last_activity_at": "2026-10-08T14:12:09Z",
    "created_at": "2026-09-14T09:30:00Z",
    "updated_at": "2026-10-08T14:12:09Z"
  }
}