Open and move cases

Both endpoints need the write:cases scope.

POST /api/v1/cases

Opens a case. Every case starts NEW.

POST /api/v1/cases HTTP/1.1
Host: agentlyleads.com
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{ "subject": "Pallet arrived damaged", "severity": "HIGH", "companyId": "cmq2comp0alk34567890", "assigneeEmail": "kevin@example.com" }

Field	Notes
`subject`	Required unless `emailId` is given. Up to 200 characters
`description`	Up to 10000 characters
`severity`	`LOW`, `MEDIUM` (default), `HIGH` or `URGENT`. `HIGH` and `URGENT` carry a three-day resolution target
`emailId`	Open the case from a received email (see below)
`companyId`, `contactId`	Who it is on
`assigneeId` or `assigneeEmail`	An active workspace member. Omit to leave it in the queue

Pass emailId and the subject, description, contact and company are taken from the message, and the case stays linked to that conversation. One conversation is one issue: opening a case on the same conversation again returns the existing case with 200 and "created": false, instead of splitting its history. Because this copies the email's text into the case, the key also needs the read:emails scope.

Returns 201 (or 200 for an existing case) with { "case": { ... }, "created": true } in the shape of the Case object.

POST /api/v1/cases/{id}/status

Moves a case through NEW, OPEN, PENDING, RESOLVED and CLOSED, and can change its severity or who has it.

POST /api/v1/cases/cmq2case0alk34567890/status HTTP/1.1
Content-Type: application/json

{ "status": "RESOLVED" }

Field	Notes
`status`	The new status
`severity`	The new severity
`assigneeId` or `assigneeEmail`	Hand it to an active workspace member. `assigneeId: null` returns it to the queue

The clock follows the same rules as the app:

Leaving NEW records firstResponseAt, once.
RESOLVED and CLOSED stop the clock and stamp resolvedAt.
Moving from RESOLVED to CLOSED keeps the original resolvedAt, because filing is not a second resolution.
Reopening (back to NEW, OPEN or PENDING) clears resolvedAt and the clock runs again.

Errors

Status	When
`400`	A missing subject, nothing to change, or an assignee who is not an active workspace member
`403`	The key lacks `write:cases`, or lacks `read:emails` when opening from an email
`404`	No case, email, company or contact with that ID in your workspace

Open and move cases

POST /api/v1/cases

From an email

POST /api/v1/cases/{id}/status

Errors

On this page