> For the complete documentation index, see [llms.txt](https://api-docs.conversion.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.conversion.ai/contacts.md). # Contacts ## Concepts ### Contact identifier Contacts are uniquely identified by their **email address**. You can optionally include your **system's contact id**. ### Default Contact Variables These are the default variables for contacts in Conversion. Use these keys when updating or retrieving these variables.
KeyTypeDescription
first_nameSTRINGFirst Name
last_nameSTRINGLast Name
job_titleSTRINGJob Title
phone_numberSTRINGPhone Number
citySTRINGCity
countrySTRINGCountry
timezoneSTRINGUse IANA format (ex. "America/Los_Angeles")
### Subscription Status This denotes the subscription status of a contact. Possible values: * `NOT_SUBSCRIBED` (default) - Contact is not marked * `SUBSCRIBED` - Contact is subscribed to at least one email topic * `UNSUBSCRIBED` - Contact has unsubscribed from all email topics * `BOUNCED` - Previous emails to this contact have bounced * `COMPLAINED` - Contact's inbox has marked your sender as spam Use `subscriptionStatus` in requests to configure a contact's subscription status. {% hint style="warning" %} ### Updating subscription status When updating a contact's subscription status, you can only update it to either `SUBSCRIBED` or `NOT_SUBSCRIBED` in the batch upsert recipients endpoint. You can update to any status in the individual recipient upsert endpoint. {% endhint %} ## Batch Upsert Contacts Create or update multiple contacts in a single request. To update a contact, include their email address and any variables you want to update. **Rate limits:** 10 / second, 200 contacts per batch **Method:** `POST` **Route:** `/v1/contacts/batch` **Request Body:** ```json { "batch": [ { "email": "john@example.com", "id": "your_contact_id_123", "companyId": "your_internal_company_id_123", "syncToCrm": false, "audienceId": "12345", "createdAt": "2025-08-12T09:21:45Z", "variables": { "first_name": "John", "last_name": "Doe", "phone": "+1234567890", "company_name": "Acme Corp", ... } }, ... ] } ``` **Field Descriptions:** * `batch` (required): List of contacts to create/update * `email` (required): Valid email address * `id` (optional): Your system's contact id * `companyId` (optional): Your system's company ID to link the contact to - Note will only populate if the company already exists in our system. * `audienceId` (optional): Conversion's internal audienceId to add the new contact to. You will have to pull the audienceId from the audience view URL for now. * `syncToCrm` (optional): Defaults to `false`. Denotes if this contact should sync back to your CRM. * `createdAt` (optional): Defaults to now. When the contact was created in your system. * `variables` (optional): Key-value pairs for custom contact fields **Response:** Empty object response. ## Get Contact by Email Retrieve a contact and it's variables using their email address. **Rate limits:** 10 / second **Method:** `GET` **Route:** `/v1/contacts/{email}` **Response:** ```json { "email": "john@example.com", "id": "your_contact_id_123", "companyId": "your_internal_company_id_123", "subscriptionStatus": "SUBSCRIBED", "syncToCrm": false, "createdAt": "2025-08-12T09:21:45Z", "variables": { "first_name": "John", "last_name": "Doe", "phone": "+1234567890", "company_name": "Acme Corp", ... } } ``` ## Delete Contact by Email Remove a contact from Conversion using their email address. **Rate limits:** 10 / second **Method:** `DELETE` **Route:** `/v1/contacts/{email}` **Query Parameters:** * `?gdpr=true` : Fully deletes a contact and all associated information from Conversion, in compliance with GDPR. {% hint style="warning" %} #### GDPR Deletion Only use this query parameter if a user is requesting their data to be deleted, Conversion still maintains important user information when using the standard delete endpoint. {% endhint %} **Response:** Empty object response. ## Batch Upsert Recipients Create or update multiple recipients in a single request. To upsert a recipient, include their email address and their subscription status. **Rate limits:** 10 / second, 200 recipients per batch **Method:** `POST` **Route:** `/v1/recipients/batch` **Request Body:** ```json { "batch": [ { "email":"test@test.com", "status":"NO_STATUS" }, { "email":"test2@test.com", "status":"NO_STATUS" }, { "email":"test3@test.com", "status":"SUBSCRIBED" }, ... ] } ``` **Field Descriptions:** * `batch` (required): List of recipients to create/update * `email` (required): Valid email address * `status` (required): this must be converting between either `SUBSCRIBED` or `NO_STATUS` (The current recipient must be one of those statuses and converting to the other) **Response:** Empty object response. ## Upsert Recipient Create or update a single recipient. To upsert a recipient, include their email address and their subscription status. This individual endpoint can update to ANY status. **Rate limits:** 10 / second **Method:** `POST` **Route:** `/v1/recipients/:email` **Request Body:** ```json { "status":"UNSUBSCRIBED" } ``` **Field Descriptions:** * `status` (required): The status to convert to. This endpoint can convert between any of the status. Be careful of converting recipients that have already bounced, as they are likely to bounce again. **Response:** Empty object response.