Leads

Store and manage leads

Retrieve Leads

GET

https://api.tomba.io/v1

/leads

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Returns the leads of your workspace, or your own leads when you aren't in a workspace, with each lead's list and custom attribute values.

list returns only the leads in one list.
meta.total_pages is rounded down, so it doesn't count a last, partial page. Use meta.total to know when you've read every lead.
With no matching leads, data.leads is an empty array and meta is absent.

Also accepts an OAuth 2.0 access token with the leads scope.

Retrieve Leads › query Parameters

page

integer · min: 1

Page number, starting at 1.

Default: 1

limit

integer · min: 1 · max: 200

Leads per page. Values above 200 are treated as 200.

Default: 10

list

integer · int64

ID of a lead list, to return only the leads in it.

sort

string · enum

Field to sort by.

Enum values:

first_name

last_name

country

website_url

position

twitter

Default: created_at

direction

string · enum

Sort direction.

Enum values:

desc

asc

Default: desc

Retrieve Leads › Responses

A page of leads.

object · required

GET/leads

curl https://api.tomba.io/v1/leads \
  --header 'X-Tomba-Key: <api-key>' \
  --header 'X-Tomba-Secret: <api-key>'

Example Responses

{
  "data": {
    "leads": [
      {
        "id": 1234,
        "user_id": 1042,
        "email": "jane.doe@stripe.com",
        "list_id": 12,
        "first_name": "Jane",
        "last_name": "Doe",
        "country": "US",
        "website_url": "stripe.com",
        "position": "Marketing Manager",
        "twitter": "https://twitter.com/janedoe",
        "linkedin": "https://www.linkedin.com/in/janedoe",
        "phone_number": "+14155550123",
        "company": "Stripe",
        "notes": "Met at the Q3 conference",
        "lead_source": "finder",
        "score": 90,
        "sync_status": null,
        "sync_airtable": null,
        "sync_hubspot": null,
        "sync_mailchimp": null,
        "sync_pipedrive": null,
        "created_at": "2026-09-15T10:30:00Z",
        "updated_at": "2026-09-20T14:00:00Z",
        "leads_list": {
          "list_id": 12,
          "size": 150,
          "name": "Q4 prospects"
        },
        "attributes": {
          "deal-size": "5000"
        }
      }
    ],
    "meta": {
      "total": 150,
      "pageSize": 10,
      "current": 1,
      "total_pages": 15
    }
  }
}

json

application/json

Create a Lead

POST

https://api.tomba.io/v1

/leads

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Saves a lead to your account. Every field is optional, email included. Tomba doesn't check for duplicates: saving the same email address twice creates two leads.

list_id must be a JSON number. Sent as a string, the lead is still created, but without the list and without every field that follows list_id in the request body. A list_id that isn't one of your own lists is dropped.
attributes sets custom attribute values, keyed by the attribute's identifier from GET /attributes. Send the values as strings. Keys that don't match one of your attributes are ignored.
You can store as many leads as pricing.available_leads in GET /me. Past that, the request fails with 422 rate_limit.

When your plan isn't Free and you've set up a lead webhook, Tomba sends the new lead to it. See Lead events.

Also accepts an OAuth 2.0 access token with the leads scope.

Create a Lead › Request Body

email

string · email

Email address. Stored in lowercase.

list_id

integer · int64

ID of one of your lead lists. Must be a JSON number.

first_name

string · minLength: 1 · maxLength: 25

First name, 1 to 25 characters.

last_name

string · minLength: 1 · maxLength: 25

Last name, 1 to 25 characters.

country

string

Two-letter country code in uppercase, for example US.

website_url

string

Company domain, for example stripe.com.

position

string · maxLength: 255

Job title, up to 255 characters.

twitter

string

Twitter profile URL. A bare handle fails validation.

linkedin

string

LinkedIn profile URL.

phone_number

string

Phone number.

company

string · maxLength: 55

Company name, up to 55 characters.

notes

string · maxLength: 55

Notes, up to 55 characters.

score

integer · max: 100

Lead score, up to 100.

lead_source

string

Where the lead came from, as a code in a string: 1 domain search, 2 email finder, 3 email verifier, 4 browser extension. Leads return it as domain, finder, verify, or browser.

object

Custom attribute values keyed by attribute identifier. Values must be strings.

Create a Lead › Responses

Lead created.

object · required

POST/leads

curl https://api.tomba.io/v1/leads \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Tomba-Key: <api-key>' \
  --header 'X-Tomba-Secret: <api-key>' \
  --data '{
  "email": "jane.doe@stripe.com",
  "list_id": 12,
  "first_name": "Jane",
  "last_name": "Doe",
  "company": "Stripe",
  "website_url": "stripe.com",
  "position": "Marketing Manager",
  "country": "US",
  "attributes": {
    "deal-size": "5000"
  }
}'

Example Request Body

{
  "email": "jane.doe@stripe.com",
  "list_id": 12,
  "first_name": "Jane",
  "last_name": "Doe",
  "company": "Stripe",
  "website_url": "stripe.com",
  "position": "Marketing Manager",
  "country": "US",
  "attributes": {
    "deal-size": "5000"
  }
}

