AlterLabAPI Reference
Auto-generated
Contact Lists
API reference for contact lists endpoints.
Auto-generated
This page was generated from the OpenAPI spec. Run
make generate-docs to refresh after spec changes.POST /api/v1/contact-lists
POST
/api/v1/contact-listsCreate Contact List
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Required | Display name for the list |
| description | string | Optional | description |
| processor_notice_accepted | boolean | Required | Must be True. Owner acknowledges that AlterLab is a data processor under GDPR/CCPA and that the owner is responsible for lawful contact collection. |
| auto_delete_days | integer | Optional | auto_delete_days |
Request Example
Bash
curl -X POST https://api.alterlab.io/api/v1/contact-lists \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "example_name",
"processor_notice_accepted": false
}'Response Example
JSON
{
"status": "ok"
}GET /api/v1/contact-lists
GET
/api/v1/contact-listsList Contact Lists
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| page | integer | Optional | pageDefault: 1 |
| limit | integer | Optional | limitDefault: 20 |
| q | string | Optional | q |
Request Example
Bash
curl -X GET https://api.alterlab.io/api/v1/contact-lists \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"Response Example
JSON
{
"lists": [],
"total": 0,
"page": 0,
"limit": 0,
"total_pages": 0
}DELETE /api/v1/contact-lists/erasure
DELETE
/api/v1/contact-lists/erasureErase Contact
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
string | Required | Email address to erase |
Request Example
Bash
curl -X DELETE 'https://api.alterlab.io/api/v1/contact-lists/erasure?email=<email>' \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"Response Example
JSON
{
"email": "example",
"contacts_deleted": 0,
"lists_affected": 0
}GET /api/v1/contact-lists/policy
GET
/api/v1/contact-lists/policyGet Processor Policy
Request Example
Bash
curl -X GET https://api.alterlab.io/api/v1/contact-lists/policy \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"Response Example
JSON
{
"status": "ok"
}GET /api/v1/contact-lists/{list_id}
GET
/api/v1/contact-lists/{list_id}Get Contact List
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| list_id | string | Required | list_id |
Request Example
Bash
curl -X GET https://api.alterlab.io/api/v1/contact-lists/<list_id> \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"Response Example
JSON
{
"id": "example",
"name": "example",
"description": "example",
"processor_notice_accepted": true,
"auto_delete_days": "example",
"contact_count": 0
}PATCH /api/v1/contact-lists/{list_id}
PATCH
/api/v1/contact-lists/{list_id}Update Contact List
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| list_id | string | Required | list_id |
| name | string | Optional | name |
| description | string | Optional | description |
| auto_delete_days | integer | Optional | auto_delete_days |
Request Example
Bash
curl -X PATCH https://api.alterlab.io/api/v1/contact-lists/<list_id> \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"Response Example
JSON
{
"id": "example",
"name": "example",
"description": "example",
"processor_notice_accepted": true,
"auto_delete_days": "example",
"contact_count": 0
}DELETE /api/v1/contact-lists/{list_id}
DELETE
/api/v1/contact-lists/{list_id}Delete Contact List
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| list_id | string | Required | list_id |
Request Example
Bash
curl -X DELETE https://api.alterlab.io/api/v1/contact-lists/<list_id> \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"Response Example
JSON
{
"status": "ok"
}POST /api/v1/contact-lists/{list_id}/contacts
POST
/api/v1/contact-lists/{list_id}/contactsAdd Contact
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| list_id | string | Required | list_id |
string | Required | ||
| name | string | Optional | name |
| company | string | Optional | company |
| custom_fields | object | Optional | Custom Fields |
| status | string | Optional | One of: new/contacted/replied/converted/bounced/unsubscribedDefault: new |
| tags | string[] | Optional | Tags |
| consent_basis | "legitimate_interest" | "contract" | "consent" | "none" | Optional | GDPR-lawful basis for sending marketing email. |
| data_source | string | Optional | How this contact was collected: manual, csv_import, workflow, apiDefault: manual |
| source_url | string | Optional | source_url |
| source_workflow_id | string | Optional | source_workflow_id |
Request Example
Bash
curl -X POST https://api.alterlab.io/api/v1/contact-lists/<list_id>/contacts \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "example_email",
"status": "example_status"
}'Response Example
JSON
{
"status": "ok"
}GET /api/v1/contact-lists/{list_id}/contacts
GET
/api/v1/contact-lists/{list_id}/contactsList Contacts
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| list_id | string | Required | list_id |
| page | integer | Optional | pageDefault: 1 |
| limit | integer | Optional | limitDefault: 50 |
| status | string | Optional | status |
| q | string | Optional | q |
Request Example
Bash
curl -X GET https://api.alterlab.io/api/v1/contact-lists/<list_id>/contacts \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"Response Example
JSON
{
"contacts": [],
"total": 0,
"page": 0,
"limit": 0,
"total_pages": 0
}PATCH /api/v1/contact-lists/{list_id}/contacts/{contact_id}
PATCH
/api/v1/contact-lists/{list_id}/contacts/{contact_id}Update Contact
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| list_id | string | Required | list_id |
| contact_id | string | Required | contact_id |
| name | string | Optional | name |
| company | string | Optional | company |
| custom_fields | object | Optional | custom_fields |
| status | string | Optional | status |
| tags | string[] | Optional | tags |
| consent_basis | "legitimate_interest" | "contract" | "consent" | "none" | Optional | GDPR-lawful basis for sending marketing email. |
Request Example
Bash
curl -X PATCH https://api.alterlab.io/api/v1/contact-lists/<list_id>/contacts/<contact_id> \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"Response Example
JSON
{
"id": "example",
"list_id": "example",
"email": "example",
"name": "example",
"company": "example",
"custom_fields": {}
}GET /api/v1/contact-lists/{list_id}/export
GET
/api/v1/contact-lists/{list_id}/exportExport Contacts
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| list_id | string | Required | list_id |
Request Example
Bash
curl -X GET https://api.alterlab.io/api/v1/contact-lists/<list_id>/export \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"Response Example
JSON
{
"status": "ok"
}POST /api/v1/contact-lists/{list_id}/import
POST
/api/v1/contact-lists/{list_id}/importImport contacts from a CSV file
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| list_id | string | Required | list_id |
Request Example
Bash
curl -X POST https://api.alterlab.io/api/v1/contact-lists/<list_id>/import \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"Response Example
JSON
{
"list_id": "example",
"imported": 0,
"skipped": 0,
"errors": 0,
"error_samples": [],
"truncated": true
}