curl --request POST \
--url https://pub-api.conversion.ai/api/v2/campaigns/{campaignId}/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/campaigns/{campaignId}/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/campaigns/{campaignId}/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/campaigns/{campaignId}/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/campaigns/{campaignId}/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/campaigns/{campaignId}/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/campaigns/{campaignId}/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"
}
]
}
}{
"error": {
"code": "invalid_request",
"message": "request validation failed"
}
}{
"error": {
"code": "unauthorized",
"message": "API key is required"
}
}{
"error": {
"code": "export_not_enabled",
"message": "business is not authorized to use this endpoint"
}
}{
"error": {
"code": "campaign_not_found",
"message": "campaign not found"
}
}{
"error": {
"code": "internal_error",
"message": "failed to add contacts to campaign"
}
}Batch Add Contacts to Campaign
Add up to 1,000 contacts to a campaign 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/campaigns/{campaignId}/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/campaigns/{campaignId}/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/campaigns/{campaignId}/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/campaigns/{campaignId}/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/campaigns/{campaignId}/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/campaigns/{campaignId}/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/campaigns/{campaignId}/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"
}
]
}
}{
"error": {
"code": "invalid_request",
"message": "request validation failed"
}
}{
"error": {
"code": "unauthorized",
"message": "API key is required"
}
}{
"error": {
"code": "export_not_enabled",
"message": "business is not authorized to use this endpoint"
}
}{
"error": {
"code": "campaign_not_found",
"message": "campaign not found"
}
}{
"error": {
"code": "internal_error",
"message": "failed to add contacts to campaign"
}
}Authorizations
Your Conversion API key. Found in Settings > Integrations in the dashboard. Format: sk_live_<key_id>_<secret>.
Path Parameters
The ID of the campaign to add the contacts to.
Body
An array of contacts to add to the campaign. 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?