API reference

Companies

Companies are the organisations your contacts work for. Contacts and deals point to a company with company_id. Every plan includes them.

Scopes: companies:read · companies:write
Plan: Every plan
Events: company.*

The company object

Fields without a value are null. To list a company’s people, list contacts with company_id.

Attributes

iduuidRead-only
Unique identifier of the company.
namestring
Company name.
industrystringNullable
Industry, as free text.
websitestringNullable
Website URL.
phonestringNullable
Main phone number.
emailstringNullable
General email address.
addressstringNullable
Postal address, as one string.
descriptionstringNullable
Notes about the company.
sizestringNullable
Headcount band as free text, for example 51-200.
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.
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.
created_atdate-timeRead-only
When the record was created (UTC).
updated_atdate-timeRead-only
When the record last changed (UTC).

The company object

{
  "id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
  "name": "Northwind Analytics",
  "industry": "Software",
  "website": "https://northwind.example",
  "phone": "+44 20 7946 0100",
  "email": "[email protected]",
  "address": "18 Example Street, London EC2A 4NE, United Kingdom",
  "description": "Analytics platform for logistics teams. Annual contract since 2025.",
  "size": "51-200",
  "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
  "tags": [
    "enterprise"
  ],
  "custom_fields": {
    "annual_revenue": 4200000
  },
  "created_at": "2026-09-12T16:05:41Z",
  "updated_at": "2026-10-02T08:47:15Z"
}

List companies

GET/api/v1/companies

Requires companies:read

Returns the companies 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 by name.
sortenum
The field to sort by. Any other value is a 400 validation_failed.
One ofcreated_atupdated_atnameindustry
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.

namestring
Exact match. [like] matches a case-insensitive substring.
industrystring
Exact match. [like] matches a case-insensitive substring.
owner_iduuid
Exact match, or several IDs with [in].
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 company objects and meta. meta.next_cursor is null on the last page.

GET/api/v1/companies

curl -G https://acme.nextora.co/api/v1/companies \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -d 'name[like]=north' \
  -d limit=20

Response200 OK

{
  "data": [
    {
      "id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
      "name": "Northwind Analytics",
      "industry": "Software",
      "website": "https://northwind.example",
      "phone": "+44 20 7946 0100",
      "email": "[email protected]",
      "address": "18 Example Street, London EC2A 4NE, United Kingdom",
      "description": "Analytics platform for logistics teams. Annual contract since 2025.",
      "size": "51-200",
      "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
      "tags": [
        "enterprise"
      ],
      "custom_fields": {
        "annual_revenue": 4200000
      },
      "created_at": "2026-09-12T16:05:41Z",
      "updated_at": "2026-10-02T08:47:15Z"
    }
  ],
  "meta": {
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  }
}

Create a company

POST/api/v1/companies

Requires companies:write

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

Body parameters

namestringRequired
Company name.
industrystringNullable
Industry, as free text.
websitestringNullable
Website URL.
phonestringNullable
Main phone number.
emailstringNullable
General email address.
addressstringNullable
Postal address, as one string.
descriptionstringNullable
Notes about the company.
sizestringNullable
Headcount band as free text, for example 51-200.
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.
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 company, with 201 Created.

POST/api/v1/companies

curl -X POST https://acme.nextora.co/api/v1/companies \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Northwind Analytics",
    "industry": "Software",
    "website": "https://northwind.example",
    "size": "51-200",
    "tags": [
      "enterprise"
    ]
  }'

Response201 Created

{
  "data": {
    "id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "name": "Northwind Analytics",
    "industry": "Software",
    "website": "https://northwind.example",
    "phone": null,
    "email": null,
    "address": null,
    "description": null,
    "size": "51-200",
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "tags": [
      "enterprise"
    ],
    "custom_fields": {},
    "created_at": "2026-10-10T09:20:47Z",
    "updated_at": "2026-10-10T09:20:47Z"
  }
}

Retrieve a company

GET/api/v1/companies/{id}

Requires companies:read

Returns one company by ID.

Path parameters

iduuidRequired
The company’s ID.

Returns

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

GET/api/v1/companies/{id}

curl https://acme.nextora.co/api/v1/companies/2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56 \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "name": "Northwind Analytics",
    "industry": "Software",
    "website": "https://northwind.example",
    "phone": "+44 20 7946 0100",
    "email": "[email protected]",
    "address": "18 Example Street, London EC2A 4NE, United Kingdom",
    "description": "Analytics platform for logistics teams. Annual contract since 2025.",
    "size": "51-200",
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "tags": [
      "enterprise"
    ],
    "custom_fields": {
      "annual_revenue": 4200000
    },
    "created_at": "2026-09-12T16:05:41Z",
    "updated_at": "2026-10-02T08:47:15Z"
  }
}

Update a company

PATCH/api/v1/companies/{id}

Requires companies:write

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

Path parameters

iduuidRequired
The company’s ID.

Body parameters

namestring
Company name.
industrystringNullable
Industry, as free text.
websitestringNullable
Website URL.
phonestringNullable
Main phone number.
emailstringNullable
General email address.
addressstringNullable
Postal address, as one string.
descriptionstringNullable
Notes about the company.
sizestringNullable
Headcount band as free text, for example 51-200.
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.
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 company.

PATCH/api/v1/companies/{id}

curl -X PATCH https://acme.nextora.co/api/v1/companies/2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56 \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+44 20 7946 0100",
    "address": "18 Example Street, London EC2A 4NE, United Kingdom"
  }'

Response200 OK

{
  "data": {
    "id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "name": "Northwind Analytics",
    "industry": "Software",
    "website": "https://northwind.example",
    "phone": "+44 20 7946 0100",
    "email": "[email protected]",
    "address": "18 Example Street, London EC2A 4NE, United Kingdom",
    "description": "Analytics platform for logistics teams. Annual contract since 2025.",
    "size": "51-200",
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "tags": [
      "enterprise"
    ],
    "custom_fields": {
      "annual_revenue": 4200000
    },
    "created_at": "2026-09-12T16:05:41Z",
    "updated_at": "2026-10-02T08:47:15Z"
  }
}

Delete a company

DELETE/api/v1/companies/{id}

Requires companies:write

Moves the company 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 company’s ID.

Returns

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

DEL/api/v1/companies/{id}

curl -X DELETE https://acme.nextora.co/api/v1/companies/2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56 \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "deleted": true
  }
}

Restore a company

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

Requires companies:write

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

Path parameters

iduuidRequired
The company’s ID.

Returns

The restored company.

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

curl -X POST https://acme.nextora.co/api/v1/companies/2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56/restore \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "name": "Northwind Analytics",
    "industry": "Software",
    "website": "https://northwind.example",
    "phone": "+44 20 7946 0100",
    "email": "[email protected]",
    "address": "18 Example Street, London EC2A 4NE, United Kingdom",
    "description": "Analytics platform for logistics teams. Annual contract since 2025.",
    "size": "51-200",
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "tags": [
      "enterprise"
    ],
    "custom_fields": {
      "annual_revenue": 4200000
    },
    "created_at": "2026-09-12T16:05:41Z",
    "updated_at": "2026-10-02T08:47:15Z"
  }
}