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 GET /lists later to verify list metadata and current prospect count.

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"
    }
  ]
}

Each contact must include at least one supported field. Supported fields are firstName, lastName, phoneNumber, email, companyName, companyDomain, jobTitle, and linkedinUrl.

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. If a LinkedIn URL conflicts with the existing matched prospect, Sonik creates a separate prospect instead.

List Existing Lists

GET /lists returns dialer lists newest first.

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