Outbound API

Read-only programmatic access to your contacts, lists, drafts, and platform events. OpenAPI 3.1 spec: /api-docs/openapi.json

Authentication

Mint API keys at /admin/api-keys. Pass the secret on every request:

curl https://outbound.ustack.ai/api/v1/me \
  -H "Authorization: Bearer obk_live_<your-secret>"

Rate limits

60 requests per minute per API key (default).
120 requests per 30 seconds (burst window) for short bursts.
Response headers: X-RateLimit-Limit, X-RateLimit-Reset.
On exhaustion: 429 Too Many Requests with a Retry-After header.

Pagination

List endpoints return cursor-paginated results:

{
  "data": [ ... ],
  "nextCursor": "eyJpZCI6Ii4uLiIsInQiOiIyMDI2LTA1LTIzVDEwOjAwOjAwLjAwMFoifQ"
}

Pass ?cursor=<value> on the next call to fetch the next page. Default page size is 50; max is 200 (override with ?limit=).

Errors

Error responses use RFC 7807 application/problem+json:

{
  "type": "https://outbound.ustack.ai/errors/invalid-api-key",
  "title": "Invalid API key",
  "status": 401,
  "detail": "The presented API key is not valid."
}

Endpoints

Method	Path	Scope	Description
GET	/api/v1/me	any	Current API key and organization info.
GET	/api/v1/contacts	contacts.read	List contacts. Cursor-paginated. Filters: listId, qualificationStatus, q.
GET	/api/v1/contacts/:id	contacts.read	Single contact.
GET	/api/v1/contacts/:id/research	contacts.read	Cached L4 research dossier for a contact.
GET	/api/v1/lists	lists.read	List contact lists. Cursor-paginated. ?includeArchived=1 to include archived.
GET	/api/v1/lists/:id	lists.read	Single contact list.
GET	/api/v1/drafts	drafts.read	List drafts. Cursor-paginated. Filters: status, contactId.
GET	/api/v1/drafts/:id	drafts.read	Single draft (includes full body + engagement timeline).
GET	/api/v1/events	events.read	Paginated platform event log. Filter: eventType (single or comma-separated).

Multi-tenancy

Every API key belongs to exactly one organization. Every endpoint scopes all queries by the key's organizationId. There is no cross-tenant access path; a key minted by Org A cannot read Org B's data even if it knows another org's resource ids.

Webhooks (write-only push)

For event-driven integrations, register webhook endpoints at /admin/integrations/webhooks. Deliveries are signed with X-Outbound-Signature; verify with HMAC-SHA256(timestamp + "." + body, signingSecret).