json

application/json

Example Responses

{
  "data": {
    "id": 1235
  }
}

json

application/json

Retrieve a Single Lead

GET

https://api.tomba.io/v1

/leads/{leadId}

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Returns one lead of your workspace, as the only item of data.leads.

A lead that doesn't exist, or that you can't see, returns 200 with an empty data.leads array, not 404.

Also accepts an OAuth 2.0 access token with the leads scope.

Retrieve a Single Lead › path Parameters

leadId

integer · int64 · required

The lead's ID. A non-numeric ID fails with 422.

Retrieve a Single Lead › Responses

The lead, or an empty array when there's no such lead.

object · required

GET/leads/{leadId}

curl https://api.tomba.io/v1/leads/:leadId \
  --header 'X-Tomba-Key: <api-key>' \
  --header 'X-Tomba-Secret: <api-key>'

Example Responses

{
  "data": {
    "leads": [
      {
        "id": 1234,
        "user_id": 1042,
        "email": "jane.doe@stripe.com",
        "list_id": 12,
        "first_name": "Jane",
        "last_name": "Doe",
        "country": "US",
        "website_url": "stripe.com",
        "position": "Marketing Manager",
        "twitter": "https://twitter.com/janedoe",
        "linkedin": "https://www.linkedin.com/in/janedoe",
        "phone_number": "+14155550123",
        "company": "Stripe",
        "notes": "Met at the Q3 conference",
        "lead_source": "finder",
        "score": 90,
        "sync_status": null,
        "sync_airtable": null,
        "sync_hubspot": null,
        "sync_mailchimp": null,
        "sync_pipedrive": null,
        "created_at": "2026-09-15T10:30:00Z",
        "updated_at": "2026-09-20T14:00:00Z",
        "leads_list": {
          "list_id": 12,
          "size": 150,
          "name": "Q4 prospects"
        },
        "attributes": {
          "deal-size": "5000"
        }
      }
    ]
  }
}

json

application/json

Update a lead

PUT

https://api.tomba.io/v1

/leads/{leadId}

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Updates a lead of your workspace. Send only the fields to change; the others keep their values.

list_id moves the lead to that list. A list outside your workspace is ignored.
attributes adds or replaces custom attribute values, keyed by the attribute's identifier. Keys that don't match an attribute of your workspace are ignored.
Some limits differ from POST /leads: first_name and last_name need at least 2 characters, position takes up to 25, and twitter and linkedin up to 99.

Also accepts an OAuth 2.0 access token with the leads scope.

Update a lead › path Parameters

leadId

integer · int64 · required

The lead's ID. A non-numeric ID fails with 422.

Update a lead › Request Body

email

string · email

Email address. Stored in lowercase.

first_name

string · minLength: 2 · maxLength: 25

First name, 2 to 25 characters.

last_name

string · minLength: 2 · maxLength: 25

Last name, 2 to 25 characters.

country

string

Two-letter country code in uppercase, for example US.

website_url

string

Company domain, for example stripe.com.

position

string · maxLength: 25

Job title, up to 25 characters.

twitter

string · maxLength: 99

Twitter profile URL, up to 99 characters.

linkedin

string · maxLength: 99

LinkedIn profile URL, up to 99 characters.

phone_number

string

Phone number.

company

string · maxLength: 55

Company name, up to 55 characters.

notes

string · maxLength: 55

Notes, up to 55 characters.

score

integer · max: 100

Lead score, up to 100.

list_id

integer · int64

ID of a lead list in your workspace. Must be a JSON number.

lead_source

string · maxLength: 5

Where the lead came from, as a code in a string (see POST /leads).

object

Custom attribute values keyed by attribute identifier. Values must be strings.

Update a lead › Responses

Lead updated.

OperationSuccess

object · required

Result of an update or delete.

Delete a lead

DELETE

https://api.tomba.io/v1

/leads/{leadId}

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Deletes a lead of your workspace, with its custom attribute values.

Also accepts an OAuth 2.0 access token with the leads scope.

Delete a lead › path Parameters

leadId

integer · int64 · required

The lead's ID. A non-numeric ID fails with 422.

Delete a lead › Responses

Lead deleted.

OperationSuccess

object · required

Result of an update or delete.

Bulks Lead Lists

Retrieve Leads

GET

https://api.tomba.io/v1

/leads

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Returns the leads of your workspace, or your own leads when you aren't in a workspace, with each lead's list and custom attribute values.

list returns only the leads in one list.
meta.total_pages is rounded down, so it doesn't count a last, partial page. Use meta.total to know when you've read every lead.
With no matching leads, data.leads is an empty array and meta is absent.

Also accepts an OAuth 2.0 access token with the leads scope.

Retrieve Leads › query Parameters

page

integer · min: 1

Page number, starting at 1.

Default: 1

limit

integer · min: 1 · max: 200

Leads per page. Values above 200 are treated as 200.

Default: 10

list

