Skip to main content
POST
/
v1
/
lists
/
:id
/
contacts
Add Contacts to List
curl --request POST \
  --url https://api.example.com/v1/lists/:id/contacts \
  --header 'Content-Type: application/json' \
  --data '
{
  "contact_ids": [
    {}
  ]
}
'
{
  "data": {
    "added": 123,
    "list_id": "<string>",
    "contact_count": 123
  }
}

​
Request

​
Path Parameters

​
id
string
required
List UUID

​
Headers

Authorization: Bearer wbk_your_api_key_here
Content-Type: application/json

​
Body Parameters

​
contact_ids
array
required
Array of contact UUIDs to add to the list

​
Response

​
data
object
Operation result
curl -X POST \
  https://nbkxaqxwvkgbddekwsma.supabase.co/functions/v1/api-gateway/v1/lists/abc-123/contacts \
  -H "Authorization: Bearer wbk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [
      "123e4567-e89b-12d3-a456-426614174000",
      "789e0123-e45b-67c8-a901-234567890abc"
    ]
  }'

​
Example Response

{
  "data": {
    "added": 2,
    "list_id": "abc12345-678d-90ef-1234-567890abcdef",
    "contact_count": 47
  }
}

​
Duplicate Handling

If a contact is already in the list, it will be silently skipped (not an error). The added count reflects only newly added contacts.

​
Example with Duplicates

If you try to add 5 contacts but 2 are already in the list: 
{
  "data": {
    "added": 3,
    "list_id": "abc-123",
    "contact_count": 50
  }
}

​
Bulk Operations

You can add up to 100 contacts in a single request: 
# Add 100 contacts at once
contact_ids = [...]  # List of up to 100 UUIDs
response = requests.post(
    f"{BASE_URL}/v1/lists/{LIST_ID}/contacts",
    headers=headers,
    json={"contact_ids": contact_ids}
)
Requests with more than 100 contact IDs will be rejected with a validation error.

​
Errors

StatusCodeDescription
400validation_errorInvalid contact IDs or exceeds 100 limit
401invalid_keyInvalid API key
403insufficient_permissionsMissing write permission
404not_foundList not found or not in your workspace
429rate_limitedRate limit exceeded

​
Example Error (Invalid Contact ID)

{
  "error": {
    "code": "validation_error",
    "message": "One or more contact IDs are invalid or not in your workspace",
    "details": {
      "invalid_ids": ["not-a-real-uuid"]
    }
  }
}