Conversation API
Read your support data from your own integration. Retrieve conversations and their history with standard authenticated JSON requests.
A read-only API
The API covers email and widget conversations, customer details, assignment, tags, message bodies, and files stored in OutcomeArc. Private notes and unsent drafts require an explicit key permission. It does not send replies, modify data, or run a migration into another platform for you.
https://app.outcomearc.com/api/v1Use HTTPS from a trusted server. All endpoints use GET and return application/json. IDs are UUID strings; timestamps are ISO-8601 values with a timezone. Missing optional values are null. Clients should tolerate new response fields within v1.
Authentication
- As a workspace owner or administrator, open Settings → API.
- Name the key and select the inboxes it may read. Optionally enable Include private notes, unsent drafts, and their attachments; this is off by default.
- Create the key and copy it once. Keep it in your server’s secret storage, for example as
OUTCOMEARC_API_KEY.
Authorization: Bearer <YOUR_API_KEY>Keys start with oa_api_, expire after 90 days, and can be revoked in Settings. Only a hash is stored. To rotate a key or change access, create a replacement and revoke the old key. Up to 50 active keys are allowed per workspace.
Access is checked on every request against the key’s selected inboxes and its creator’s current administrator role and inbox permissions. New inboxes are not automatically included. Deleted inboxes are excluded. A missing or inaccessible resource returns the same 404.
First request
curl --fail-with-body 'https://app.outcomearc.com/api/v1/inboxes' \
--header "Authorization: Bearer $OUTCOMEARC_API_KEY"Pagination & filters
Conversation, message, and attachment lists return data, pagination, and private_content_included. Lists are ordered oldest first by created_at, then ID. The private-content flag describes the key’s permission, not whether a particular page contains notes or drafts.
limit- Optional integer, 1–50. Default: 25.
cursor- Omit on the first request. For the next page, pass the previous response’s
pagination.next_cursorunchanged. Stop when it isnull.
Keep the same endpoint and filters between pages. You may reduce limit to handle large responses. Cursors are opaque continuation positions, not credentials; every page is authorized again. There is no offset ceiling, total count, or bulk-export job.
Conversation filters
These parameters apply only to GET /conversations and are combined with AND:
inbox_id- Required. One inbox ID returned by
/inboxes. statusall(default),open,pending,closed, orspam. All includes spam; the three individual status filters exclude spam. The app’s Active status isopenhere.created_after- Inclusive creation timestamp, for example
2026-01-01T00:00:00Z. created_before- Exclusive creation timestamp. Must be later than
created_afterwhen both are supplied. updated_after- Inclusive conversation-update timestamp. This is not a change feed for every customer, tag, or message edit.
URL-encode values, including + in timezone offsets. Unknown or duplicate query parameters are rejected. Lists are live, not point-in-time snapshots: concurrent imports, moves, edits, or deletions can change what is returned. Deduplicate by stable ID and reconcile after activity has stopped when completeness is required.
Inboxes
/inboxesReturns all currently accessible inboxes selected for this key, at most 50. This endpoint takes no query parameters and is not paginated. Each item has id, name, and email (nullable).
{
"data": [
{
"id": "22222222-2222-4222-8222-222222222222",
"name": "Support",
"email": "support@example.com"
}
]
}Conversations
/conversationsLists conversations in one granted inbox, including closed, spam, and AI-only widget conversations by default. Conversation records do not embed messages or attachment lists.
curl --fail-with-body --get 'https://app.outcomearc.com/api/v1/conversations' \
--header "Authorization: Bearer $OUTCOMEARC_API_KEY" \
--data-urlencode 'inbox_id=22222222-2222-4222-8222-222222222222' \
--data-urlencode 'status=all' \
--data-urlencode 'limit=25'{
"data": [
{
"id": "11111111-1111-4111-8111-111111111111",
"inbox_id": "22222222-2222-4222-8222-222222222222",
"subject": "Question about my account",
"status": "closed",
"is_spam": false,
"channel": "email",
"conversation_type": "human",
"priority": "normal",
"created_at": "2026-01-01T10:00:00+00:00",
"updated_at": "2026-01-02T11:00:00+00:00",
"last_message_at": "2026-01-02T11:00:00+00:00",
"closed_at": "2026-01-02T11:00:00+00:00",
"snoozed_until": null,
"external_source": null,
"external_id": null,
"customer": {
"id": "33333333-3333-4333-8333-333333333333",
"name": "Alex",
"email": "alex@example.com",
"external_id": null,
"timezone": "UTC",
"custom_data": {
"plan": "trial"
},
"created_at": "2026-01-01T10:00:00+00:00",
"updated_at": "2026-01-01T10:00:00+00:00"
},
"assignee": null,
"team": null,
"tags": [
{
"id": "44444444-4444-4444-8444-444444444444",
"name": "Account",
"color": "#64748b"
}
]
}
],
"pagination": {
"limit": 25,
"next_cursor": null
},
"private_content_included": false
}/conversations/{conversation_id}Returns one conversation as { "data": { …conversation fields… } }, without pagination. Takes no query parameters.
Conversation fields
id,inbox_id,subject,status,is_spam, andprioritydescribe the current conversation. Spam is a boolean, not a stored status.channelisemailorwidget.conversation_typedistinguisheshumanandaiconversations.created_at,updated_at, andlast_message_atare timestamps.closed_atandsnoozed_untilare nullable.external_sourceandexternal_idretain an imported conversation’s source identity when available. They are not OutcomeArc IDs.customerincludes ID, name, email, external ID, timezone, custom data, and creation/update timestamps. Private customer-profile notes are excluded. Widget identities may use a synthetic email address.assigneeisnullor an object withid,name, andemail.teamisnullor an object withidandname.tagsis an array ofid,name, andcolorobjects; an untagged conversation returns[].
Messages
/conversations/{conversation_id}/messagesReturns chronological message history. Supports limit and cursor. Page through this endpoint independently for each conversation.
{
"data": [
{
"id": "55555555-5555-4555-8555-555555555555",
"conversation_id": "11111111-1111-4111-8111-111111111111",
"kind": "email",
"direction": "inbound",
"body_text": "Can you help with my account?",
"body_html": "<p>Can you help with my account?</p>",
"delivery_status": "delivered",
"email_message_id": null,
"in_reply_to": null,
"created_at": "2026-01-01T10:00:00+00:00",
"updated_at": "2026-01-01T10:00:00+00:00",
"sent_at": null,
"author": {
"id": "33333333-3333-4333-8333-333333333333",
"name": "Alex",
"email": "alex@example.com",
"external_id": null
},
"recipients": {
"to": [
"support@example.com"
],
"cc": [],
"bcc": []
}
}
],
"pagination": {
"limit": 25,
"next_cursor": null
},
"private_content_included": false
}kinddistinguishes email, chat, note, and draft records.directionisinbound,outbound, orinternal. Notes, drafts, and internal messages are omitted unless private-content access was granted.body_textand nullablebody_htmlcontain the stored bodies without API truncation. An empty body means no content was retained in that format; the API does not invent missing text. Treat HTML as untrusted and sanitize it before rendering.authorcontains nullableid,name,email, andexternal_id. Stored source authors are retained when available; missing details remain null.recipientscontainsto,cc, andbccas retained by the source. Older records may have no recipients; imported values may be strings or address objects rather than a uniform address format.delivery_statusis the stored delivery state. Do not interpret a draft as sent.sent_at,email_message_id, andin_reply_toare nullable; creation and update timestamps are always included.
Raw provider payloads, internal metadata, original headers, widget session credentials, and audit events are not returned. Private-content permission cannot be enabled through a query parameter.
Attachments
/conversations/{conversation_id}/attachmentsLists attachment metadata with limit and cursor. Match message_id to the message list. Only files attached to visible, persisted messages are included; unattached upload staging is never exposed.
{
"data": [
{
"id": "66666666-6666-4666-8666-666666666666",
"conversation_id": "11111111-1111-4111-8111-111111111111",
"message_id": "55555555-5555-4555-8555-555555555555",
"file_name": "receipt.pdf",
"content_type": "application/pdf",
"byte_size": 10420,
"content_id": null,
"created_at": "2026-01-01T10:00:00+00:00"
}
],
"pagination": {
"limit": 25,
"next_cursor": null
},
"private_content_included": false
}byte_size is the stored size in bytes. content_id is nullable and identifies a CID inline image where retained. A source attachment that was never downloaded into OutcomeArc storage is not available through this endpoint.
/attachments/{attachment_id}/downloadRechecks key, inbox, and private-content access, then returns a private download link. Takes no query parameters. The API returns JSON, not a redirect or file bytes.
{
"data": {
"url": "https://storage.example.com/short-lived-signed-url",
"expires_in": 60
}
}Fetch the returned URL within 60 seconds without forwarding your API Authorization header to the storage host. Treat the URL as a secret. Request a fresh link if it expires. Already-issued links may remain usable for up to 60 seconds after key revocation. Deleted or unavailable files may fail when fetched.
Limits & errors
The workspace shares a limit of 120 requests per 60-second window across all its API keys. On 429, wait at least the Retry-After value (60 seconds) before retrying. Use bounded concurrency and backoff for temporary failures.
Responses are capped at 4 MiB. An oversized response returns 413, not truncated content. Retry with a smaller page, down to limit=1. If a single record still exceeds the cap, this API cannot return that record; do not treat the export as complete.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request / invalid_cursor | Invalid ID, filter, date, page size, or cursor. Correct the request before retrying. |
| 401 | unauthorized | Missing, invalid, expired, or revoked key; also applies if its creator no longer has an administrator role. |
| 404 | not_found / attachment_unavailable | Missing or inaccessible resource, unsupported route, or unavailable stored file. |
| 405 | method_not_allowed | Only GET is supported. |
| 413 | response_too_large | Response exceeds 4 MiB. Reduce page size. |
| 429 | rate_limited | Workspace budget exhausted. Respect Retry-After. |
| 503 | temporarily_unavailable | Temporary service or query failure. Retry later; narrow the date range or page size for expensive queries. |
{
"error": {
"code": "not_found",
"message": "Resource not found or not accessible to this key.",
"request_id": "request-identifier"
}
}API responses use Cache-Control: no-store. Error responses include a request ID for support; normal handler responses also include X-Request-Id. Infrastructure-level errors may use a different format. Never send credentials or customer message bodies with a diagnostic report.
Using the data in another platform
Discover inboxes, page through conversations, and retrieve each conversation’s message and attachment pages. Your integration is responsible for mapping these records to the destination platform’s import API, preserving private-note and draft visibility, and handling destination-specific limits and permissions.
Use OutcomeArc IDs as source identifiers to avoid duplicate imports. Do not send imported drafts or replay historical replies as new outbound email. This API provides ordinary resource reads, not a destination-specific connector, full workspace backup, or guaranteed point-in-time export.
Only retained data is available. Permanently erased conversations, unlinked customers, skipped source attachments, and history never stored in OutcomeArc cannot be reconstructed. For a complete migration, reconcile source and destination records and resolve every failed page or file download before considering the work finished.