Guide

Contact Lists

Keep scraped contact data in managed lists with consent tracking, CSV import and export, and erasure.

Personal data

You are the controller of the contacts you store. Accept the processor notice, record a consent basis and use auto_delete_days to limit retention.

Create a List

POST /api/v1/contact-lists requires name and processor_notice_accepted. description and auto_delete_days are optional.

Bash

curl -X POST https://api.alterlab.io/api/v1/contact-lists   -H "X-API-Key: $ALTERLAB_API_KEY" -H "Content-Type: application/json"   -d '{"name": "Leads", "processor_notice_accepted": true, "auto_delete_days": 365}'

List, Get, Update and Delete

GET /api/v1/contact-lists (page, limit, q), GET, PATCH and DELETE /api/v1/contact-lists/{list_id}. PATCH accepts name, description and auto_delete_days.

Bash

curl "https://api.alterlab.io/api/v1/contact-lists?limit=20"   -H "X-API-Key: $ALTERLAB_API_KEY"

Add and List Contacts

POST /api/v1/contact-lists/{list_id}/contacts requires email and accepts name, company, custom_fields, status, tags, consent_basis, data_source, source_url and source_workflow_id. GET lists contacts with page, limit, status and q. PATCH /contacts/{contact_id} updates one.

Bash

curl -X POST https://api.alterlab.io/api/v1/contact-lists/LIST_ID/contacts   -H "X-API-Key: $ALTERLAB_API_KEY" -H "Content-Type: application/json"   -d '{"email": "jane@example.com", "tags": ["prospect"]}'

Import and Export

POST /api/v1/contact-lists/{list_id}/import takes a CSV file. GET /api/v1/contact-lists/{list_id}/export returns the contacts.

Bash

curl -X POST https://api.alterlab.io/api/v1/contact-lists/LIST_ID/import   -H "X-API-Key: $ALTERLAB_API_KEY"   -F "file=@contacts.csv"

Erasure and Processor Policy

DELETE /api/v1/contact-lists/erasure?email=... removes a contact everywhere on request. GET /api/v1/contact-lists/policy returns the processor policy you accept when creating a list.

Bash

curl -X DELETE "https://api.alterlab.io/api/v1/contact-lists/erasure?email=jane@example.com"   -H "X-API-Key: $ALTERLAB_API_KEY"

Secrets Platform Sub-Accounts

Last updated: June 2026