Campaign audience

A contact list holds the phone numbers a campaign calls. You build a list by uploading a CSV file: create the list to get a presigned upload URL, upload the file, wait for validation, then confirm the upload to import the contacts.

Base URL

https://api.persistence.dev

These endpoints are served under the public /v1 prefix.

Authentication

Every request requires a workspace API key in the X-API-Key header.

curl https://api.persistence.dev/v1/calls/contact-lists \
  --header "X-API-Key: $PERSISTENCE_API_KEY"

Endpoints

List contact lists

GET /v1/calls/contact-lists — page through contact lists.

Create contact list

POST /v1/calls/contact-lists — create a list and get a presigned upload URL.

Get contact list

GET /v1/calls/contact-lists/{id} — retrieve a list and its upload status.

Update contact list

PATCH /v1/calls/contact-lists/{id} — change a list name or type.

Delete contact list

DELETE /v1/calls/contact-lists/{id} — delete a list.

List contact list items

GET /v1/calls/contact-lists/{id}/items — page through the phone numbers in a list.

Create upload URL

POST /v1/calls/contact-lists/{id}/get-presign-url — get a presigned URL for a new file.

Confirm upload

POST /v1/calls/contact-lists/{id}/uploads/{uploadID}/confirm — import a validated upload.

Stream upload status

GET /v1/calls/contact-lists/{id}/uploads/{uploadID}/events — follow upload progress over SSE.

Upload a contact list

Create the list

Send POST /v1/calls/contact-lists with name, type, and the fileName of the CSV you intend to upload. The response returns the new list along with uploadUrl, uploadHeaders, and s3Key, plus an uploadDetails object whose id is the uploadID used by the remaining steps.

curl --request POST https://api.persistence.dev/v1/calls/contact-lists \
  --header "X-API-Key: $PERSISTENCE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Spring outreach",
    "type": "contacts",
    "fileName": "contacts.csv"
  }'

Upload the file

Send the CSV file directly to uploadUrl, including every header returned in uploadHeaders. This request goes to the storage provider, so do not send your API key with it.

curl --request PUT "$UPLOAD_URL" \
  --header "Content-Type: text/csv" \
  --upload-file contacts.csv

Wait for validation

After the file lands, the upload moves through the statuses below. Follow the progress with GET /v1/calls/contact-lists/{id}/uploads/{uploadID}/events, or poll GET /v1/calls/contact-lists/{id} and read uploadDetails.status.

Confirm the upload

Once the upload reaches validated, call POST /v1/calls/contact-lists/{id}/uploads/{uploadID}/confirm to import the rows into the list. Confirming before validation completes returns a 409.

curl --request POST \
  "https://api.persistence.dev/v1/calls/contact-lists/$LIST_ID/uploads/$UPLOAD_ID/confirm" \
  --header "X-API-Key: $PERSISTENCE_API_KEY"

To replace or extend the contents of an existing list, start at step 2 by requesting a fresh URL from POST /v1/calls/contact-lists/{id}/get-presign-url.

Contact list fields

Field	Type	Description
`id`	string	Contact list ID.
`name`	string	Contact list name.
`type`	string	List type: `contacts`, `dnd`, or `batch`.
`status`	string	List status: `draft`, `ready`, or `archived`.
`totalEntries`	integer	Number of entries in the list.
`uploadDetails`	object	The most recent upload for the list.
`createdAt`	string	Creation timestamp.
`updatedAt`	string	Last update timestamp.

Use contacts for the audience a campaign calls and dnd for numbers a campaign must skip.

Upload fields

uploadDetails describes the state of a file upload.

Field	Type	Description
`id`	string	Upload ID, used as the `uploadID` path parameter.
`status`	string	Current upload status.
`s3Key`	string	Storage key for the uploaded file.
`metadata`	object	Row counts for the upload.
`errors`	array	Errors recorded during validation.
`errorReportS3Key`	string	Storage key for the error report.
`errorReportUrl`	string	Download URL for the error report.
`uploadedAt`	string	Time the file was uploaded.
`validatedAt`	string	Time validation finished.
`processedAt`	string	Time the import finished.

metadata reports totalRows, validRows, invalidRows, duplicateRows, and importedRows.

Upload statuses

Status	Meaning
`uploaded`	The file has been received.
`validating`	The file is being checked.
`validated`	The file passed validation and can be confirmed.
`validation_failed`	The file failed validation.
`processing`	The confirmed upload is being imported.
`processed`	The import finished.
`failed`	The upload could not be processed.

When validation fails, errorReportUrl points to a report describing the rejected rows.

Track upload progress

GET /v1/calls/contact-lists/{id}/uploads/{uploadID}/events returns a server-sent event stream. Each event carries an eventId, an eventType, the current upload in data, and errorReportUrl when a report is available.

curl --no-buffer \
  "https://api.persistence.dev/v1/calls/contact-lists/$LIST_ID/uploads/$UPLOAD_ID/events" \
  --header "X-API-Key: $PERSISTENCE_API_KEY" \
  --header "Accept: text/event-stream"

The interactive playground on this page sends a normal request and shows a single event body. Use a client that supports server-sent events to consume the stream.

Pagination and filtering

GET /v1/calls/contact-lists accepts these query parameters.

Parameter	Type	Description
`page`	integer	Page number.
`perPage`	integer	Items per page.
`type`	string	Filter by list type, `contacts` or `dnd`.
`status`	string	Filter by list status.
`searchText`	string	Filter lists by text.

GET /v1/calls/contact-lists/{id}/items accepts page and perPage. Both endpoints return a paged object containing items, page, perPage, totalCount, column, order, and searchText. Each item in a list has a phoneNumber and a metadata object holding the other columns imported from the CSV file.

Errors

Errors return a code and an error message.

{
  "code": "not_found",
  "error": "contact list not found"
}

Status	Meaning
`400`	The request body or a path parameter is invalid.
`401`	The `X-API-Key` header is missing or invalid.
`403`	The key is not permitted to perform the operation.
`404`	The contact list or upload does not exist.
`409`	The list already exists, or the upload is not ready to be confirmed.

API reference

Agents

Calls

Accounts and workspaces

Billing

Campaigns

Telephony

Number pools

Knowledge bases

Campaign audience

Base URL

Authentication

Endpoints

List contact lists

Create contact list

Get contact list

Update contact list

Delete contact list

List contact list items

Create upload URL

Confirm upload

Stream upload status

Upload a contact list

Contact list fields

Upload fields

Upload statuses

Track upload progress

Errors

​Base URL

​Authentication

​Endpoints

List contact lists

Create contact list

Get contact list

Update contact list

Delete contact list

List contact list items

Create upload URL

Confirm upload

Stream upload status

​Upload a contact list

​Contact list fields

​Upload fields

​Upload statuses

​Track upload progress

​Pagination and filtering

​Errors

Base URL

Authentication

Endpoints

Upload a contact list

Contact list fields

Upload fields

Upload statuses

Track upload progress

Pagination and filtering

Errors