Lists and contact upload

Use list endpoints when an external system needs to create a Sonik dialer list and add contacts to it.

The flow is:

1. Call GET /users and choose the workspace user who should own the list.
2. Call POST /lists with a name and that user's ownerUserId.
3. Call POST /lists/{listId}/contacts with contacts to add to the list.
4. Call DELETE /lists/{listId}/contacts with an email or phoneNumber query parameter to remove contacts from the list.
5. Call GET /lists later to verify list metadata and current prospect count.
6. Call DELETE /lists/{listId} when the list is no longer needed.

Clients do not send workspaceId. The API key determines the workspace for every list and contact upload.

Create a List

POST /lists creates an empty dialer list in the authenticated workspace.

Request body:

{
  "name": "September outbound list",
  "ownerUserId": "22222222-2222-4222-8222-222222222222"
}

ownerUserId must be an existing non-deleted user in the same workspace as the API key. Use GET /users to discover valid user IDs.

Response body:

{
  "list": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "September outbound list",
    "source": "CSV",
    "ownerUserId": "22222222-2222-4222-8222-222222222222",
    "createdAt": "2026-09-07T09:00:00.000Z",
    "updatedAt": "2026-09-07T09:00:00.000Z",
    "prospectsCount": 0
  }
}

Upload Contacts

POST /lists/{listId}/contacts adds up to 100 contacts per request.

Request body:

{
  "contacts": [
    {
      "firstName": "Alex",
      "lastName": "Morgan",
      "phoneNumber": "+49 151 12345678",
      "email": "[email protected]",
      "companyName": "Example GmbH",
      "companyDomain": "example.com",
      "jobTitle": "Head of Sales",
      "linkedinUrl": "https://www.linkedin.com/in/alex-morgan",
      "customProperties": {
        "Favorite tool": "Apollo",
        "Customer tier": "Enterprise"
      }
    }
  ]
}

Each contact must include at least one supported field. Supported standard fields are firstName, lastName, phoneNumber, email, companyName, companyDomain, jobTitle, and linkedinUrl. A contact with at least one non-empty customProperties entry is also accepted without a standard field.

customProperties is an optional object containing string values. Property names and values are trimmed, blank values are ignored, and property names are case-sensitive. These properties are available as filters on the uploaded list and are displayed as read-only fields whenever the contact's battle card is opened, regardless of whether the active context is a manual, CSV, HubSpot, or Salesforce list.

Response body:

{
  "listId": "11111111-1111-4111-8111-111111111111",
  "acceptedContacts": 1,
  "totalProspects": 1
}

The upload endpoint reuses existing workspace prospects when a safe email or phone match already exists. Incoming custom properties are merged into the existing prospect, with incoming values taking precedence for matching property names. If a LinkedIn URL conflicts with the existing matched prospect, Sonik creates a separate prospect instead.

Remove Contacts

DELETE /lists/{listId}/contacts removes contacts from a dialer list by email or phone number.

Send exactly one query parameter:

Examples:

DELETE /lists/11111111-1111-4111-8111-111111111111/[email protected]
DELETE /lists/11111111-1111-4111-8111-111111111111/contacts?phoneNumber=%2B49%20151%2012345678

Response body:

{
  "listId": "11111111-1111-4111-8111-111111111111",
  "removedContacts": 1,
  "totalProspects": 0
}

If no attached contact matches the identifier, the endpoint returns removedContacts: 0. Removing a contact detaches it from the selected list only; it does not delete the workspace prospect record or remove it from other lists.

Delete a List

DELETE /lists/{listId} deletes the list and detaches all contacts from it. Contact records are preserved.

The endpoint returns 204 No Content after deletion.

List Existing Lists

GET /lists returns dialer lists newest first.

Use the API Reference for complete schemas, response headers, and error details.