Cases

A case is one tracked workflow against one counterparty. The current implementation stores it in DynamoDB, processes it asynchronously, and updates it as the thread evolves.

Core Fields

Field	What it means in the implementation
`caseId`	A random UUID generated when the case is created.
`clientReferenceId`	Your own identifier. Offload stores it and echoes it in `GET /cases/{id}` and webhook payloads.
`channel`	Validated as `EMAIL` or `SMS`, but the workflow is currently email-based. Use `EMAIL`.
`goal`	The business outcome Offload is trying to achieve. `objective` is required. `knowledge` can be a string or an object.
`counterparty`	The person or team Offload contacts. `address` and `name` are required.
`senderPersona`	How Offload should represent your side of the conversation. `name` is required.
`constraints`	Extra instructions the worker passes into the LLM prompt.
`resultSchema`	An optional object describing the shape of the final `result`. The API only validates that it is an object.
`metadata`	Opaque JSON stored on the case and echoed in webhook payloads. It is not currently returned by `GET /cases/{id}`.
`clientWebhookUrl`	Optional URL for outbound webhook delivery.

Runtime Fields

Field	Runtime meaning
`status`	One of `CREATED`, `RUNNING`, `INPUT_NEEDED`, `COMPLETED`, `FAILED`.
`attemptCount`	Number of outbound messages sent so far. After the initial outreach succeeds, this becomes `1`.
`maxAttempts`	Maximum number of automated follow-up attempts after the initial outreach.
`nextActionAt`	Unix timestamp in milliseconds for the next scheduled check or follow-up. When nothing is scheduled, the implementation uses `253402300799999`.
`attachments`	Inbound attachments seen on the case thread. Each entry is metadata only. Download URLs are minted separately.
`resultStatus`	A workflow outcome string such as `goal_achieved`, `max_retries`, `failed_rejected`, `BOUNCED`, `COMPLAINED`, or `REJECTED`. Treat this as an open set.
`result`	Structured JSON extracted when the case completes successfully.
`failureReason`	Present on some failures, especially provider delivery failures or explicit rejection-style outcomes.
`inputRequest`	Active human-in-the-loop question, if the case is paused.
`inputRequestId`	Stable identifier for the active input request.
`inputRequestStatus`	`PENDING`, `RESOLVED`, or `NONE`.

Defaults

If you omit them at creation time:

maxAttempts defaults to 3
followUpDelayHours defaults to 72

That means a default case can send:

1 initial outreach
up to 3 automated follow-ups

Attachments

Attachments are tracked separately from result:

they come from inbound reply events
they are stored as metadata on the case
they appear in webhook payloads and GET /cases/{id}
you fetch a fresh downloadUrl with GET /cases/{id}/attachments/{attachmentId}

The current implementation does not inspect attachment contents directly.

Usage Limits

POST /cases checks monthly usage before creating a new case:

SANDBOX: 100
PAYG: 100
BASE_PRO: 500

The limit compares both:

created cases in the current UTC month
billable finished cases in the current UTC month

The code treats completed cases as billable. Failed cases are billable unless the terminal resultStatus is BOUNCED, REJECTED, or COMPLAINED.

Design Advice

Good cases are:

specific
bounded to one outcome
easy to verify from the conversation

Good examples:

“Collect a signed W-9 from the vendor.”
“Confirm whether the Tuesday delivery window works.”
“Get the corrected March invoice.”

Poor examples:

“Handle vendor onboarding.”
“Figure out what to do.”
“Manage all communication with this account forever.”

Start here

Concepts

Guides

Core Fields

Runtime Fields

Defaults

Attachments

Usage Limits

Design Advice

​Core Fields

​Runtime Fields

​Defaults

​Attachments

​Usage Limits

​Design Advice

Core Fields

Runtime Fields

Defaults

Attachments

Usage Limits

Design Advice