v1

latestOpenAPI 3.1.02026-07-247601.0 MB

Miscellaneous

Add Records to a List

This endpoint doesn't consume Apollo credits. Learn more about API pricing and credits.

A <a href="https://knowledge.apollo.io/hc/en-us/articles/4409728608525-Create-and-Use-a-List" target="_blank">list</a> 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 <a href="https://docs.apollo.io/reference/search-for-contacts">Search for Contacts</a> or <a href="https://docs.apollo.io/reference/search-for-accounts">Search for Accounts</a> 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.

post/labels/add_entity_ids_to_label_names

Request body

entity_idsstring[] required

The Apollo IDs of the contacts or accounts to add to the lists. IDs that aren't valid are ignored. Example: ["66e34b81740c50074e3d1bd4"]

label_namesstring[] 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"]

modality'contacts' | 'accounts' required

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

asyncboolean

Controls whether the request is processed synchronously or in the background. <ul><li>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.</li><li>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.</li></ul>

Response

200

messagestring