Skip to content

Contact List — Contacts (Collection)

List contacts collection and bulk CSV upload endpoint.

Endpoint

All verbs: /contact_list/<list>/contacts

GET /contact_list/<list>/contacts

Parameter Type Description
page int Page to return. Defaults to 1.
pagesize int Result page size. Range [10, 100]. Defaults to 10.

Returns: Contact collection and result count.

Example:

curl -u "username:api_key" -H "Accept: application/json" \
  "https://app.duo.pt/contact_list/{list_id}/contacts?page=1&pagesize=10"

Response:

{
  "success": true,
  "data": {
    "result": [
      {
        "contact_id": 17137542,
        "subscription_status": "PENDING",
        "bouncing": false,
        "telephone": "351910000001",
        "email": "contact@example.com"
      }
    ],
    "contact_list": {
      "id": 1,
      "owner": 1,
      "name": "Example...",
      "default_email_out": null,
      "unsubscribe_message": "You have been unsubscribed.",
      "email_out_custom_fields": null,
      "double_optin": false,
      "optout_allowed": false,
      "optout_category": null,
      "optin_email": null,
      "optin_sms": null,
      "shared_with_children": false,
      "read_shared_with_children": false,
      "segments": null
    },
    "filter": "",
    "page": 1,
    "pagesize": 10,
    "count": 1
  }
}

POST /contact_list/<list>/contacts

Bulk contact upload from a previously submitted CSV file. This is a two-step process:

  1. POST the CSV file to /contact_list/contacts/new/ — receive csv_file_path.
  2. POST to this endpoint with the csv_file_path.
Parameter Type Description
csv_file_path string Path from the previous upload step
mapping[<column_index>] int or string Column mapping: empty string (skip), "email", "telephone", or a custom field ID (int)
header int 0 = first row is a contact; 1 = first row is column headers
on_duplicate string ignore (skip existing) or update (update custom fields)
subscription_status string PENDING or SUBSCRIBED
offset int First line to process. Omit on first call. Use next_offset from previous response on subsequent calls.

Returns: A dictionary with:

Key Description
not_updated List of non-updated contacts
updated List of updated contacts
created List of created contacts
failed Dictionary of import failures keyed by contact
contact_list The contact list
next_offset Present if processing limit was hit — resubmit with this as offset to continue