Skip to main content
Upload back-office tasks (compliance reviews, fraud investigations, payment disputes, KYC reviews) so Rulebase can evaluate them alongside your conversations.

​
When to use tasks vs conversations

If the work is…Use
A customer interaction (call, chat, email)/conversations
Back-office work an agent did in your internal admin tool (no customer on the line)/tasks
Tasks work like conversations. They’re scored against scorecards, assigned to QA reviewers, and rolled up into agent performance reports.

​
Upload methods

Rulebase supports two methods for uploading tasks. Pick based on how your source system exports data.
  1. Single task. POST /tasks with a JSON body. Use this when your system pushes individual tasks in real time.
  2. Bulk CSV upload. POST /tasks/upload with a multipart CSV containing many tasks. Use this for periodic exports.

​
Method 1: single task

Send a JSON body to POST /tasks with the task details: 
curl -X POST https://api.rulebase.co/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "external_id": "TASK-9182",
      "agent": {
        "email": "[email protected]",
        "name": "Alex Smith",
        "external_id": "EMP-447"
      },
      "completed_at": "2026-05-12T14:32:00Z",
      "custom_attributes": {
        "task_type": "fraud_review",
        "status": "completed",
        "priority": "high",
        "risk_score": 78
      }
    }
  }'
A successful response returns the created task: 
{
  "data": {
    "id": "task_01HZ8QK4...",
    "external_id": "TASK-9182",
    "agent": {
      "email": "[email protected]",
      "name": "Alex Smith",
      "external_id": "EMP-447"
    },
    "completed_at": "2026-05-12T14:32:00Z",
    "custom_attributes": {
      "task_type": "fraud_review",
      "status": "completed",
      "priority": "high",
      "risk_score": 78
    },
    "created_at": "2026-05-12T14:35:00Z",
    "updated_at": "2026-05-12T14:35:00Z"
  }
}
You can fetch the task back later with GET /tasks/{id}. For the full REST spec, see Create a task.

​
Method 2: bulk CSV upload

Upload a CSV to POST /tasks/upload as multipart/form-data: 
curl -X POST https://api.rulebase.co/tasks/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "upload[file][email protected]"
A successful response returns an upload id and a processing status: 
{
  "data": {
    "id": "tup_01HZ8QK4...",
    "status": "processing",
    "created_at": "2026-05-12T14:35:00Z",
    "updated_at": "2026-05-12T14:35:00Z"
  }
}
Poll GET /tasks/upload/{id} until status becomes completed (or failed). Each row in the CSV is processed as if it were a separate POST /tasks call.

​
Bulk upload requirements

  • Content-Type: multipart/form-data
  • File format: CSV with a header row
  • Header row required; column order is flexible
For the full REST spec, see Upload tasks in bulk.

​
Task schema reference

FieldRequiredTypeDescription
external_idYesstringUnique identifier for this task in your system. Used to deduplicate re-uploads.
agentYesobjectThe agent who handled the task. See Agent object below.
completed_atYesstringISO 8601 timestamp of when the agent finished the task. Used for time-based reporting.
custom_attributesNoobjectFree-form key/value pairs for anything else (task type, status, outcome, risk category, etc.).
Customer-specific fields (task type taxonomies, lifecycle states, outcomes) go in custom_attributes rather than the top-level schema. Rulebase stores the full object and exposes it in reports and filters.

​
Agent object

agent is an object, not a string: 
{
  "email": "[email protected]",
  "name": "Alex Smith",
  "external_id": "EMP-447"
}
FieldRequiredDescription
external_idOne of email or external_id requiredStable identifier from your system (employee/user ID).
emailOne of email or external_id requiredWork email of the agent.
nameNoDisplay name. Used to label dashboards and reports.

​
How agents are matched

When Rulebase receives a task, it looks up the agent against your existing employee records:
  1. Match by external_id if provided.
  2. Otherwise, match by email.
  3. If neither matches an existing employee, a new one is created from the fields you sent.
Subsequent task pushes upsert: missing fields get filled in, existing fields are preserved. You don’t need a separate employee roster API. You enrich employee records by carrying richer agent objects on the tasks you push. Name alone is not enough to match an agent. Typos and name collisions create phantom employees, so at least one of email or external_id is always required.

​
CSV column reference

CSV uploads use flat columns that map onto the JSON schema:
ColumnRequiredMaps to
external_idYesexternal_id
agent_emailOne of agent_email or agent_external_id requiredagent.email
agent_external_idOne of agent_email or agent_external_id requiredagent.external_id
agent_nameNoagent.name
completed_atYescompleted_at
custom_<key>Nocustom_attributes.<key>
Any column prefixed with custom_ is flattened into custom_attributes. For example, a custom_task_type column becomes custom_attributes.task_type.

​
Example CSV

external_id,agent_email,agent_name,completed_at,custom_task_type,custom_status,custom_priority
TASK-9182,[email protected],Alex Smith,2026-05-12T14:32:00Z,fraud_review,completed,high
TASK-9183,[email protected],Sam Patel,2026-05-12T14:48:00Z,kyc_verification,completed,normal
TASK-9184,[email protected],Alex Smith,2026-05-12T15:02:00Z,account_closure,cancelled,

​
Retrieving a task

Use GET /tasks/{id} to fetch a task back by its Rulebase ID: 
{
  "data": {
    "id": "task_01HZ8QK4...",
    "external_id": "TASK-9182",
    "agent": {
      "email": "[email protected]",
      "name": "Alex Smith",
      "external_id": "EMP-447"
    },
    "completed_at": "2026-05-12T14:32:00Z",
    "custom_attributes": {
      "task_type": "fraud_review",
      "status": "completed",
      "priority": "high",
      "risk_score": 78
    },
    "created_at": "2026-05-12T14:35:00Z",
    "updated_at": "2026-05-12T14:51:00Z"
  }
}