> ## Documentation Index > Fetch the complete documentation index at: https://docs.oration.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Customers > Queues a batch import job for customer records. Use `strategy=upsert` to merge existing customers by identifier or contact fields instead of inserting only new records. # Creating Customers This endpoint allows you to create customers. ## Request Body The request body should contain a `customers` array with the customer information you want to create. Each customer object in the array should include the following fields: | Field | Type | Required | Description | | ----------- | --------------------------------- | -------- | ------------------------------------------------------------------ | | name | string | No | The customer's full name | | phoneNumber | string | No | The customer's phone number in E.164 format (e.g., `+12345678901`) | | email | string | No | The customer's email address | | identifier | string | Yes | A unique identifier for the customer in your system | | metadata | object/string/number/boolean/null | No | Additional data about the customer that you want to store | | priority | integer | No | Calling priority for the customer. Default: 5. Ascending order. | You can use `priority` to control how the customers are picked during campaign runs. It is calculated in ascending order. **Lower the value, higher the priority. 0 is the highest priority.** In addition to the `customers` array, the request body can include the following top-level parameters: | Parameter | Type | Required | Description | | --------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | strategy | string | No | The strategy to use when creating customers. Can be `upsert` or `insert`. Defaults to `insert` | | partial | boolean | No | When set to `true`, allows partial batch processing. Only valid when `strategy` is set to `insert`. This ensures customers without errors are still inserted even if others in the batch fail. | ## Response Structure The response includes the job ID. You can use this job ID to check the status of the job. | Field | Type | Description | | ----- | ------ | -------------------------------- | | jobId | string | The unique identifier of the job | ## OpenAPI ````yaml POST /customers/batch openapi: 3.1.0 info: title: Oration AI Webhooks description: >- Webhook events for Oration AI platform - AI agents, conversations, and voice interactions version: 1.0.0 contact: name: Oration AI Support url: https://oration.ai/support email: support@oration.ai servers: - url: https://www.oration.ai/api/v2 description: Production API base URL security: [] tags: - name: conversations description: Create conversations and inspect conversation records. - name: customers description: >- Bulk import and manage customer records used by campaigns and outbound workflows. - name: jobs description: >- Track asynchronous jobs created by long-running import or processing requests. externalDocs: description: Product and integration documentation url: https://docs.oration.ai paths: /customers/batch: post: tags: - customers summary: Bulk create or upsert customers description: >- Queues a batch import job for customer records. Use `strategy=upsert` to merge existing customers by identifier or contact fields instead of inserting only new records. operationId: lambda-workspaces-customer-createBatch parameters: - in: header name: x-api-key description: Workspace API key used for server-to-server authentication. example: ora_live_xxxxxxxxxxxxx schema: type: string required: true - in: header name: x-workspace-slug description: >- Human-readable workspace slug. Provide this or `x-workspace-id` depending on your integration setup. example: acme-support schema: type: string - in: header name: x-workspace-id description: Workspace UUID. Useful when the workspace slug is not available. example: 6f8c7d9d-34e2-4f42-9f5d-8f3c5b16a6af schema: type: string requestBody: required: true description: Customer records to import in a single async batch job. content: application/json: schema: type: object description: >- Request body for asynchronously importing or upserting customer records. properties: customers: type: array description: Customer records to create or update. items: type: object description: Single customer import record. properties: name: type: string description: Customer display name. nullable: true phoneNumber: type: string description: Primary phone number for the customer. minLength: 1 email: type: string description: Primary email address for the customer. format: email identifier: type: string description: >- External unique identifier used for deduplication and reconciliation. metadata: description: Arbitrary metadata stored on the customer record. nullable: true anyOf: - anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object additionalProperties: {} - type: array items: {} source: description: >- Origin metadata describing how the customer entered the system. oneOf: - type: object properties: method: type: string enum: - api required: - method - type: object properties: method: type: string enum: - manual sourceFile: type: string minLength: 1 required: - method - sourceFile - type: object properties: method: type: string enum: - integration integrationProviderId: type: string format: uuid integrationConnectionId: type: string format: uuid externalId: type: string required: - method - integrationProviderId - integrationConnectionId default: method: api priority: type: number description: >- Relative priority used by downstream workflows such as campaign scheduling. default: 5 isDoNotDisturbEnabled: type: boolean description: >- If true, the customer should not be contacted unless a request explicitly bypasses DND. nullable: true id: type: string description: Optional customer UUID when importing known records. format: uuid required: - identifier strategy: type: string description: >- Whether to only insert new customers or upsert matching records. enum: - upsert - insert default: insert partial: type: boolean description: >- If true, valid records are accepted even when some records in the batch fail validation. default: false required: - customers examples: upsertCustomers: summary: Upsert two customers and allow partial success value: customers: - identifier: crm-1001 name: Ava Johnson phoneNumber: '+14155550100' email: ava@example.com priority: 9 isDoNotDisturbEnabled: true metadata: segment: vip city: San Francisco - identifier: crm-1002 name: Noah Lee phoneNumber: '+14155550101' source: method: api strategy: upsert partial: true responses: '200': description: Customer import job created successfully. content: application/json: schema: type: object description: Async job handle returned after scheduling a customer import. properties: jobId: type: string description: >- Identifier of the background job that tracks import progress. example: jobId: 5135bfe3-b2c7-41f3-a44f-f4b58e7384df '400': description: Invalid input data content: application/json: schema: $ref: '#/components/schemas/error.BAD_REQUEST' '401': description: Authorization not provided content: application/json: schema: $ref: '#/components/schemas/error.UNAUTHORIZED' '403': description: Insufficient access content: application/json: schema: $ref: '#/components/schemas/error.FORBIDDEN' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR' security: - Authorization: [] components: schemas: error.BAD_REQUEST: type: object properties: message: type: string description: The error message example: Invalid input data code: type: string description: The error code example: BAD_REQUEST issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Invalid input data error (400) description: The error information example: code: BAD_REQUEST message: Invalid input data issues: [] error.UNAUTHORIZED: type: object properties: message: type: string description: The error message example: Authorization not provided code: type: string description: The error code example: UNAUTHORIZED issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Authorization not provided error (401) description: The error information example: code: UNAUTHORIZED message: Authorization not provided issues: [] error.FORBIDDEN: type: object properties: message: type: string description: The error message example: Insufficient access code: type: string description: The error code example: FORBIDDEN issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Insufficient access error (403) description: The error information example: code: FORBIDDEN message: Insufficient access issues: [] error.INTERNAL_SERVER_ERROR: type: object properties: message: type: string description: The error message example: Internal server error code: type: string description: The error code example: INTERNAL_SERVER_ERROR issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Internal server error error (500) description: The error information example: code: INTERNAL_SERVER_ERROR message: Internal server error issues: [] securitySchemes: Authorization: type: http scheme: bearer bearerFormat: JWT description: >- Bearer token issued for an authenticated Oration user or service account. ````