Skip to main content
This guide walks through the shortest useful integration:
  1. create a case
  2. receive webhook events
  3. resume the case if human input is required

​
Prerequisites

  • an active API key
  • a public HTTPS endpoint that can receive POST requests from Offload
  • a place to store caseId and webhook event data in your app

​
1. Set your base URL and API key

export OFFLOAD_BASE_URL="https://2dr03s75sl.execute-api.us-west-2.amazonaws.com"
export OFFLOAD_API_KEY="your-api-key"
Use the x-api-key header on POST /cases, GET /cases/{id}, and POST /cases/{id}/input.

​
2. Create a case

This example asks Offload to collect a signed W-9 and return structured data when the task is complete. 
curl -X POST "$OFFLOAD_BASE_URL/cases" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $OFFLOAD_API_KEY" \
  -d '{
    "clientReferenceId": "vendor_2048",
    "channel": "EMAIL",
    "maxAttempts": 3,
    "followUpDelayHours": 72,
    "goal": {
      "objective": "Collect a signed W-9 from the vendor",
      "knowledge": {
        "vendorName": "Northstar Supplies",
        "requestReason": "AP onboarding",
        "dueDate": "2026-04-04"
      }
    },
    "counterparty": {
      "address": "ap@northstar.example",
      "name": "Maya Chen",
      "company": "Northstar Supplies",
      "timezone": "America/Los_Angeles"
    },
    "senderPersona": {
      "name": "Avery",
      "role": "Accounts Payable",
      "company": "Offload Customer Inc.",
      "tone": "friendly, concise"
    },
    "constraints": [
      "Email only",
      "Do not mention legal action"
    ],
    "resultSchema": {
      "type": "object",
      "properties": {
        "signedW9Received": { "type": "boolean" },
        "taxId": { "type": "string" },
        "documentUrl": { "type": "string" }
      },
      "required": ["signedW9Received"]
    },
    "clientWebhookUrl": "https://your-app.example/webhooks/offload"
  }'
Successful response: 
{
  "ok": true,
  "data": {
    "caseId": "case_123"
  }
}
Store caseId and map it to your own object using clientReferenceId if you have one.

​
3. Receive webhook events

Configure your webhook endpoint to accept JSON POST requests. Offload currently sends:
  • case.completed
  • case.failed
  • case.input_needed
Example case.completed payload: 
{
  "event_id": "evt_case_123_case_completed_1774131900000",
  "event_type": "case.completed",
  "timestamp": 1774131900000,
  "data": {
    "caseId": "case_123",
    "clientReferenceId": "vendor_2048",
    "status": "COMPLETED",
    "channel": "EMAIL",
    "attemptCount": 2,
    "resultStatus": "goal_achieved",
    "result": {
      "signedW9Received": true,
      "taxId": "12-3456789",
      "documentUrl": "https://files.example.com/w9.pdf"
    }
  }
}

​
4. Handle input-needed cases

Sometimes Offload cannot continue without a business decision or missing context. In that case, you receive case.input_needed. Example: 
{
  "event_id": "evt_case_123_case_input_needed_1774131900000",
  "event_type": "case.input_needed",
  "timestamp": 1774131900000,
  "data": {
    "caseId": "case_123",
    "clientReferenceId": "vendor_2048",
    "status": "INPUT_NEEDED",
    "channel": "EMAIL",
    "attemptCount": 1,
    "inputRequest": "The vendor asked whether they can send the W-9 next Monday. Should I accept that timeline?",
    "inputRequestId": "input-request-123",
    "inputRequestStatus": "PENDING",
    "inputRequestedAt": 1774131900000
  }
}
Resume the case: 
curl -X POST "$OFFLOAD_BASE_URL/cases/case_123/input" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $OFFLOAD_API_KEY" \
  -d '{
    "inputRequestId": "input-request-123",
    "providedContext": "Yes, next Monday is acceptable."
  }'
Accepted response: 
{
  "ok": true,
  "data": {
    "caseId": "case_123",
    "inputRequestId": "input-request-123",
    "accepted": true
  }
}

​
5. Poll if needed

If you want a point-in-time status check, call GET /cases/{id}. 
curl -H "x-api-key: $OFFLOAD_API_KEY" \
  "$OFFLOAD_BASE_URL/cases/case_123"
GET /cases/{id} returns the current case state and result data, but the active inputRequest details are currently only included in webhook events.

​
Next steps