Contact imports

A ContactImport is a named bulk insert of contacts. It’s the typical way to onboard a list — one POST creates all the contacts and the import becomes the unit you reference when enrolling a campaign.

Create an import

POST /contact_imports
Authorization: Bearer <key>
Content-Type: application/json
Idempotency-Key: optional-stable-key

{
  "contact_import": {
    "name": "Q2 OC contractors",
    "contacts": [
      { "email": "[email protected]", "first_name": "Ada", "last_name": "Lovelace", "company": "Acme" },
      { "email": "[email protected]", "first_name": "Babs",                            "company": "Acme" }
    ]
  }
}

Duplicate emails (across all your imports) are silently skipped — the response includes a skipped count when this happens.

Response

{ "id": "...", "name": "Q2 OC contractors", "record_count": 2 }

If some contacts were skipped due to duplicates:

{ "id": "...", "name": "Q2 OC contractors", "record_count": 1, "skipped": 1 }

List imports

GET /contact_imports
Authorization: Bearer <key>

[
  { "id": "...", "name": "Q2 OC contractors", "record_count": 9529, "created_at": "..." }
]

Show an import

GET /contact_imports/:id

{
  "id": "...",
  "name": "Q2 OC contractors",
  "record_count": 9529,
  "contact_count": 9529,
  "created_at": "..."
}

contact_count is the live count of associated Contact rows; record_count is the count at insertion time. They diverge if you delete contacts from the import after creation.

List contacts in an import

GET /contact_imports/:id/contacts

[
  { "id": "...", "email": "[email protected]", "first_name": "Ada", "company": "Acme", "unsubscribed_at": null, "created_at": "..." }
]

Delete an import

DELETE /contact_imports/:id

Cascades to all associated contacts (which in turn cascades to their enrollments).

Errors

Status	Code	When
404	contact_import_not_found	Unknown id or another account’s.
422	no_contacts_provided	POST with empty contacts array.
422	validation_failed	Missing import name or other validation.