Add Records to a List

post

https://api.apollo.io/api/v1/labels/add_entity_ids_to_label_names

✅
No Credit Cost
This endpoint doesn't consume Apollo credits. Learn more about API pricing and credits.

A list is a saved group of contacts or accounts in Apollo that you can organize, action, and track together.

Use the Add Records to a List endpoint to add existing contacts or accounts to one or more lists, referencing the lists by name. If a list name you provide doesn't exist yet for the given modality, Apollo creates it automatically.

Provide the record IDs in entity_ids and the target list names in label_names. To find record IDs, use the Search for Contacts or Search for Accounts endpoints.

If you provide no valid entity_ids or no label_names, the endpoint makes no changes and returns a 200 response with a confirmation message.

Body Params

entity_ids

array of strings

required

The Apollo IDs of the contacts or accounts to add to the lists. IDs that aren't valid are ignored.

Example: ["66e34b81740c50074e3d1bd4"]

entity_ids*

label_names

array of strings

required

The names of the lists to add the records to. If a name doesn't already exist for the given modality, Apollo creates a new list with that name.

Example: ["Conference 2024 - Maui"]

label_names*

modality

string

enum

required

The type of records referenced by entity_ids. Must be contacts or accounts.

Allowed:

async

boolean

Controls whether the request is processed synchronously or in the background.

false (default): Apollo processes the request during the API call and returns the updated lists. A synchronous request must finish within the API's 5-minute (300-second) request timeout, so a large entity_ids batch can time out.
true: Apollo processes the work in the background and immediately returns an entity_progress_job object — instead of the updated lists — that you can poll for progress. Use this for batches large enough to risk the 5-minute timeout.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Add Records to a List

No Credit Cost

What’s Next

What’s Next

No Credit Cost

200200

401401

403403

422422

429429

What’s Next

What’s Next