integer · int64

ID of a lead list, to return only the leads in it.

sort

string · enum

Field to sort by.

Enum values:

first_name

last_name

country

website_url

position

twitter

Default: created_at

direction

string · enum

Sort direction.

Enum values:

desc

asc

Default: desc

Retrieve Leads › Responses

A page of leads.

object · required

Create a Lead

POST

https://api.tomba.io/v1

/leads

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Saves a lead to your account. Every field is optional, email included. Tomba doesn't check for duplicates: saving the same email address twice creates two leads.

list_id must be a JSON number. Sent as a string, the lead is still created, but without the list and without every field that follows list_id in the request body. A list_id that isn't one of your own lists is dropped.
attributes sets custom attribute values, keyed by the attribute's identifier from GET /attributes. Send the values as strings. Keys that don't match one of your attributes are ignored.
You can store as many leads as pricing.available_leads in GET /me. Past that, the request fails with 422 rate_limit.

When your plan isn't Free and you've set up a lead webhook, Tomba sends the new lead to it. See Lead events.

Also accepts an OAuth 2.0 access token with the leads scope.

Create a Lead › Request Body

email

string · email

Email address. Stored in lowercase.

list_id

integer · int64

ID of one of your lead lists. Must be a JSON number.

first_name

string · minLength: 1 · maxLength: 25

First name, 1 to 25 characters.

last_name

string · minLength: 1 · maxLength: 25

Last name, 1 to 25 characters.

country

string

Two-letter country code in uppercase, for example US.

website_url

string

Company domain, for example stripe.com.

position

string · maxLength: 255

Job title, up to 255 characters.

twitter

string

Twitter profile URL. A bare handle fails validation.

linkedin

string

LinkedIn profile URL.

phone_number

string

Phone number.

company

string · maxLength: 55

Company name, up to 55 characters.

notes

string · maxLength: 55

Notes, up to 55 characters.

score

integer · max: 100

Lead score, up to 100.

lead_source

string

Where the lead came from, as a code in a string: 1 domain search, 2 email finder, 3 email verifier, 4 browser extension. Leads return it as domain, finder, verify, or browser.

object

Custom attribute values keyed by attribute identifier. Values must be strings.

Create a Lead › Responses

Lead created.

object · required

Retrieve a Single Lead

GET

https://api.tomba.io/v1

/leads/{leadId}

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Returns one lead of your workspace, as the only item of data.leads.

A lead that doesn't exist, or that you can't see, returns 200 with an empty data.leads array, not 404.

Also accepts an OAuth 2.0 access token with the leads scope.

Retrieve a Single Lead › path Parameters

leadId

integer · int64 · required

The lead's ID. A non-numeric ID fails with 422.

Retrieve a Single Lead › Responses

The lead, or an empty array when there's no such lead.

object · required

Update a lead

PUT

https://api.tomba.io/v1

/leads/{leadId}

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Updates a lead of your workspace. Send only the fields to change; the others keep their values.

list_id moves the lead to that list. A list outside your workspace is ignored.
attributes adds or replaces custom attribute values, keyed by the attribute's identifier. Keys that don't match an attribute of your workspace are ignored.
Some limits differ from POST /leads: first_name and last_name need at least 2 characters, position takes up to 25, and twitter and linkedin up to 99.

Also accepts an OAuth 2.0 access token with the leads scope.

Update a lead › path Parameters

leadId

integer · int64 · required

The lead's ID. A non-numeric ID fails with 422.

Update a lead › Request Body

email

string · email

Email address. Stored in lowercase.

first_name

string · minLength: 2 · maxLength: 25

First name, 2 to 25 characters.

last_name

string · minLength: 2 · maxLength: 25

Last name, 2 to 25 characters.

country

string

Two-letter country code in uppercase, for example US.

website_url

string

Company domain, for example stripe.com.

position

string · maxLength: 25

Job title, up to 25 characters.

twitter

string · maxLength: 99

Twitter profile URL, up to 99 characters.

linkedin

string · maxLength: 99

LinkedIn profile URL, up to 99 characters.

phone_number

string

Phone number.

company

string · maxLength: 55

Company name, up to 55 characters.

notes

string · maxLength: 55

Notes, up to 55 characters.

score

integer · max: 100

Lead score, up to 100.

list_id

integer · int64

ID of a lead list in your workspace. Must be a JSON number.

lead_source

string · maxLength: 5

Where the lead came from, as a code in a string (see POST /leads).

object

Custom attribute values keyed by attribute identifier. Values must be strings.

Update a lead › Responses

Lead updated.

OperationSuccess

object · required

Result of an update or delete.

Delete a lead

DELETE

https://api.tomba.io/v1

/leads/{leadId}

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Deletes a lead of your workspace, with its custom attribute values.

Also accepts an OAuth 2.0 access token with the leads scope.

Delete a lead › path Parameters

leadId

integer · int64 · required

The lead's ID. A non-numeric ID fails with 422.

Delete a lead › Responses

Lead deleted.

OperationSuccess

object · required

Result of an update or delete.