---
title: "Upsert Contact"
method: POST
path: "/v2/contacts"
---

# Upsert Contact

`POST /v2/contacts`

## Request

- Base URL: `https://pub-api.conversion.ai/api`
- URL: `https://pub-api.conversion.ai/api/v2/contacts`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in query parameter `api_key`

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.

## Request body

- object
  - `email` string, 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.
  - `cnvContactId` string, 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.
  - `fields` ContactFields: A map of contact field keys to values. Keys must match existing field definitions in your Conversion account.
  - `companyFields` CompanyFields: A map of company field keys to values for the contact's associated company.
  - `updateOnly` boolean: When `true`, restricts the operation to updates only. Returns a `contact_not_found` error if no existing contact matches the provided identifier.
  - `syncToCRM` boolean: When `true`, syncs the contact to the connected CRM (e.g., Salesforce) if the contact does not already have an external CRM record.
  - `preserveExistingFields` boolean: 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.

## Response `200`

Contact upserted successfully.

- object
  - `data` object
    - `cnvContactId` string, uuid, required: The Conversion contact ID of the created or updated contact.
    - `contactCreated` boolean, required: `true` if a new contact was created, `false` if an existing contact was updated.

## Other responses

- `400`: The request was malformed or contained invalid data.
- `401`: Authentication failed.
- `404`: Contact not found (when `updateOnly` is true).
- `500`: An unexpected server error occurred.

---

[API](https://skmtc.dev/conversion/apis/conversion-api.md) - [All operations](https://skmtc.dev/conversion/apis/conversion-api/llms.txt) - [OpenAPI document](https://skmtc.dev/conversion/apis/conversion-api/revisions/8422f815402a?raw)