Account Tasks & Interactions

Account tasks in Billabex represent action items that require human input or approval. They are created exclusively by the Billabex AI agent when it needs user guidance, contact information, or explicit approval to proceed with dunning activities on a specific account.

This guide covers how to interact with account tasks via the API: listing, retrieving, canceling, and responding with interactions.

Overview

Account tasks follow a simple lifecycle:

1. Created - The Billabex agent creates an account task when user input is required
2. Open - The task awaits user input
3. Interaction - A user responds via an interaction message
4. Closed/Canceled - The task is resolved by the agent or canceled by the user

Each account task has a type that determines what kind of response is expected.

Note: Account tasks can only be created by the Billabex agent. The public API allows you to read tasks, respond to them, and cancel them - but not create new ones.

Account Task Types

extraData.idempotencyKey

Task types that carry no structured payload of their own (Notice, AskNextAction, NeedContacts, ApproveFirstOutreach, Unknown) expose extraData.idempotencyKey. It is a stable key the agent sets when several tasks of the same type may legitimately coexist on one account, and it is null otherwise. It does not change when the task is replayed, so use it to reconcile a task you have already seen. A Notice about a customer complaint, for instance, is keyed contact-grievance:<incoming email id>.

Required Scopes

List Active Account Tasks

Retrieve active account tasks for a specific account.

GET [baseURL]/api/public/v1/account-tasks?accountId=ACCOUNT_ID
Authorization: Bearer YOUR_ACCESS_TOKEN

Query parameters:

Example response:

[
  {
    "task": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "organizationId": "org-uuid",
      "accountId": "account-uuid",
      "type": "NeedUserInput",
      "title": "Clarification needed on invoice #1234",
      "status": "UserActionRequired",
      "isActive": true,
      "isClosed": false,
      "isCanceled": false,
      "thread": [
        {
          "id": "interaction-uuid",
          "message": {
            "type": "Text",
            "value": "The customer mentioned a dispute. How should I proceed?"
          },
          "attachments": [],
          "sentAt": "2024-05-01T10:15:30.000Z",
          "agent": {
            "email": "agent@billabex.com",
            "firstName": "Alex",
            "lastName": "Martin"
          }
        }
      ],
      "assignees": [],
      "createdAt": "2024-05-01T10:15:30.000Z",
      "closedAt": null,
      "canceledAt": null,
      "cancelReason": null,
      "completedAt": null,
      "isPending": false,
      "pendingAt": null,
      "extraData": { "refEmailMessageIds": [] }
    }
  }
]

Search Account Tasks

GET /account-tasks answers a single account and returns its active tasks in one shot. To work across the whole organization, with filters, sorting and pagination, use the search endpoint.

GET [baseURL]/api/public/v1/account-tasks/search?organizationId=ORG_ID&first=20
Authorization: Bearer YOUR_ACCESS_TOKEN

Query parameters:

Filterable fields:

type accepts ApproveEligibility, ApproveContactChange, ApprovePaymentArrangement, ApproveFirstOutreach, NeedContacts, AskNextAction, NeedUserInput, PaymentScheduleInvalidated, Notice and Unknown. status accepts the values of the table further down this page.

Open tasks of a given type, most recent first:

GET [baseURL]/api/public/v1/account-tasks/search?organizationId=ORG_ID&filters=status%3Ais%3AUserActionRequired%3Btype%3Ais%3ANeedContacts&sortBy=createdAt&sortOrder=desc

Tasks created since the start of the quarter, on accounts owing more than 1000:

GET [baseURL]/api/public/v1/account-tasks/search?organizationId=ORG_ID&filters=createdAt%3Aafter%3A2026-06-30%3Bbalance%3AgreaterThan%3A1000

Example response:

{
  "nodes": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "organizationId": "org-uuid",
      "accountId": "account-uuid",
      "accountFullName": "Acme Corporation",
      "accountTagIds": [],
      "title": "Clarification needed on invoice #1234",
      "type": "NeedUserInput",
      "status": "UserActionRequired",
      "assignees": [],
      "assigneesFullName": [],
      "isActive": true,
      "isClosed": false,
      "isCanceled": false,
      "isPending": false,
      "balance": 1250.5,
      "currency": "EUR",
      "createdAt": "2026-05-01T10:15:30.000Z",
      "updatedAt": "2026-05-02T08:00:00.000Z",
      "closedAt": null,
      "canceledAt": null,
      "cancelReason": null,
      "pendingAt": null,
      "completedAt": null,
      "lastAgentInteractionAt": "2026-05-01T10:15:30.000Z"
    }
  ],
  "pageInfo": {
    "endCursor": "v2:8f14e45fceea:2"
  }
}

