Skip to main content

​
Endpoint

POST /cases

​
Auth

x-api-key: your-api-key

​
Purpose

Creates a new asynchronous coordination case and starts the workflow.

​
Request body

FieldTypeRequiredNotes
channelEMAIL | SMSYesUse EMAIL for current production workflows.
goalobjectYesMust include objective.
counterpartyobjectYesMust include address and name.
senderPersonaobjectYesMust include name.
clientReferenceIdstringNoYour stable ID for mapping the case back to your system.
constraintsstring[]NoHard rules for the workflow.
maxAttemptsintegerNoDefaults to 3.
followUpDelayHoursintegerNoDefaults to 72.
resultSchemaobjectNoJSON Schema for the final result.
clientWebhookUrlstringNoRecommended for event-driven integrations.
metadataobjectNoOpaque metadata echoed back in webhooks.

​
Example request

{
  "clientReferenceId": "property_4421_invoice_march",
  "channel": "EMAIL",
  "maxAttempts": 2,
  "followUpDelayHours": 24,
  "goal": {
    "objective": "Get the vendor to send the updated invoice for March landscaping services.",
    "knowledge": {
      "invoiceMonth": "March 2026",
      "vendorName": "GreenLeaf Landscaping",
      "propertyName": "Maple Grove Apartments",
      "expectedAmount": "$1,240.00"
    }
  },
  "counterparty": {
    "address": "ap@greenleaf.example",
    "name": "Jordan Lee",
    "company": "GreenLeaf Landscaping",
    "timezone": "America/Los_Angeles"
  },
  "senderPersona": {
    "name": "Melissa",
    "role": "Accounts Payable Coordinator",
    "company": "Northstar Property Group",
    "tone": "professional, clear, polite"
  },
  "clientWebhookUrl": "https://your-app.example/webhooks/offload",
  "metadata": {
    "portfolio": "west-coast",
    "propertyId": "property-4421"
  }
}

​
Example response

{
  "ok": true,
  "data": {
    "caseId": "case_123"
  }
}

​
Errors

StatusCodeMeaning
400INVALID_REQUESTMalformed JSON or failed validation
401UNAUTHORIZEDMissing or invalid API key
500INTERNAL_ERRORThe case could not be created