Contacts

Create and manage 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.

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.

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:

{
  "batch": [
    {
      "email": "[email protected]",
      "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": "[phone]",
        "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:

{
  "email": "[email protected]",
  "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": "[phone]",
    "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.

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.

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:

{
    "batch": [
        {
            "email":"[email protected]",
            "status":"NO_STATUS"
        },
        {
            "email":"[email protected]",
            "status":"NO_STATUS"
        },
        {
            "email":"[email protected]",
            "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:

{
    "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.