API reference

Leads

Leads are inbound interest you have not qualified yet: a name, a way to reach them, where they came from and how far they got. Web forms and imports create them; so can you.

Scopes: leads:read · leads:write
Plan: Sales hub
Events: lead.*

The lead object

status and source accept the built-in values below and any the workspace has added in the app. score is computed in Nextora and cannot be written.

Attributes

iduuidRead-only
Unique identifier of the lead.
namestring
The person’s name.
emailstringNullable
Email address.
phonestringNullable
Phone number.
company_namestringNullable
The company they mentioned, as free text.
statusstring
Where the lead is in qualification. Workspaces can add their own statuses. New leads start as new.
Built innewcontactedqualifiedproposalnegotiationwonlost
sourcestringNullable
The channel the lead came from. Workspaces can add their own sources.
Built inwebsitereferralcold_calladvertisementsocialeventemailsmstelegramviberwhatsappinstagramother
scoreintegerRead-only
Lead score, maintained in Nextora by lead scoring and workflows. 0 until scored.
owner_iduuid
The user who owns the record. On create it defaults to the API key’s owner. See Users.
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 lead object

{
  "id": "a7c9e1b3-5f2d-4a6c-8e9b-2d4f6a8c0e13",
  "name": "Grace Whitfield",
  "email": "[email protected]",
  "phone": "+44 161 496 0732",
  "company_name": "Harbor Logistics",
  "status": "new",
  "source": "website",
  "score": 0,
  "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
  "custom_fields": {
    "budget": 15000
  },
  "created_at": "2026-10-10T07:58:31Z",
  "updated_at": "2026-10-10T07:58:31Z"
}

Capturing leads

Creating a lead is the one write a read-only workspace still accepts, so a website’s lead capture keeps working while billing is sorted out. Every other write answers 403 workspace_read_only until the subscription is active again.

Posting your site’s forms to the API? A Nextora web form does the same without an API key in your front end, with validation, spam protection and the form’s automations.

List leads

GET/api/v1/leads

Requires leads:read

Returns the leads 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_atnamestatusscore
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.
emailstring
Exact match. [like] matches a case-insensitive substring.
statusstring
Exact match. [like] matches a case-insensitive substring.
Built innewcontactedqualifiedproposalnegotiationwonlost
sourcestring
Exact match. [like] matches a case-insensitive substring.
Built inwebsitereferralcold_calladvertisementsocialeventemailsmstelegramviberwhatsappinstagramother
owner_iduuid
Exact match, or several IDs with [in].
company_namestring
Exact match. [like] matches a case-insensitive substring.
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 lead objects and meta. meta.next_cursor is null on the last page.

GET/api/v1/leads

curl -G https://acme.nextora.co/api/v1/leads \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -d status=new \
  -d 'created_at[gte]=2026-10-01T00:00:00Z' \
  -d limit=20

Response200 OK

{
  "data": [
    {
      "id": "a7c9e1b3-5f2d-4a6c-8e9b-2d4f6a8c0e13",
      "name": "Grace Whitfield",
      "email": "[email protected]",
      "phone": "+44 161 496 0732",
      "company_name": "Harbor Logistics",
      "status": "new",
      "source": "website",
      "score": 0,
      "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
      "custom_fields": {
        "budget": 15000
      },
      "created_at": "2026-10-10T07:58:31Z",
      "updated_at": "2026-10-10T07:58:31Z"
    }
  ],
  "meta": {
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  }
}

Create a lead

POST/api/v1/leads

Requires leads:write

Creates a lead and runs the workflows that react to new leads, as for a lead created in the app. Works in a read-only workspace too.

Body parameters

namestringRequired
The person’s name.
emailstringNullable
Email address.
phonestringNullable
Phone number.
company_namestringNullable
The company they mentioned, as free text.
statusstring
Where the lead is in qualification. Workspaces can add their own statuses. New leads start as new.
Built innewcontactedqualifiedproposalnegotiationwonlost
Defaultnew
sourcestringNullable
The channel the lead came from. Workspaces can add their own sources.
Built inwebsitereferralcold_calladvertisementsocialeventemailsmstelegramviberwhatsappinstagramother
owner_iduuid
The user who owns the record. On create it defaults to the API key’s owner. See Users.
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 lead, with 201 Created.

POST/api/v1/leads

