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",
"brand_id": "7c1de5f0-9a42-4b6d-8e33-2f5a9c7b1e64",
"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"
}
]
}
}
'{
"success": true,
"data": {
"list_id": "3f7a9c1e-8b24-4d6f-a2e5-9c7b3f1a8d42",
"purpose": "audience",
"name": "Spring Outreach List",
"status": "processing",
"total_rows": 12500,
"channels": [
"text"
],
"imported_via_api": true
}
}Import List
The one list import: phones, emails, or both from one CSV you host. The platform fetches source_url (HTTPS only, at most 50 MB, text/csv, application/csv, or text/plain), checks the columns you named against the file’s headers and checks that the first rows of each named column hold phone numbers or email addresses, and returns 202 before writing a row. Nothing is written when a check fails.
Columns. Send phone_column, email_column, or both (they must differ). There is no automatic email-column detection: name the column. Without merge_tags, every column other than the chosen ones becomes a merge tag automatically. With merge_tags, phone numbers map only the columns you name, while emails map the named columns and also every remaining column by its default name. Custom field names for emails must match ^[a-z][a-z0-9_]{0,63}$.
Purpose. audience (the default) makes ONE list. Both sides are polled on GET /contact-lists/{id}: import for the phone numbers and email for the emails (email.status is processing until ready or failed, with counts and removed_at_upload). An email-only audience is organization-wide even when you send brand_id. consent (where the addresses came from) is optional: it is allowed only for an audience with an email_column, and any other combination returns 400. Omit it and no consent record is stored. Unknown top-level fields in the request body are ignored; unknown keys inside merge_tags and consent return 400. Every refusal happens before anything is stored. do_not_contact adds the phone numbers to an opt-out list and records the emails as unsubscribes for the organization; the unsubscribes appear on GET /email/suppressions once the background job finishes (minutes for a large file). A do-not-contact import returns no list_id.
Email access. email_column requires email to be enabled for the organization; otherwise the request returns 403 ENTITLEMENT_REQUIRED.
Replaces POST /email/lists/import, which was removed. To migrate: send name as list_name (now required); the mapping entry whose value is email becomes email_column; other mapping entries become merge_tags; consent, email_domain_id, and acquired carry over unchanged.
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",
"brand_id": "7c1de5f0-9a42-4b6d-8e33-2f5a9c7b1e64",
"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"
}
]
}
}
'{
"success": true,
"data": {
"list_id": "3f7a9c1e-8b24-4d6f-a2e5-9c7b3f1a8d42",
"purpose": "audience",
"name": "Spring Outreach List",
"status": "processing",
"total_rows": 12500,
"channels": [
"text"
],
"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.
16 - 200Body
HTTPS URL of the CSV, such as a presigned storage URL. At most 50 MB; text/csv, application/csv, or text/plain. Private and link-local addresses are refused, on every redirect.
Name for the list. Names do not have to be unique. For do_not_contact, the name of the opt-out list the phone numbers go to.
1 - 255Target 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. Ignored for the emails of an import: an email list is organization-wide or scoped to one sending domain (email_domain_id).
audience: a list you send to. do_not_contact: phone numbers become an opt-out list and emails become unsubscribes, both applied automatically to every send.
audience, do_not_contact The CSV header holding the phone number. Send this, email_column, or both. A header that is not in the file returns 400 PHONE_COLUMN_NOT_FOUND with details.headers.
1The CSV header holding the email address. Must differ from phone_column. A header that is not in the file returns 400 VALIDATION_ERROR with details: { field: "email_column", headers }. Requires email to be enabled for the organization.
1Maps 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, the phone side maps only the columns named; the email side maps the named columns and every remaining column by its default name. With an email_column, custom field names must match ^[a-z][a-z0-9_]{0,63}$ (lowercase, starting with a letter, at most 64 characters).
Show child attributes
Show child attributes
Optional. Where the email addresses came from. Allowed only when purpose is audience and email_column is set; sent with any other combination it returns 400. Omit it and no consent record is stored.
Show child attributes
Show child attributes
Scopes the emails to one sending domain. Omit or send null for an organization-wide list any email campaign can use. An unknown domain returns 404 NOT_FOUND.
Optional, default false. true marks the email addresses as purchased or rented. Acquired lists are not blocked from sending, but they are sent more gradually, warming up on half steps.