> ## Documentation Index > Fetch the complete documentation index at: https://docs.conversion.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi.json post /v2/contacts openapi: 3.1.0 info: title: Conversion API version: 2.0.0 description: >- The Conversion API lets you programmatically manage contacts, track custom events, and manage their associated data. servers: - url: https://pub-api.conversion.ai/api security: - apiKey: [] paths: /v2/contacts: post: summary: Upsert Contact description: >- 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. operationId: upsertContact requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email description: >- 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. examples: - jane@example.com cnvContactId: type: string format: uuid description: >- 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. examples: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 subscriptionStatus: $ref: '#/components/schemas/SubscriptionStatus' fields: $ref: '#/components/schemas/ContactFields' companyFields: $ref: '#/components/schemas/CompanyFields' updateOnly: type: boolean default: false description: >- When `true`, restricts the operation to updates only. Returns a `contact_not_found` error if no existing contact matches the provided identifier. syncToCRM: type: boolean default: false description: >- When `true`, syncs the contact to the connected CRM (e.g., Salesforce) if the contact does not already have an external CRM record. preserveExistingFields: type: boolean default: false description: >- 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. examples: create-with-fields: summary: Create contact with fields value: email: jane@example.com subscriptionStatus: SUBSCRIBED fields: first_name: Jane last_name: Smith job_title: VP of Marketing companyFields: company_name: Acme Corp update-by-id: summary: Update by contact ID value: cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 fields: job_title: Director of Marketing enrich: summary: Enrich without overwriting value: email: jane@example.com preserveExistingFields: true fields: first_name: Jane last_name: Smith phone: +1-555-0100 responses: '200': description: Contact upserted successfully. content: application/json: schema: type: object properties: data: type: object required: - cnvContactId - contactCreated properties: cnvContactId: type: string format: uuid description: >- The Conversion contact ID of the created or updated contact. contactCreated: type: boolean description: >- `true` if a new contact was created, `false` if an existing contact was updated. examples: created: summary: Contact created value: data: cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 contactCreated: true updated: summary: Contact updated value: data: cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 contactCreated: false '400': description: The request was malformed or contained invalid data. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing-identifier: summary: Missing identifier value: error: code: missing_identifier message: either 'email' or 'cnvContactId' is required invalid-email: summary: Invalid email value: error: code: invalid_email message: 'invalid email format: not-an-email' invalid-field: summary: Unknown field value: error: code: invalid_field message: field 'nonexistent_key' does not exist invalid-subscription-status: summary: Invalid subscription status value: error: code: invalid_subscription_status message: invalid subscription status value '401': description: Authentication failed. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: summary: Missing or invalid API key value: error: code: unauthorized message: API key is required '404': description: Contact not found (when `updateOnly` is true). content: application/json: schema: $ref: '#/components/schemas/Error' examples: not-found: summary: Contact not found value: error: code: contact_not_found message: no contact found with the provided identifier '500': description: An unexpected server error occurred. content: application/json: schema: $ref: '#/components/schemas/Error' examples: internal: summary: Internal error value: error: code: internal_error message: failed to upsert contact components: schemas: SubscriptionStatus: type: string enum: - SUBSCRIBED - UNSUBSCRIBED - NO_STATUS description: >- The contact's email subscription status. System-managed statuses (`BOUNCED`, `COMPLAINED`, etc.) cannot be set through the API. ContactFields: type: object additionalProperties: {} description: >- A map of contact field keys to values. Keys must match existing field definitions in your Conversion account. examples: - first_name: Jane last_name: Smith job_title: VP of Marketing CompanyFields: type: object additionalProperties: {} description: >- A map of company field keys to values for the contact's associated company. examples: - company_name: Acme Corp industry: Technology Error: type: object properties: error: type: object required: - code - message properties: code: type: string description: A machine-readable error code. examples: - invalid_email message: type: string description: A human-readable error description. examples: - 'invalid email format: not-an-email' securitySchemes: apiKey: type: apiKey in: header name: X-API-Key description: >- Your Conversion API key. Found in **Settings > Integrations** in the dashboard. Format: `sk_live__`. ````