> ## 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. # Batch Upsert Contacts > Create or update up to 1,000 contacts in a single request. Each contact is processed independently and the response includes a per-contact result indicating success or failure. ## OpenAPI ````yaml /openapi.json post /v2/contacts/batch 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/batch: post: summary: Batch Upsert Contacts description: >- Create or update up to 1,000 contacts in a single request. Each contact is processed independently and the response includes a per-contact result indicating success or failure. operationId: batchUpsertContacts requestBody: required: true content: application/json: schema: type: object required: - contacts properties: contacts: type: array minItems: 1 maxItems: 1000 description: An array of contact objects to upsert. items: type: object description: A single contact to upsert. properties: email: type: string format: email description: >- The contact's email address. At least one of `email` or `cnvContactId` is required. examples: - jane@example.com cnvContactId: type: string format: uuid description: >- The Conversion contact ID. 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 all operations to updates only. Contacts that are not found will be returned with a `contact_not_found` error in their result item. syncToCRM: type: boolean default: false description: >- When `true`, syncs upserted contacts to the connected CRM (e.g., Salesforce) if they do not already have an external CRM record. preserveExistingFields: type: boolean default: false description: >- When `true`, prevents overwriting existing non-empty field values for all contacts in the batch. New values are only written to fields that are currently empty or unset. examples: basic: summary: Basic batch upsert value: contacts: - email: jane@example.com subscriptionStatus: SUBSCRIBED fields: first_name: Jane last_name: Smith - email: bob@example.com subscriptionStatus: SUBSCRIBED fields: first_name: Bob last_name: Jones companyFields: company_name: Acme Corp enrichment: summary: Enrichment mode value: preserveExistingFields: true contacts: - email: jane@example.com fields: first_name: Jane phone: +1-555-0100 responses: '200': description: Batch processed. Check each result item for individual outcomes. content: application/json: schema: type: object properties: data: type: object required: - results properties: results: type: array description: >- An array of result objects in the same order as the input `contacts` array. items: type: object required: - success properties: success: type: boolean description: '`true` if the contact was successfully upserted.' cnvContactId: type: string format: uuid description: The Conversion contact ID. Present on success. contactCreated: type: boolean description: >- `true` if a new contact was created, `false` if updated. Present on success. error: type: string description: >- A machine-readable error code. Present on failure. message: type: string description: >- A human-readable error description. Present on failure. examples: all-success: summary: All contacts upserted value: data: results: - success: true cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 contactCreated: true - success: true cnvContactId: f9e8d7c6-b5a4-3210-fedc-ba9876543210 contactCreated: false partial-failure: summary: Partial failure value: data: results: - success: true cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 contactCreated: true - success: false error: invalid_email message: 'invalid email format: not-an-email' '400': description: The request was malformed. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid-request: summary: Invalid request body value: error: code: invalid_request message: request validation failed '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 '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 contacts 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__`. ````