# 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.
Key
Type
Description
first_name
STRING
First Name
last_name
STRING
Last Name
job_title
STRING
Job Title
phone_number
STRING
Phone Number
city
STRING
City
country
STRING
Country
timezone
STRING
Use 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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://api-docs.conversion.ai/contacts.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.