Skip to main content
Contacts represent the people in your project. Every email address you send to or track an event for is automatically upserted as a contact.
All contact endpoints require a secret key (sk_*).

​
List contacts

GET /contacts Returns a cursor-paginated list of contacts for the authenticated project.

​
Query parameters

​
limit
number
default:"20"
Number of contacts to return per page. Maximum 100.
​
cursor
string
Pagination cursor returned from a previous response. Omit on the first request.
​
search
string
Filter contacts by email address (partial match).

​
Response

​
contacts
array
required
Array of contact objects.
​
cursor
string
Cursor to pass as cursor on the next request. null when there are no more pages.
​
hasMore
boolean
true when additional pages are available.
​
total
integer
Total number of contacts. Only included on the first page (when no cursor is provided).
Example
curl --request GET \
  --url 'https://next-api.useplunk.com/contacts?limit=20' \
  --header 'Authorization: Bearer sk_live_yourkey'
200
{
  "contacts": [
    {
      "id": "clx_contact_abc123",
      "email": "[email protected]",
      "subscribed": true,
      "data": { "plan": "pro" },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-10T08:00:00.000Z"
    }
  ],
  "cursor": "clx_contact_def456",
  "hasMore": true,
  "total": 1042
}

​
Create contact

POST /contacts Creates a new contact or updates an existing one (upsert by email address).

​
Body parameters

​
email
string
required
Contact email address. Used as the unique identifier for upsert.
​
subscribed
boolean
default:"true"
Subscription status for marketing emails.
​
data
object
Custom key-value data to store on the contact. Merged with any existing data.

​
Response

Returns the contact object. HTTP 201 when a new contact was created; 200 when an existing contact was updated.
​
id
string
Contact ID.
​
email
string
Contact email address.
​
subscribed
boolean
Subscription status.
​
data
object
Custom contact data.
​
createdAt
string
ISO 8601 creation timestamp.
​
updatedAt
string
ISO 8601 last-updated timestamp.
​
_meta
object
Example
curl --request POST \
  --url https://next-api.useplunk.com/contacts \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]",
    "subscribed": true,
    "data": {
      "firstName": "Jane",
      "plan": "premium"
    }
  }'
201
{
  "id": "clx_contact_abc123",
  "email": "[email protected]",
  "subscribed": true,
  "data": { "firstName": "Jane", "plan": "premium" },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "_meta": { "isNew": true, "isUpdate": false }
}

​
Get contact

GET /contacts/:id Retrieves a single contact by ID.

​
Path parameters

​
id
string
required
The contact ID.

​
Response

Returns the contact object.
Example
curl --request GET \
  --url https://next-api.useplunk.com/contacts/clx_contact_abc123 \
  --header 'Authorization: Bearer sk_live_yourkey'
200
{
  "id": "clx_contact_abc123",
  "email": "[email protected]",
  "subscribed": true,
  "data": { "plan": "premium" },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-10T08:00:00.000Z"
}

​
Update contact

PATCH /contacts/:id Updates a contact’s subscription status or custom data fields.

​
Path parameters

​
id
string
required
The contact ID.

​
Body parameters

​
email
string
New email address for the contact.
​
subscribed
boolean
Updated subscription status.
​
data
object
Custom data fields to merge into the contact’s existing data.

​
Response

Returns the updated contact object.
Example
curl --request PATCH \
  --url https://next-api.useplunk.com/contacts/clx_contact_abc123 \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{
    "subscribed": false,
    "data": { "plan": "free" }
  }'
200
{
  "id": "clx_contact_abc123",
  "email": "[email protected]",
  "subscribed": false,
  "data": { "plan": "free" },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-15T12:00:00.000Z"
}

​
Delete contact

DELETE /contacts/:id Permanently deletes a contact and all associated data.
This action is irreversible. All events, email history, and segment memberships for the contact are removed.

​
Path parameters

​
id
string
required
The contact ID.

​
Response

Returns 204 No Content on success.
Example
curl --request DELETE \
  --url https://next-api.useplunk.com/contacts/clx_contact_abc123 \
  --header 'Authorization: Bearer sk_live_yourkey'

​
Import contacts (CSV)

POST /contacts/import Queues a CSV file for bulk contact import. The import runs asynchronously in the background.
The request must use multipart/form-data with the CSV file in a field named file. Maximum file size is 5 MB. The CSV must have at minimum an email column.

​
Body (multipart/form-data)

​
file
file
required
CSV file. Must include an email column. Additional columns are stored as contact data fields.

​
Response

Returns 202 Accepted with a jobId you can poll for status.
​
message
string
Confirmation message.
​
jobId
string
Use this to check import progress.
Example
curl --request POST \
  --url https://next-api.useplunk.com/contacts/import \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --form '[email protected]'

​
Get import status

GET /contacts/import/:jobId Returns the status of a CSV import job.

​
Path parameters

​
jobId
string
required
The job ID returned from the import request.

​
Bulk subscribe

POST /contacts/bulk-subscribe Queues a bulk subscribe operation for up to 1,000 contacts.

​
Body parameters

​
contactIds
string[]
required
Array of contact IDs to subscribe. Maximum 1,000 per request.

​
Response

Returns 202 Accepted with a jobId.
Example
curl --request POST \
  --url https://next-api.useplunk.com/contacts/bulk-subscribe \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{ "contactIds": ["clx_abc", "clx_def"] }'

​
Bulk unsubscribe

POST /contacts/bulk-unsubscribe Queues a bulk unsubscribe operation for up to 1,000 contacts.

​
Body parameters

​
contactIds
string[]
required
Array of contact IDs to unsubscribe. Maximum 1,000 per request.

​
Bulk delete

POST /contacts/bulk-delete Queues a bulk delete operation for up to 1,000 contacts.
Bulk delete is irreversible. All event history and segment memberships for the deleted contacts are also removed.

​
Body parameters

​
contactIds
string[]
required
Array of contact IDs to delete. Maximum 1,000 per request.

​
Get bulk action status

GET /contacts/bulk/:jobId Returns the status of a bulk subscribe, unsubscribe, or delete job.

​
Path parameters

​
jobId
string
required
The job ID returned from the bulk operation request.

Build docs developers (and LLMs) love

Get started for freeTalk to us