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
}
'import requests
url = "https://www.oration.ai/api/v2/customers/batch"
payload = {
"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
}
headers = {
"x-api-key": "<x-api-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-api-key': '<x-api-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
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
})
};
fetch('https://www.oration.ai/api/v2/customers/batch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://www.oration.ai/api/v2/customers/batch",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"x-api-key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://www.oration.ai/api/v2/customers/batch"
payload := strings.NewReader("{\n \"customers\": [\n {\n \"identifier\": \"crm-1001\",\n \"name\": \"Ava Johnson\",\n \"phoneNumber\": \"+14155550100\",\n \"email\": \"ava@example.com\",\n \"priority\": 9,\n \"isDoNotDisturbEnabled\": true,\n \"metadata\": {\n \"segment\": \"vip\",\n \"city\": \"San Francisco\"\n }\n },\n {\n \"identifier\": \"crm-1002\",\n \"name\": \"Noah Lee\",\n \"phoneNumber\": \"+14155550101\",\n \"source\": {\n \"method\": \"api\"\n }\n }\n ],\n \"strategy\": \"upsert\",\n \"partial\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<x-api-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://www.oration.ai/api/v2/customers/batch")
.header("x-api-key", "<x-api-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"customers\": [\n {\n \"identifier\": \"crm-1001\",\n \"name\": \"Ava Johnson\",\n \"phoneNumber\": \"+14155550100\",\n \"email\": \"ava@example.com\",\n \"priority\": 9,\n \"isDoNotDisturbEnabled\": true,\n \"metadata\": {\n \"segment\": \"vip\",\n \"city\": \"San Francisco\"\n }\n },\n {\n \"identifier\": \"crm-1002\",\n \"name\": \"Noah Lee\",\n \"phoneNumber\": \"+14155550101\",\n \"source\": {\n \"method\": \"api\"\n }\n }\n ],\n \"strategy\": \"upsert\",\n \"partial\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://www.oration.ai/api/v2/customers/batch")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"customers\": [\n {\n \"identifier\": \"crm-1001\",\n \"name\": \"Ava Johnson\",\n \"phoneNumber\": \"+14155550100\",\n \"email\": \"ava@example.com\",\n \"priority\": 9,\n \"isDoNotDisturbEnabled\": true,\n \"metadata\": {\n \"segment\": \"vip\",\n \"city\": \"San Francisco\"\n }\n },\n {\n \"identifier\": \"crm-1002\",\n \"name\": \"Noah Lee\",\n \"phoneNumber\": \"+14155550101\",\n \"source\": {\n \"method\": \"api\"\n }\n }\n ],\n \"strategy\": \"upsert\",\n \"partial\": true\n}"
response = http.request(request)
puts response.read_body{
"jobId": "5135bfe3-b2c7-41f3-a44f-f4b58e7384df"
}{
"code": "BAD_REQUEST",
"message": "Invalid input data",
"issues": []
}{
"code": "UNAUTHORIZED",
"message": "Authorization not provided",
"issues": []
}{
"code": "FORBIDDEN",
"message": "Insufficient access",
"issues": []
}{
"code": "INTERNAL_SERVER_ERROR",
"message": "Internal server error",
"issues": []
}Customers
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.
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
}
'import requests
url = "https://www.oration.ai/api/v2/customers/batch"
payload = {
"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
}
headers = {
"x-api-key": "<x-api-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-api-key': '<x-api-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
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
})
};
fetch('https://www.oration.ai/api/v2/customers/batch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://www.oration.ai/api/v2/customers/batch",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"x-api-key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://www.oration.ai/api/v2/customers/batch"
payload := strings.NewReader("{\n \"customers\": [\n {\n \"identifier\": \"crm-1001\",\n \"name\": \"Ava Johnson\",\n \"phoneNumber\": \"+14155550100\",\n \"email\": \"ava@example.com\",\n \"priority\": 9,\n \"isDoNotDisturbEnabled\": true,\n \"metadata\": {\n \"segment\": \"vip\",\n \"city\": \"San Francisco\"\n }\n },\n {\n \"identifier\": \"crm-1002\",\n \"name\": \"Noah Lee\",\n \"phoneNumber\": \"+14155550101\",\n \"source\": {\n \"method\": \"api\"\n }\n }\n ],\n \"strategy\": \"upsert\",\n \"partial\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<x-api-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://www.oration.ai/api/v2/customers/batch")
.header("x-api-key", "<x-api-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"customers\": [\n {\n \"identifier\": \"crm-1001\",\n \"name\": \"Ava Johnson\",\n \"phoneNumber\": \"+14155550100\",\n \"email\": \"ava@example.com\",\n \"priority\": 9,\n \"isDoNotDisturbEnabled\": true,\n \"metadata\": {\n \"segment\": \"vip\",\n \"city\": \"San Francisco\"\n }\n },\n {\n \"identifier\": \"crm-1002\",\n \"name\": \"Noah Lee\",\n \"phoneNumber\": \"+14155550101\",\n \"source\": {\n \"method\": \"api\"\n }\n }\n ],\n \"strategy\": \"upsert\",\n \"partial\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://www.oration.ai/api/v2/customers/batch")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"customers\": [\n {\n \"identifier\": \"crm-1001\",\n \"name\": \"Ava Johnson\",\n \"phoneNumber\": \"+14155550100\",\n \"email\": \"ava@example.com\",\n \"priority\": 9,\n \"isDoNotDisturbEnabled\": true,\n \"metadata\": {\n \"segment\": \"vip\",\n \"city\": \"San Francisco\"\n }\n },\n {\n \"identifier\": \"crm-1002\",\n \"name\": \"Noah Lee\",\n \"phoneNumber\": \"+14155550101\",\n \"source\": {\n \"method\": \"api\"\n }\n }\n ],\n \"strategy\": \"upsert\",\n \"partial\": true\n}"
response = http.request(request)
puts response.read_body{
"jobId": "5135bfe3-b2c7-41f3-a44f-f4b58e7384df"
}{
"code": "BAD_REQUEST",
"message": "Invalid input data",
"issues": []
}{
"code": "UNAUTHORIZED",
"message": "Authorization not provided",
"issues": []
}{
"code": "FORBIDDEN",
"message": "Insufficient access",
"issues": []
}{
"code": "INTERNAL_SERVER_ERROR",
"message": "Internal server error",
"issues": []
}Creating Customers
This endpoint allows you to create customers.Request Body
The request body should contain acustomers 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) |
| 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. |
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 |
Authorizations
Bearer token issued for an authenticated Oration user or service account.
Headers
Workspace API key used for server-to-server authentication.
Human-readable workspace slug. Provide this or x-workspace-id depending on your integration setup.
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.
Customer records to create or update.
Show child attributes
Show child attributes
Whether to only insert new customers or upsert matching records.
Available options:
upsert, insert 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.
Identifier of the background job that tracks import progress.
⌘I