Skip to main content
This guide is for developers integrating with the platform. The platform runs browser-automation agents that perform healthcare tasks (e.g. prior auth, eligibility, claim submission, appeals on payer portals). You submit work as tasks; each task is processed asynchronously. When a task finishes, you receive a webhook with the outcome so you can update your systems without polling or using the UI. After you complete this guide, you’ll have created a task via the API and received a webhook when it reaches a final state: completed, completed with issues, or failed.

​
Before you begin

You need the following in place before calling the API:
  • Account SOPs – Standard operating procedures and account configuration (e.g. provider credentials, portal access) so the agent can perform tasks on your behalf.
  • API key – A secret key used to authenticate your requests. You send it as a Bearer token in the Authorization header.
  • Webhook endpoint – A URL we can call when a task reaches a final state. Your server receives a POST request with the task outcome (completed, completed with issues, or failed) so you can update your records.
Contact support@chooseserene.com to set up all of them.

​
Create a task

To create a task, send a POST /tasks request with your API key (as a Bearer token in the Authorization header), a task type, and either text data or file uploads. The platform creates a task and assigns it to an agent. You do not need to poll for status; when the task finishes, we send a webhook to your configured endpoint with the outcome.
1

Send the request

Send POST /tasks with your API key, a task type, and either inline text (data) or file uploads (multipart). The API returns immediately with the created task; the agent runs in the background and you get the final outcome via webhook.
Send type and optional data as JSON. No files required.
curl --request POST \
  --url "$API_BASE/tasks" \
  --header "Authorization: Bearer $SERENE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
"type": "submit_claim",
"data": "member_id: 300059049\npatient: Louise Golicic\nDOB: 1949-12-23\nplace_of_service: home\nservice_date: 2025-03-25"
}'
ResponseOn success (200), the response body is the created task. Store the id if you need to correlate the webhook payload later; you do not need to poll for status.
{
  "id": 1,
  "accountId": 1,
  "task_number": 1,
  "status": "pending",
  "handler": "submit_claim_1",
  "title": "Submit claim #1",
  "instructions": "SOP: Log in to portal, open claim form, enter member and procedure details, submit and capture confirmation number.",
  "startedAt": null,
  "completedAt": null,
  "failedAt": null,
  "notes": null,
  "createdAt": "2025-03-18T12:00:00.000Z",
  "updatedAt": "2025-03-18T12:00:00.000Z"
}
For more details, see the endpoint reference: POST /tasks.
2

What happens behind the scenes

After you get the task back from the API, a computer agent picks it up and runs it in the background. The agent uses your account’s configured credentials and SOPs to sign in to the payer portal (e.g. Availity), then uses the task data from your request (text or uploaded files) to complete the workflow—e.g. fill forms, check eligibility, or submit claims. It navigates the same screens a human would. You do not need to poll or use the UI; when the agent is done (success, issues, or failure), we send a webhook to your endpoint with the outcome.Computer-use agent logging into the Availity portal
3

Receive the webhook

When the task reaches a final state, we send a POST request to the webhook URL you configured for your account. The body is an envelope with signature (to verify the payload), event ("task_finished"), created_at, and data (the task object). Your server can update your database, notify users, or trigger follow-up workflows—no polling or dashboard checks needed.You will receive one of three statuses in data.status:
  • completed – The agent finished successfully; the task was completed as intended.
  • completed_with_issues – The agent finished but with caveats (e.g. manual follow-up needed). Use data.notes for details.
  • failed – The task did not succeed. The payload includes data.notes with error or context for the record.
Webhook request body (examples)
{
  "signature": "",
  "event": "task_finished",
  "created_at": "2025-03-18T12:05:00.000Z",
  "data": {
    "id": 1,
    "accountId": 1,
    "task_number": 1,
    "status": "completed",
    "handler": "submit_claim_1",
    "title": "Submit claim #1",
    "instructions": "SOP: Log in to portal, open claim form, enter member and procedure details, submit and capture confirmation number.",
    "trajectory_id": 42,
    "startedAt": "2025-03-18T12:01:00.000Z",
    "completedAt": "2025-03-18T12:05:00.000Z",
    "failedAt": null,
    "notes": "Claim successfully submitted with reference PA-2025-03-1842.",
    "createdAt": "2025-03-18T12:00:00.000Z",
    "updatedAt": "2025-03-18T12:05:00.000Z"
  }
}
Respond with a 2xx status so we know the delivery succeeded. If we do not receive 2xx, we may retry. For payload details, retry behavior, and configuration, see Webhooks.

​
Next steps

API reference

Explore authentication and other endpoints.

Webhooks

Payload format and configuration for task completion webhooks.