Contacts

Create, read, update, and delete contacts in your workspace. All endpoints require a Bearer token — see Authentication for details.

Overview

Method	Path	Description
`GET`	`/api/v1/contacts`	List contacts (paginated)
`POST`	`/api/v1/contacts`	Create a contact
`GET`	`/api/v1/contacts/:id`	Get a single contact
`PATCH`	`/api/v1/contacts/:id`	Update a contact (partial)
`DELETE`	`/api/v1/contacts/:id`	Delete a contact

List contacts

GET/api/v1/contacts

Returns a paginated list of contacts for the authenticated workspace.

Query parameters

Field	Type	Required	Description
`limit`	`number`	optional	Max contacts to return. Default 50, max 200.
`offset`	`number`	optional	Pagination offset. Default 0.
`status`	`string`	optional	'subscribed' or 'unsubscribed'. Omit for all.
`search`	`string`	optional	Filter contacts whose email contains this substring.

Response

"color:#79c0ff">curl "https://pristinesend.com/api/v1/contacts?limit=10&status=subscribed" \
  "color:#ff7b72">-H "Authorization: Bearer ps_live_YOUR_API_KEY"

Create a contact

POST/api/v1/contacts

Creates a new contact. Returns 409 Conflict if the email already exists in the workspace.

Request body

Field	Type	Required	Description
`email`	`string`	required	Contact email address. Must be unique per workspace.
`first_name`	`string`	optional	Contact's first name.
`last_name`	`string`	optional	Contact's last name.
`status`	`string`	optional	'subscribed' or 'unsubscribed'. Defaults to 'subscribed'.
`properties`	`object`	optional	Arbitrary key/value metadata. Must be a JSON object.

Response

"color:#79c0ff">curl "color:#ff7b72">-X POST https://pristinesend.com/api/v1/contacts \
  "color:#ff7b72">-H "Authorization: Bearer ps_live_YOUR_API_KEY" \
  "color:#ff7b72">-H "Content">-Type: application/json" \
  "color:#ff7b72">-d "color:#a5d6ff">'{
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "status": "subscribed",
    "properties": { "city": "Seattle" }
  }'

Get a contact

GET/api/v1/contacts/:id

Returns a single contact by UUID. Returns 404 if the contact doesn't exist or belongs to a different workspace.

"color:#79c0ff">curl https://pristinesend.com/api/v1/contacts/8e4f2b1c-... \
  "color:#ff7b72">-H "Authorization: Bearer ps_live_YOUR_API_KEY"

Update a contact

PATCH/api/v1/contacts/:id

Partially updates a contact. Only include the fields you want to change. The properties field is merged with existing properties rather than replaced. Email cannot be changed after creation.

Request body

Field	Type	Required	Description
`first_name`	`string`	optional	New first name.
`last_name`	`string`	optional	New last name.
`status`	`string`	optional	'subscribed' or 'unsubscribed'.
`properties`	`object`	optional	Properties to merge into existing properties. Email cannot be changed.

Response

"color:#79c0ff">curl "color:#ff7b72">-X PATCH https://pristinesend.com/api/v1/contacts/8e4f2b1c-... \
  "color:#ff7b72">-H "Authorization: Bearer ps_live_YOUR_API_KEY" \
  "color:#ff7b72">-H "Content">-Type: application/json" \
  "color:#ff7b72">-d "color:#a5d6ff">'{
    "status": "unsubscribed",
    "properties": { "tier": "pro" }
  }'

Delete a contact

DELETE/api/v1/contacts/:id

Permanently deletes a contact. Returns 204 No Content on success with no response body. Returns 404 if the contact doesn't exist.

"color:#79c0ff">curl "color:#ff7b72">-X DELETE https://pristinesend.com/api/v1/contacts/8e4f2b1c-... \
  "color:#ff7b72">-H "Authorization: Bearer ps_live_YOUR_API_KEY"

Error codes

All errors return a consistent JSON envelope:

{
  "error": {
    "code": "validation_error",
    "message": "Email is not a valid email address",
    "details": { "field": "email" }
  }
}

Status	code	When
`400`	`invalid_request`	Malformed JSON or invalid query params
`400`	`validation_error`	Missing required field or invalid value
`401`	`unauthorized`	Missing or invalid API key
`404`	`not_found`	Contact doesn't exist in this workspace
`409`	`conflict`	Email already exists in this workspace
`500`	`internal_error`	Unexpected server error — safe to retry

See the full Error codes reference for general API errors.