Skip to main content
POST
/
customers
/
batch
Bulk create or upsert customers
curl --request POST \
  --url https://www.oration.ai/api/v2/customers/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "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
}
'
{
  "jobId": "5135bfe3-b2c7-41f3-a44f-f4b58e7384df"
}

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.

​
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:
FieldTypeRequiredDescription
namestringNoThe customer’s full name
phoneNumberstringNoThe customer’s phone number in E.164 format (e.g., +12345678901)
emailstringNoThe customer’s email address
identifierstringYesA unique identifier for the customer in your system
metadataobject/string/number/boolean/nullNoAdditional data about the customer that you want to store
priorityintegerNoCalling 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:
ParameterTypeRequiredDescription
strategystringNoThe strategy to use when creating customers. Can be upsert or insert. Defaults to insert
partialbooleanNoWhen 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.
FieldTypeDescription
jobIdstringThe unique identifier of the job

Authorizations

​
Authorization
string
header
required

Bearer token issued for an authenticated Oration user or service account.

Headers

​
x-api-key
string
required

Workspace API key used for server-to-server authentication.

​
x-workspace-slug
string

Human-readable workspace slug. Provide this or x-workspace-id depending on your integration setup.

​
x-workspace-id
string

Workspace UUID. Useful when the workspace slug is not available.

Body

application/json

Customer records to import in a single async batch job.

Request body for asynchronously importing or upserting customer records.

​
customers
object[]
required

Customer records to create or update.

​
strategy
enum<string>
default:insert

Whether to only insert new customers or upsert matching records.

Available options:
upsert,
insert
​
partial
boolean
default:false

If true, valid records are accepted even when some records in the batch fail validation.

Response

Customer import job created successfully.

Async job handle returned after scheduling a customer import.

​
jobId
string

Identifier of the background job that tracks import progress.