curl -X POST https://acme.nextora.co/api/v1/leads \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Grace Whitfield",
    "email": "[email protected]",
    "phone": "+44 161 496 0732",
    "company_name": "Harbor Logistics",
    "source": "website",
    "custom_fields": {
      "budget": 15000
    }
  }'

Response201 Created

{
  "data": {
    "id": "a7c9e1b3-5f2d-4a6c-8e9b-2d4f6a8c0e13",
    "name": "Grace Whitfield",
    "email": "[email protected]",
    "phone": "+44 161 496 0732",
    "company_name": "Harbor Logistics",
    "status": "new",
    "source": "website",
    "score": 0,
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "custom_fields": {
      "budget": 15000
    },
    "created_at": "2026-10-10T07:58:31Z",
    "updated_at": "2026-10-10T07:58:31Z"
  }
}

Retrieve a lead

GET/api/v1/leads/{id}

Requires leads:read

Returns one lead by ID.

Path parameters

iduuidRequired
The lead’s ID.

Returns

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

GET/api/v1/leads/{id}

curl https://acme.nextora.co/api/v1/leads/a7c9e1b3-5f2d-4a6c-8e9b-2d4f6a8c0e13 \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "a7c9e1b3-5f2d-4a6c-8e9b-2d4f6a8c0e13",
    "name": "Grace Whitfield",
    "email": "[email protected]",
    "phone": "+44 161 496 0732",
    "company_name": "Harbor Logistics",
    "status": "new",
    "source": "website",
    "score": 0,
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "custom_fields": {
      "budget": 15000
    },
    "created_at": "2026-10-10T07:58:31Z",
    "updated_at": "2026-10-10T07:58:31Z"
  }
}

Update a lead

PATCH/api/v1/leads/{id}

Requires leads:write

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

Path parameters

iduuidRequired
The lead’s ID.

Body parameters

namestring
The person’s name.
emailstringNullable
Email address.
phonestringNullable
Phone number.
company_namestringNullable
The company they mentioned, as free text.
statusstring
Where the lead is in qualification. Workspaces can add their own statuses. New leads start as new.
Built innewcontactedqualifiedproposalnegotiationwonlost
sourcestringNullable
The channel the lead came from. Workspaces can add their own sources.
Built inwebsitereferralcold_calladvertisementsocialeventemailsmstelegramviberwhatsappinstagramother
owner_iduuid
The user who owns the record. On create it defaults to the API key’s owner. See Users.
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 lead.

PATCH/api/v1/leads/{id}

curl -X PATCH https://acme.nextora.co/api/v1/leads/a7c9e1b3-5f2d-4a6c-8e9b-2d4f6a8c0e13 \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "qualified",
    "custom_fields": {
      "budget": 18000
    }
  }'

Response200 OK

{
  "data": {
    "id": "a7c9e1b3-5f2d-4a6c-8e9b-2d4f6a8c0e13",
    "name": "Grace Whitfield",
    "email": "[email protected]",
    "phone": "+44 161 496 0732",
    "company_name": "Harbor Logistics",
    "status": "qualified",
    "source": "website",
    "score": 0,
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "custom_fields": {
      "budget": 18000
    },
    "created_at": "2026-10-10T07:58:31Z",
    "updated_at": "2026-10-10T10:44:19Z"
  }
}

Delete a lead

DELETE/api/v1/leads/{id}

Requires leads:write

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

Returns

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

DEL/api/v1/leads/{id}

curl -X DELETE https://acme.nextora.co/api/v1/leads/a7c9e1b3-5f2d-4a6c-8e9b-2d4f6a8c0e13 \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "a7c9e1b3-5f2d-4a6c-8e9b-2d4f6a8c0e13",
    "deleted": true
  }
}

Restore a lead

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

Requires leads:write

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

Path parameters

iduuidRequired
The lead’s ID.

Returns

The restored lead.

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

curl -X POST https://acme.nextora.co/api/v1/leads/a7c9e1b3-5f2d-4a6c-8e9b-2d4f6a8c0e13/restore \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "a7c9e1b3-5f2d-4a6c-8e9b-2d4f6a8c0e13",
    "name": "Grace Whitfield",
    "email": "[email protected]",
    "phone": "+44 161 496 0732",
    "company_name": "Harbor Logistics",
    "status": "new",
    "source": "website",
    "score": 0,
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "custom_fields": {
      "budget": 15000
    },
    "created_at": "2026-10-10T07:58:31Z",
    "updated_at": "2026-10-10T07:58:31Z"
  }
}