Skip to main content
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"
      }
    ]
  }
}
'
{
  "success": true,
  "data": {
    "id": "cl_abc123",
    "list_name": "Spring Outreach List",
    "status": "importing",
    "created_at": "2025-03-15T10:00:00Z"
  }
}

Authorizations

​
X-API-Key
string
header
required

Authenticate every request by passing your API key in the X-API-Key header. Keys are scoped to your organization hierarchy.

Body

application/json
​
source_url
string<uri>
required
​
list_name
string
required
​
phone_column
string
required
​
organization_id
string

Target organization for the import. Defaults to the organization that owns the API key. Required only when targeting a sub-organization under an agency-tier parent; the API key must have access to the sub-organization (otherwise the request returns 403 ORG_ACCESS_DENIED).

​
brand_id
string

Optional. When provided, the list is scoped to this brand and the brand's organization is used (must match organization_id if both are sent — otherwise returns 400 BRAND_ORG_MISMATCH).

​
merge_tags
object

Response

Import accepted (poll the contact list for ready status)