Two things to keep in mind:

• Items do not carry the interaction thread. Call GET /account-tasks/:accountTaskId for the thread of a task.
• The endCursor belongs to the filters and the sort it was issued for. Changing either one invalidates it, and the call returns 400 with the code LIST_CURSOR_INVALID.

Get an Account Task

Retrieve a single account task by ID.

GET [baseURL]/api/public/v1/account-tasks/:accountTaskId
Authorization: Bearer YOUR_ACCESS_TOKEN

Returns the same structure as above, wrapped in { "task": { ... } }.

Cancel an Account Task

Cancel an active account task. This marks the task as canceled without resolving it.

POST [baseURL]/api/public/v1/account-tasks/:accountTaskId/cancel
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "reason": "Invoice re-sent by hand, the contact confirmed reception."
}

The body is optional, and so is reason (2000 characters at most). Sending one is strongly recommended: cancelling is the only ending that answers nothing, and several task types hold the automatic follow-ups back while they are active, so cancelling one hands the cadence back to the agent. The reason is shown next to the cancellation and is read back by the agent before it reopens the same subject on that account.

Returns the updated account task with isCanceled: true, canceledAt set, and cancelReason carrying the reason when one was given.

Add an Interaction

Respond to an account task by adding a user interaction. This is how users provide the requested input to the Billabex agent.

POST [baseURL]/api/public/v1/account-tasks/:accountTaskId/interactions
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Text Interaction

For NeedUserInput and AskNextAction account tasks:

{
  "interaction": {
    "message": {
      "type": "Text",
      "value": "Please offer a 3-month payment plan with 10% interest."
    },
    "attachments": []
  }
}

Structured Interaction

For ApproveEligibility, NeedContacts, and Unknown account tasks, use structured messages.

ApproveEligibility Response

{
  "interaction": {
    "message": {
      "type": "Structured",
      "schema": "ApproveEligibility",
      "schemaVersion": 1,
      "value": true
    }
  }
}

The value is a boolean: true to approve, false to reject.

NeedContacts Response

{
  "interaction": {
    "message": {
      "type": "Structured",
      "schema": "NeedContacts",
      "schemaVersion": 1,
      "value": {
        "fullName": "Jane Doe",
        "email": "jane@company.com",
        "language": "en"
      }
    }
  }
}

Required fields in value:

• fullName (string)
• email (string)
• language (string, e.g., “en”, “fr”)

Unknown Response

{
  "interaction": {
    "message": {
      "type": "Structured",
      "schema": "Unknown",
      "schemaVersion": 1,
      "value": true
    }
  }
}

Message Schema Reference

Validation Rules

The API enforces strict validation on interaction messages:

• Text account tasks (NeedUserInput, AskNextAction) must receive type: "Text" messages
• Structured account tasks must receive type: "Structured" messages with matching schema
• Schema name and version must match exactly
• Value must conform to the expected type for that schema

Invalid messages return a 400 Bad Request with details.

Account Task Status Values

Common Errors

400 Bad Request - Invalid Message

{
  "statusCode": 400,
  "message": "Text message is required for this task type"
}

Cause: Sending a structured message to a text-only account task type.

404 Not Found - Account Task Not Found

{
  "statusCode": 404,
  "message": "Account task 123e4567-e89b-12d3-a456-426614174000 not found"
}

Cause: The account task ID does not exist or belongs to another organization.

403 Forbidden - Insufficient Scope

{
  "statusCode": 403,
  "message": "Forbidden",
  "error": "insufficient_scope"
}

Cause: Your token lacks tasks:all for write operations.

Next Steps

• Getting Started - Integration quick start
• OAuth Scopes - Required permissions
• Pagination & Filtering - Cursors and the filters parameter
• Rate Limiting - Avoid hitting limits
• API Reference - Full endpoint documentation

Support

Questions about account tasks and interactions?
Contact us via the website contact form.