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

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,
      "completedAt": null,
      "isPending": false,
      "pendingAt": null,
      "extraData": {}
    }
  }
]

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

Returns the updated account task with isCanceled: true and canceledAt set.

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
• Rate Limiting - Avoid hitting limits
• API Reference - Full endpoint documentation

Support

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