COconversion

Upsert Contact

Create a new contact or update an existing one. Contacts are identified by email or cnvContactId. If the contact exists, its fields are updated; if not, a new contact is created.

post/v2/contacts

Request

  • Base URL
    https://pub-api.conversion.ai/api
  • Auth
    • API key in header X-API-Key
    • or API key in query parameter api_key

Request body

emailstring email

The contact's email address. At least one of email or cnvContactId is required. When both are provided, cnvContactId identifies the contact and email updates the contact's email address.

cnvContactIdstring uuid

The Conversion contact ID. Use this to identify an existing contact by its internal ID instead of email. At least one of email or cnvContactId is required.

subscriptionStatus'SUBSCRIBED' | 'UNSUBSCRIBED' | 'NO_STATUS'

The contact's email subscription status. System-managed statuses (BOUNCED, COMPLAINED, etc.) cannot be set through the API.

fieldsContactFields

A map of contact field keys to values. Keys must match existing field definitions in your Conversion account.

companyFieldsCompanyFields

A map of company field keys to values for the contact's associated company.

updateOnlyboolean

When true, restricts the operation to updates only. Returns a contact_not_found error if no existing contact matches the provided identifier.

syncToCRMboolean

When true, syncs the contact to the connected CRM (e.g., Salesforce) if the contact does not already have an external CRM record.

preserveExistingFieldsboolean

When true, prevents overwriting existing non-empty field values. New values are only written to fields that are currently empty or unset. Useful for enrichment workflows.

Example request

{
  "email": "jane@example.com",
  "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fields": {
    "first_name": "Jane",
    "last_name": "Smith",
    "job_title": "VP of Marketing"
  },
  "companyFields": {
    "company_name": "Acme Corp",
    "industry": "Technology"
  }
}

Response

Contact upserted successfully.

Changes

No recorded changes to this operation across all 1 revision of this API.