Import Contact List
curl --request POST \
--url https://api.politicalcomms.com/v1/contact-lists/import \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"source_url": "https://example.com/path/to/list.csv",
"organization_id": "01HX0000000000000000000000",
"brand_id": "01HX0000000000000000000001",
"list_name": "Spring Outreach List",
"phone_column": "phone",
"merge_tags": {
"first_name": "first_name",
"last_name": "last_name",
"address": "street",
"address_line_2": "street2",
"city": "city",
"state": "state",
"zip": "zip",
"custom_fields": [
{
"csv_column": "donor_tier",
"merge_tag": "tier"
}
]
}
}
'import requests
url = "https://api.politicalcomms.com/v1/contact-lists/import"
payload = {
"source_url": "https://example.com/path/to/list.csv",
"organization_id": "01HX0000000000000000000000",
"brand_id": "01HX0000000000000000000001",
"list_name": "Spring Outreach List",
"phone_column": "phone",
"merge_tags": {
"first_name": "first_name",
"last_name": "last_name",
"address": "street",
"address_line_2": "street2",
"city": "city",
"state": "state",
"zip": "zip",
"custom_fields": [
{
"csv_column": "donor_tier",
"merge_tag": "tier"
}
]
}
}
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({
source_url: 'https://example.com/path/to/list.csv',
organization_id: '01HX0000000000000000000000',
brand_id: '01HX0000000000000000000001',
list_name: 'Spring Outreach List',
phone_column: 'phone',
merge_tags: {
first_name: 'first_name',
last_name: 'last_name',
address: 'street',
address_line_2: 'street2',
city: 'city',
state: 'state',
zip: 'zip',
custom_fields: [{csv_column: 'donor_tier', merge_tag: 'tier'}]
}
})
};
fetch('https://api.politicalcomms.com/v1/contact-lists/import', 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://api.politicalcomms.com/v1/contact-lists/import",
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([
'source_url' => 'https://example.com/path/to/list.csv',
'organization_id' => '01HX0000000000000000000000',
'brand_id' => '01HX0000000000000000000001',
'list_name' => 'Spring Outreach List',
'phone_column' => 'phone',
'merge_tags' => [
'first_name' => 'first_name',
'last_name' => 'last_name',
'address' => 'street',
'address_line_2' => 'street2',
'city' => 'city',
'state' => 'state',
'zip' => 'zip',
'custom_fields' => [
[
'csv_column' => 'donor_tier',
'merge_tag' => 'tier'
]
]
]
]),
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://api.politicalcomms.com/v1/contact-lists/import"
payload := strings.NewReader("{\n \"source_url\": \"https://example.com/path/to/list.csv\",\n \"organization_id\": \"01HX0000000000000000000000\",\n \"brand_id\": \"01HX0000000000000000000001\",\n \"list_name\": \"Spring Outreach List\",\n \"phone_column\": \"phone\",\n \"merge_tags\": {\n \"first_name\": \"first_name\",\n \"last_name\": \"last_name\",\n \"address\": \"street\",\n \"address_line_2\": \"street2\",\n \"city\": \"city\",\n \"state\": \"state\",\n \"zip\": \"zip\",\n \"custom_fields\": [\n {\n \"csv_column\": \"donor_tier\",\n \"merge_tag\": \"tier\"\n }\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://api.politicalcomms.com/v1/contact-lists/import")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"source_url\": \"https://example.com/path/to/list.csv\",\n \"organization_id\": \"01HX0000000000000000000000\",\n \"brand_id\": \"01HX0000000000000000000001\",\n \"list_name\": \"Spring Outreach List\",\n \"phone_column\": \"phone\",\n \"merge_tags\": {\n \"first_name\": \"first_name\",\n \"last_name\": \"last_name\",\n \"address\": \"street\",\n \"address_line_2\": \"street2\",\n \"city\": \"city\",\n \"state\": \"state\",\n \"zip\": \"zip\",\n \"custom_fields\": [\n {\n \"csv_column\": \"donor_tier\",\n \"merge_tag\": \"tier\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.politicalcomms.com/v1/contact-lists/import")
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 \"source_url\": \"https://example.com/path/to/list.csv\",\n \"organization_id\": \"01HX0000000000000000000000\",\n \"brand_id\": \"01HX0000000000000000000001\",\n \"list_name\": \"Spring Outreach List\",\n \"phone_column\": \"phone\",\n \"merge_tags\": {\n \"first_name\": \"first_name\",\n \"last_name\": \"last_name\",\n \"address\": \"street\",\n \"address_line_2\": \"street2\",\n \"city\": \"city\",\n \"state\": \"state\",\n \"zip\": \"zip\",\n \"custom_fields\": [\n {\n \"csv_column\": \"donor_tier\",\n \"merge_tag\": \"tier\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"list_id": "3f7a9c1e-8b24-4d6f-a2e5-9c7b3f1a8d42",
"name": "Spring Outreach List",
"status": "processing",
"total_rows": 12500,
"imported_via_api": true
}
}Contact Lists
Import Contact List
Asynchronous job: import a CSV from a client-supplied presigned S3 or public HTTPS URL. Returns immediately with the created resource; poll GET /contact-lists/{id} until status is ready. Columns other than the phone column become merge tags automatically unless you send merge_tags (see that parameter).
POST
/
contact-lists
/
import
Import Contact List
curl --request POST \
--url https://api.politicalcomms.com/v1/contact-lists/import \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"source_url": "https://example.com/path/to/list.csv",
"organization_id": "01HX0000000000000000000000",
"brand_id": "01HX0000000000000000000001",
"list_name": "Spring Outreach List",
"phone_column": "phone",
"merge_tags": {
"first_name": "first_name",
"last_name": "last_name",
"address": "street",
"address_line_2": "street2",
"city": "city",
"state": "state",
"zip": "zip",
"custom_fields": [
{
"csv_column": "donor_tier",
"merge_tag": "tier"
}
]
}
}
'import requests
url = "https://api.politicalcomms.com/v1/contact-lists/import"
payload = {
"source_url": "https://example.com/path/to/list.csv",
"organization_id": "01HX0000000000000000000000",
"brand_id": "01HX0000000000000000000001",
"list_name": "Spring Outreach List",
"phone_column": "phone",
"merge_tags": {
"first_name": "first_name",
"last_name": "last_name",
"address": "street",
"address_line_2": "street2",
"city": "city",
"state": "state",
"zip": "zip",
"custom_fields": [
{
"csv_column": "donor_tier",
"merge_tag": "tier"
}
]
}
}
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({
source_url: 'https://example.com/path/to/list.csv',
organization_id: '01HX0000000000000000000000',
brand_id: '01HX0000000000000000000001',
list_name: 'Spring Outreach List',
phone_column: 'phone',
merge_tags: {
first_name: 'first_name',
last_name: 'last_name',
address: 'street',
address_line_2: 'street2',
city: 'city',
state: 'state',
zip: 'zip',
custom_fields: [{csv_column: 'donor_tier', merge_tag: 'tier'}]
}
})
};
fetch('https://api.politicalcomms.com/v1/contact-lists/import', 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://api.politicalcomms.com/v1/contact-lists/import",
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([
'source_url' => 'https://example.com/path/to/list.csv',
'organization_id' => '01HX0000000000000000000000',
'brand_id' => '01HX0000000000000000000001',
'list_name' => 'Spring Outreach List',
'phone_column' => 'phone',
'merge_tags' => [
'first_name' => 'first_name',
'last_name' => 'last_name',
'address' => 'street',
'address_line_2' => 'street2',
'city' => 'city',
'state' => 'state',
'zip' => 'zip',
'custom_fields' => [
[
'csv_column' => 'donor_tier',
'merge_tag' => 'tier'
]
]
]
]),
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://api.politicalcomms.com/v1/contact-lists/import"
payload := strings.NewReader("{\n \"source_url\": \"https://example.com/path/to/list.csv\",\n \"organization_id\": \"01HX0000000000000000000000\",\n \"brand_id\": \"01HX0000000000000000000001\",\n \"list_name\": \"Spring Outreach List\",\n \"phone_column\": \"phone\",\n \"merge_tags\": {\n \"first_name\": \"first_name\",\n \"last_name\": \"last_name\",\n \"address\": \"street\",\n \"address_line_2\": \"street2\",\n \"city\": \"city\",\n \"state\": \"state\",\n \"zip\": \"zip\",\n \"custom_fields\": [\n {\n \"csv_column\": \"donor_tier\",\n \"merge_tag\": \"tier\"\n }\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://api.politicalcomms.com/v1/contact-lists/import")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"source_url\": \"https://example.com/path/to/list.csv\",\n \"organization_id\": \"01HX0000000000000000000000\",\n \"brand_id\": \"01HX0000000000000000000001\",\n \"list_name\": \"Spring Outreach List\",\n \"phone_column\": \"phone\",\n \"merge_tags\": {\n \"first_name\": \"first_name\",\n \"last_name\": \"last_name\",\n \"address\": \"street\",\n \"address_line_2\": \"street2\",\n \"city\": \"city\",\n \"state\": \"state\",\n \"zip\": \"zip\",\n \"custom_fields\": [\n {\n \"csv_column\": \"donor_tier\",\n \"merge_tag\": \"tier\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.politicalcomms.com/v1/contact-lists/import")
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 \"source_url\": \"https://example.com/path/to/list.csv\",\n \"organization_id\": \"01HX0000000000000000000000\",\n \"brand_id\": \"01HX0000000000000000000001\",\n \"list_name\": \"Spring Outreach List\",\n \"phone_column\": \"phone\",\n \"merge_tags\": {\n \"first_name\": \"first_name\",\n \"last_name\": \"last_name\",\n \"address\": \"street\",\n \"address_line_2\": \"street2\",\n \"city\": \"city\",\n \"state\": \"state\",\n \"zip\": \"zip\",\n \"custom_fields\": [\n {\n \"csv_column\": \"donor_tier\",\n \"merge_tag\": \"tier\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"list_id": "3f7a9c1e-8b24-4d6f-a2e5-9c7b3f1a8d42",
"name": "Spring Outreach List",
"status": "processing",
"total_rows": 12500,
"imported_via_api": true
}
}Authorizations
Authenticate every request by passing your API key in the X-API-Key header. Keys are scoped to your organization hierarchy.
Headers
Optional idempotency key: a unique string of 16-200 printable ASCII characters (a UUID is recommended). Retrying the write with the same key within 24 hours returns the stored response of the first call with an X-Idempotent-Replayed: true response header instead of executing it again. Reusing a key with a different request body returns 422 (IDEMPOTENCY_MISMATCH); a duplicate sent while the first call is still running returns 409 with a Retry-After header. Keys are scoped per endpoint and organization.
Required string length:
16 - 200Body
application/json
Target organization for the import. Defaults to the organization that owns the API key. Send it to target a sub-organization under an agency-tier parent; the API key is always limited to its own organization tree (otherwise the request returns 403 ORG_ACCESS_DENIED).
Optional. When provided, the list is scoped to this brand and the brand's organization is used, so a brand in an accessible sub-organization works without organization_id. A brand that does not belong to an organization your API key can access returns 404 BRAND_NOT_FOUND. If both are sent and the brand belongs to a different accessible organization than organization_id, the request returns 400 BRAND_ORG_MISMATCH.
Maps CSV columns to contact merge fields. Unknown keys are rejected with a 400. When omitted, or when it maps nothing, every non-phone column gets a merge tag automatically: a header that matches a standard field (first name, last name, address, address line 2, city, state, zip, including common aliases) gets the standard tag, and any other column gets a tag named after its header in lowercase with underscores (for example Donor Tier becomes {donor_tier}). When supplied, it is used exactly as sent and unlisted columns get no tag.
Show child attributes
Show child attributes