curl --request POST \
--url https://pub-api.conversion.ai/api/v2/audiences/{audienceId}/contacts/batch \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"contacts": [
{
"email": "jane@example.com"
},
{
"cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
{
"userId": "user_12345"
}
]
}
'import requests
url = "https://pub-api.conversion.ai/api/v2/audiences/{audienceId}/contacts/batch"
payload = { "contacts": [{ "email": "jane@example.com" }, { "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, { "userId": "user_12345" }] }
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
contacts: [
{email: 'jane@example.com'},
{cnvContactId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'},
{userId: 'user_12345'}
]
})
};
fetch('https://pub-api.conversion.ai/api/v2/audiences/{audienceId}/contacts/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://pub-api.conversion.ai/api/v2/audiences/{audienceId}/contacts/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([
'contacts' => [
[
'email' => 'jane@example.com'
],
[
'cnvContactId' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
],
[
'userId' => 'user_12345'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <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://pub-api.conversion.ai/api/v2/audiences/{audienceId}/contacts/batch"
payload := strings.NewReader("{\n \"contacts\": [\n {\n \"email\": \"jane@example.com\"\n },\n {\n \"cnvContactId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n },\n {\n \"userId\": \"user_12345\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
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://pub-api.conversion.ai/api/v2/audiences/{audienceId}/contacts/batch")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"contacts\": [\n {\n \"email\": \"jane@example.com\"\n },\n {\n \"cnvContactId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n },\n {\n \"userId\": \"user_12345\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://pub-api.conversion.ai/api/v2/audiences/{audienceId}/contacts/batch")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"contacts\": [\n {\n \"email\": \"jane@example.com\"\n },\n {\n \"cnvContactId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n },\n {\n \"userId\": \"user_12345\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"results": [
{
"added": true,
"cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
{
"added": false,
"error": "contact_not_found",
"message": "no contact found matching the provided identifier"
}
]
}
}Batch Add Contacts to Audience
Add up to 1,000 contacts to a static audience in a single request. Each contact is identified by cnvContactId, userId, or email and processed independently; the response includes a per-contact result indicating success or failure.
Request access. This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return
403 export_not_enabled.
curl --request POST \
--url https://pub-api.conversion.ai/api/v2/audiences/{audienceId}/contacts/batch \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"contacts": [
{
"email": "jane@example.com"
},
{
"cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
{
"userId": "user_12345"
}
]
}
'import requests
url = "https://pub-api.conversion.ai/api/v2/audiences/{audienceId}/contacts/batch"
payload = { "contacts": [{ "email": "jane@example.com" }, { "cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, { "userId": "user_12345" }] }
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
contacts: [
{email: 'jane@example.com'},
{cnvContactId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'},
{userId: 'user_12345'}
]
})
};
fetch('https://pub-api.conversion.ai/api/v2/audiences/{audienceId}/contacts/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://pub-api.conversion.ai/api/v2/audiences/{audienceId}/contacts/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([
'contacts' => [
[
'email' => 'jane@example.com'
],
[
'cnvContactId' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
],
[
'userId' => 'user_12345'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <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://pub-api.conversion.ai/api/v2/audiences/{audienceId}/contacts/batch"
payload := strings.NewReader("{\n \"contacts\": [\n {\n \"email\": \"jane@example.com\"\n },\n {\n \"cnvContactId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n },\n {\n \"userId\": \"user_12345\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
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://pub-api.conversion.ai/api/v2/audiences/{audienceId}/contacts/batch")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"contacts\": [\n {\n \"email\": \"jane@example.com\"\n },\n {\n \"cnvContactId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n },\n {\n \"userId\": \"user_12345\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://pub-api.conversion.ai/api/v2/audiences/{audienceId}/contacts/batch")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"contacts\": [\n {\n \"email\": \"jane@example.com\"\n },\n {\n \"cnvContactId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n },\n {\n \"userId\": \"user_12345\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"results": [
{
"added": true,
"cnvContactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
{
"added": false,
"error": "contact_not_found",
"message": "no contact found matching the provided identifier"
}
]
}
}Authorizations
Your Conversion API key. Found in Settings > Integrations in the dashboard. Format: sk_live_<key_id>_<secret>.
Path Parameters
The ID of the static audience to add the contacts to.
Body
An array of contacts to add to the audience. Each contact is identified by cnvContactId, userId, or email (resolution precedence: cnvContactId, then userId, then email).
1 - 1000 elementsShow child attributes
Show child attributes
Response
Batch processed. Check each result for per-contact success or failure.
Show child attributes
Show child attributes
Was this page helpful?