Lead Lists

Download schema

Organize leads into lists

Retrieve Leads Lists

GET

https://api.tomba.io/v1

/leads_lists

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Returns up to 25 lead lists of your workspace, or your own lists when you aren't in a workspace. There's no pagination.

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

Retrieve Leads Lists › Responses

Your lead lists.

object · required

GET/leads_lists

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

Example Responses

{
  "data": {
    "list_leads": [
      {
        "id": 12,
        "user_id": 1042,
        "size": 150,
        "name": "Q4 prospects",
        "type": "campaigns",
        "favorite": true,
        "created_at": "2026-07-01T08:00:00Z",
        "updated_at": "2026-09-20T14:00:00Z"
      },
      {
        "id": 15,
        "user_id": 2087,
        "size": 45,
        "name": "Enterprise accounts",
        "type": "campaigns",
        "favorite": false,
        "created_at": "2026-08-15T10:30:00Z",
        "updated_at": "2026-09-18T09:15:00Z"
      }
    ]
  }
}

json

application/json

Create Leads List

POST

https://api.tomba.io/v1

/leads_lists

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Creates a lead list. The name must be unique among your lists.

You can create as many lists as pricing.available_list in GET /me. Past that, the request fails with 422 rate_limit; the error message mentions custom fields, but the limit is on lists.

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

Create Leads List › Request Body

name

string · minLength: 2 · maxLength: 40 · required

List name, 2 to 40 characters after trimming spaces.

favorite

boolean

Whether to mark the list as a favorite.

Default: false

Create Leads List › Responses

List created.

object · required

Retrieve a Single Leads List

GET

https://api.tomba.io/v1

/leads_lists/{listId}

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Returns one lead list of your workspace.

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

Retrieve a Single Leads List › path Parameters

listId

integer · int64 · required

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

Retrieve a Single Leads List › Responses

The list.

LeadsList · required

Update Leads List

PUT

https://api.tomba.io/v1

/leads_lists/{listId}

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Renames a list of your workspace, or marks or unmarks it as a favorite.

favorite is always written: leaving it out sets it to false.
A name already used by a list in your workspace fails with 422, and that includes this list's own current name. Leave name out to change only favorite.

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

Update Leads List › path Parameters

listId

integer · int64 · required

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

Update Leads List › Request Body

name

string · minLength: 2 · maxLength: 40

New list name, 2 to 40 characters after trimming spaces.

favorite

boolean

Whether the list is a favorite. Defaults to false when left out.

Default: false

Update Leads List › Responses

List updated.

OperationSuccess

object · required

Result of an update or delete.

Delete Leads List

DELETE

https://api.tomba.io/v1

/leads_lists/{listId}

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Deletes a list of your workspace. The leads in it aren't deleted.

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

Delete Leads List › path Parameters

listId

integer · int64 · required

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

Delete Leads List › Responses

List deleted.

OperationSuccess

object · required

Result of an update or delete.

Leads Lead Attributes

Retrieve Leads Lists

GET

https://api.tomba.io/v1

/leads_lists

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Returns up to 25 lead lists of your workspace, or your own lists when you aren't in a workspace. There's no pagination.

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

Retrieve Leads Lists › Responses

Your lead lists.

object · required

Create Leads List

POST

https://api.tomba.io/v1

/leads_lists

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Creates a lead list. The name must be unique among your lists.

You can create as many lists as pricing.available_list in GET /me. Past that, the request fails with 422 rate_limit; the error message mentions custom fields, but the limit is on lists.

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

Create Leads List › Request Body

name

string · minLength: 2 · maxLength: 40 · required

List name, 2 to 40 characters after trimming spaces.

favorite

boolean

Whether to mark the list as a favorite.

Default: false

Create Leads List › Responses

List created.

object · required

Retrieve a Single Leads List

GET

https://api.tomba.io/v1

/leads_lists/{listId}

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Returns one lead list of your workspace.

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

Retrieve a Single Leads List › path Parameters

listId

integer · int64 · required

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

Retrieve a Single Leads List › Responses

The list.

LeadsList · required

Update Leads List

PUT

https://api.tomba.io/v1

/leads_lists/{listId}

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Renames a list of your workspace, or marks or unmarks it as a favorite.

favorite is always written: leaving it out sets it to false.
A name already used by a list in your workspace fails with 422, and that includes this list's own current name. Leave name out to change only favorite.

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

Update Leads List › path Parameters

listId

integer · int64 · required

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

Update Leads List › Request Body

name

string · minLength: 2 · maxLength: 40

New list name, 2 to 40 characters after trimming spaces.

favorite

boolean

Whether the list is a favorite. Defaults to false when left out.

Default: false

Update Leads List › Responses

List updated.

OperationSuccess

object · required

Result of an update or delete.

Delete Leads List

DELETE

https://api.tomba.io/v1

/leads_lists/{listId}

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Deletes a list of your workspace. The leads in it aren't deleted.

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

Delete Leads List › path Parameters

listId

integer · int64 · required

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

Delete Leads List › Responses

List deleted.

OperationSuccess

object · required

Result of an update or delete.