Contact API

Manages contacts in your lists using the Contact API, supporting V1 (deprecated) and V2 endpoints for adding and updating data, with GET requests utilizing query strings for these operations.

Instructions

1. Get your Contact List ID from Contact Lists — the ID is shown in the left column of the grid.
2. Generate an API Key with Full Access permission: Account > API Keys > Add > name the key > set Contact API permission to Full Access > Create > Copy.
3. Go to API Documentation to build your request. Navigate to the Contact API section.
   • For adding or updating contacts, select the POST method. Choose V2 for the latest features and clearer responses, or V1 (Deprecated) if you need to use the older endpoint.
   • For adding or updating contacts via query string, select the GET method. Choose V2 for the latest features and clearer responses, or V1 (Deprecated) if you need to use the older endpoint.
   • Under Fields, select desired fields. For POST, Email is required plus any optional fields. For GET, select desired fields to add or update via query string. Use + Add New Custom Field to create fields on the fly.
4. Copy the Request URL and, for POST requests, the Request Body from the generator. For GET requests, the generator builds the Request URL with appropriate query parameters automatically.
5. Set up your API client (e.g., Postman):
   • For POST (V2): Choose POST method. Paste the Request URL (replace {listId} with your Contact List ID, and optionally add ?overwriteExisting=true). Add an Authorization header (x-api-key = your API key). Paste the Request Body under Body > Raw > JSON.
   • For POST (V1) Deprecated: Choose POST method. Paste the Request URL (replace {listId} with your Contact List ID). Add an Authorization header (x-api-key = your API key). Paste the Request Body under Body > Raw > JSON. Note: V1 endpoints have a different request body structure (e.g., camelCase field names).
   • For GET (V2): Choose GET method. Paste the Request URL (replace {listId} with your Contact List ID, and include query parameters to add or update contact data, such as ?email=...&FirstName=...&LastName=...&overwriteExisting=true). Add an Authorization header (x-api-key = your API key). No request body is needed.
   • For GET (V1) Deprecated: Choose GET method. Paste the Request URL (replace {listId} with your Contact List ID, and include query parameters to add or update contact data). Add an Authorization header (x-api-key = your API key). No request body is needed.
6. Update any placeholder values in the body (for POST requests) or query parameters (for GET requests) with real contact data and send the request.
   • For V2 endpoints (POST/GET): A 200 OK status indicates the request was processed. Check the response body for succeeded: true and any messages or data. For POST and GET, if less than 10% of contacts fail, the request will return 200 OK but indicate individual failures in the messages array. If more than 10% fail, it returns 400 Bad Request.
   • For V1 endpoints (POST/GET) Deprecated: A 200 OK status indicates the request was received, but the response body might be ambiguous regarding individual contact success or failure. Always rely on the HTTP status code for primary success indication, and carefully inspect the response body for details.
   • After POST or GET requests, check the Contact List to verify the Record Count increased or contacts were updated.

Related pages

• Contact API Reference — the endpoints and their routes, authentication, query parameters, request bodies, the batch validation rule and what each response code means
• Contact API Walkthrough — every step with screenshots, from finding the Contact List ID to generating a key, building the request and checking the result