Workflow Tasks

Manage human tasks generated by running workflows. List pending tasks in your inbox, view task details with available results and form fields, complete tasks with captured data, and reassign tasks to other users or groups.

Prerequisites

All endpoints on this page require a valid JWT token, API key, and tenant header. See Authentication for details.

List Tasks

Retrieve a paginated list of workflow tasks.

GET/apidev/v1/workflow/tasks

PermissionAPICLI_WORKFLOW_READ

Rate Limit30 req/min (sliding window)

Cache15s

Request Headers

Every request to a protected endpoint requires these headers:

Header	Required	Description
`Authorization`	Yes	Bearer token obtained from the Login endpoint. Format: `Bearer <token>`
`X-API-Key`	Yes	Company integration key provided during onboarding. Format: `gtk_xxx...`
`tenant`	Yes	Your assigned tenant domain (default: `geotareas.com`) — always send your assigned tenant
`Content-Type`	Conditional	`application/json` — required for `POST` and `PUT` requests

Query Parameters

Parameter	Type	Required	Default	Description
`limit`	integer	No	`25`	Number of records per page. Min: `1`, Max: `100`
`offset`	integer	No	`0`	Number of records to skip for pagination
`status`	string	No	—	Filter by status: `PENDING`, `IN_PROGRESS`, `COMPLETED`
`definition_id`	string	No	—	Filter by workflow definition ID. Max length: 30
`entity_type`	string	No	—	Filter by entity type
`overdue_only`	boolean	No	`false`	Return only overdue tasks

Response

Field	Type	Description
`id`	string	Task unique identifier (BigInt)
`instance_id`	string	Parent workflow instance ID (BigInt)
`workflow_name`	string	Workflow definition name
`step_name`	string	Step display name
`status`	string	`"PENDING"`, `"IN_PROGRESS"`, or `"COMPLETED"`
`assigned_to_user`	object \| null	Assigned user `{id, name}`
`assigned_to_group`	object \| null	Assigned group `{id, name}`
`entity`	object	Associated entity `{type, id, label}`
`due_date`	string \| null	Task due date (ISO 8601, no timezone)
`escalated`	boolean	Whether the task has been escalated
`created_at`	string	Task creation timestamp (ISO 8601, no timezone)

Code Examples

cURL
JavaScript
Python

curl -s -X GET "https://$TENANT_HOST/apidev/v1/workflow/tasks?limit=10&status=PENDING" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

const response = await fetch(
  `https://${TENANT_HOST}/apidev/v1/workflow/tasks?limit=10&status=PENDING`,
  {
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "X-API-Key": APIKEY,
      "tenant": TENANT,
    },
  }
);

const { data, meta } = await response.json();
console.log(`Fetched ${data.length} of ${meta.total} tasks`);

import requests

response = requests.get(
    f"https://{TENANT_HOST}/apidev/v1/workflow/tasks",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "X-API-Key": APIKEY,
        "tenant": TENANT,
    },
    params={"limit": 10, "status": "PENDING"},
)

result = response.json()
for task in result["data"]:
    print(f"{task['id']}: {task['step_name']} ({task['status']})")

Example Response

{
  "success": true,
  "data": [
    {
      "id": "674839201748392018",
      "instance_id": "591847302948571634",
      "workflow_name": "New Account Onboarding",
      "step_name": "Send Welcome Email",
      "status": "PENDING",
      "assigned_to_user": null,
      "assigned_to_group": {"id": "293847102938471029", "name": "Sales Team"},
      "entity": {"type": "CUENTA", "id": "738291047382910473", "label": "Acme Corp"},
      "due_date": "2026-03-17T11:30:00",
      "escalated": false,
      "created_at": "2026-03-15T11:30:01"
    }
  ],
  "meta": {
    "total": 8,
    "limit": 10,
    "offset": 0
  }
}

Rate Limit Headers

Every response includes rate limit information in the headers:

Header	Description
`X-RateLimit-Limit`	Maximum number of requests allowed in the current window
`X-RateLimit-Remaining`	Number of requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp (seconds) when the current window resets
`Retry-After`	Seconds to wait before retrying (only present on `429` responses)
`X-Request-Id`	Unique request identifier for debugging and support tickets

Task Detail

Retrieve the full detail for a single workflow task, including available results, form fields, and data captured in previous steps.

GET/apidev/v1/workflow/tasks/{id}

PermissionAPICLI_WORKFLOW_READ

Rate Limit30 req/min (sliding window)

Cache15s

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The unique identifier of the task (BigInt)

Response

Field	Type	Description
`id`	string	Task unique identifier (BigInt)
`instance_id`	string	Parent workflow instance ID (BigInt)
`workflow_name`	string	Workflow definition name
`step_name`	string	Step display name
`step_description`	string \| null	Step description
`status`	string	`"PENDING"`, `"IN_PROGRESS"`, or `"COMPLETED"`
`assigned_to_user`	object \| null	Assigned user `{id, name}`
`assigned_to_group`	object \| null	Assigned group `{id, name}`
`due_date`	string \| null	Task due date
`escalated`	boolean	Whether the task has been escalated
`entity`	object	Associated entity `{type, id, label}`
`available_results`	array	Possible completion results (see below)
`fields`	array	Form fields to capture (see below)
`previous_steps_data`	array	Data captured in earlier steps (see below)
`created_at`	string	Task creation timestamp

available_results array items:

Field	Type	Description
`code`	string	Result code to send when completing the task
`label`	string	Display label for the result

fields array items:

Field	Type	Description
`id`	string	Field identifier
`name`	string	Field name to use in `captured_data`
`type`	string	Field type: `text`, `number`, `date`, `boolean`, `select`, `file`
`required`	boolean	Whether this field is required
`value`	any \| null	Current value (pre-filled or null)

previous_steps_data array items:

Field	Type	Description
`step_name`	string	Step display name
`completed_by`	string	User who completed the step
`completed_at`	string	Completion timestamp
`result`	string	Result code
`captured_data`	object	Key-value pairs of captured field data

Example Response

{
  "success": true,
  "data": {
    "id": "674839201748392018",
    "instance_id": "591847302948571634",
    "workflow_name": "New Account Onboarding",
    "step_name": "Send Welcome Email",
    "step_description": "Send the welcome email to the new account contact.",
    "status": "PENDING",
    "assigned_to_user": null,
    "assigned_to_group": {"id": "293847102938471029", "name": "Sales Team"},
    "due_date": "2026-03-17T11:30:00",
    "escalated": false,
    "entity": {"type": "CUENTA", "id": "738291047382910473", "label": "Acme Corp"},
    "available_results": [
      {"code": "sent", "label": "Email Sent"},
      {"code": "failed", "label": "Email Failed"}
    ],
    "fields": [
      {"id": "f_email", "name": "email_address", "type": "text", "required": true, "value": null},
      {"id": "f_template", "name": "template", "type": "select", "required": true, "value": null}
    ],
    "previous_steps_data": [
      {
        "step_name": "Verify Contact Information",
        "completed_by": "jdoe",
        "completed_at": "2026-03-15T11:30:00",
        "result": "approved",
        "captured_data": {
          "contact_verified": true,
          "phone_confirmed": true
        }
      }
    ],
    "created_at": "2026-03-15T11:30:01"
  },
  "meta": {}
}

Complete Task

Complete a workflow task by providing a result code and optional captured data. The workflow advances to the next step.

POST/apidev/v1/workflow/tasks/{id}/complete

PermissionAPICLI_WORKFLOW_EXECUTE

Rate Limit10 req/min (sliding window)

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The unique identifier of the task (BigInt)

Request Body

Field	Type	Required	Description
`result_code`	string	Yes	One of the codes from `available_results`. Max length: 80
`captured_data`	object	No	Key-value pairs matching the task `fields`
`comment`	string	No	Optional comment. Max length: 2000

Code Examples

cURL
JavaScript
Python

curl -s -X POST "https://$TENANT_HOST/apidev/v1/workflow/tasks/674839201748392018/complete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "result_code": "sent",
    "captured_data": {
      "email_address": "contact@acme.com",
      "template": "Premium Welcome"
    },
    "comment": "Welcome email sent successfully."
  }'

const response = await fetch(
  `https://${TENANT_HOST}/apidev/v1/workflow/tasks/674839201748392018/complete`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "X-API-Key": APIKEY,
      "tenant": TENANT,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      result_code: "sent",
      captured_data: {
        email_address: "contact@acme.com",
        template: "Premium Welcome",
      },
      comment: "Welcome email sent successfully.",
    }),
  }
);

const { data } = await response.json();
console.log(`Task ${data.task_id} completed — next step: ${data.next_step}`);

import requests

response = requests.post(
    f"https://{TENANT_HOST}/apidev/v1/workflow/tasks/674839201748392018/complete",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "X-API-Key": APIKEY,
        "tenant": TENANT,
        "Content-Type": "application/json",
    },
    json={
        "result_code": "sent",
        "captured_data": {
            "email_address": "contact@acme.com",
            "template": "Premium Welcome",
        },
        "comment": "Welcome email sent successfully.",
    },
)

result = response.json()
print(f"Task {result['data']['task_id']} completed")

Example Response

{
  "success": true,
  "data": {
    "task_id": "674839201748392018",
    "status": "COMPLETED",
    "result": "sent",
    "completed_at": "2026-03-19T14:10:00",
    "instance_status": "RUNNING",
    "next_step": "Review Welcome Package"
  },
  "meta": {}
}

Reassign Task

Reassign a pending or in-progress task to a different user or group. One of assign_to_user_id or assign_to_group_id is required.

POST/apidev/v1/workflow/tasks/{id}/reassign

PermissionAPICLI_WORKFLOW_EXECUTE

Rate Limit10 req/min (sliding window)

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The unique identifier of the task (BigInt)

Request Body

Field	Type	Required	Description
`assign_to_user_id`	string	Conditional	User ID to assign the task to. Max length: 30
`assign_to_group_id`	string	Conditional	Group ID to assign the task to. Max length: 30
`comment`	string	No	Optional comment explaining the reassignment. Max length: 500

Code Examples

cURL
JavaScript
Python

curl -s -X POST "https://$TENANT_HOST/apidev/v1/workflow/tasks/674839201748392018/reassign" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "assign_to_user_id": "182736450918273645",
    "comment": "Reassigning to specialist."
  }'

const response = await fetch(
  `https://${TENANT_HOST}/apidev/v1/workflow/tasks/674839201748392018/reassign`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "X-API-Key": APIKEY,
      "tenant": TENANT,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      assign_to_user_id: "182736450918273645",
      comment: "Reassigning to specialist.",
    }),
  }
);

const { data } = await response.json();
console.log(`Task ${data.task_id} reassigned to ${data.assigned_to_user.name}`);

import requests

response = requests.post(
    f"https://{TENANT_HOST}/apidev/v1/workflow/tasks/674839201748392018/reassign",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "X-API-Key": APIKEY,
        "tenant": TENANT,
        "Content-Type": "application/json",
    },
    json={
        "assign_to_user_id": "182736450918273645",
        "comment": "Reassigning to specialist.",
    },
)

result = response.json()
print(f"Task {result['data']['task_id']} reassigned")

Example Response

{
  "success": true,
  "data": {
    "task_id": "674839201748392018",
    "assigned_to_user": {"id": "182736450918273645", "name": "Maria Garcia"},
    "assigned_to_group": null,
    "reassigned_at": "2026-03-19T14:15:00"
  },
  "meta": {}
}

Errors

All endpoints on this page may return the following errors. For the full error reference, see Error Handling.

Code	HTTP	Description
`VALIDATION_ERROR`	400	Invalid params
`UNAUTHORIZED`	401	Missing, invalid, or expired tenant / Authorization / X-API-Key
`FORBIDDEN`	403	User lacks required permission
`NOT_FOUND`	404	Resource not found
`RATE_LIMITED`	429	Exceeded rate limit
`INTERNAL_ERROR`	500	Unexpected server error

Authentication -- How to obtain and use JWT tokens and API keys
Workflow Definitions -- Browse available workflow blueprints
Workflow Instances -- Start, track, and cancel workflow instances
Pagination -- Standard pagination parameters and metadata
Rate Limits -- Rate limit windows and retry strategies
Error Handling -- Full error codes reference

List Tasks​

Request Headers​

Query Parameters​

Response​

Code Examples​

Example Response​

Rate Limit Headers​

Task Detail​

Path Parameters​

Response​

Example Response​

Complete Task​

Path Parameters​

Request Body​

Code Examples​

Example Response​

Reassign Task​

Path Parameters​

Request Body​

Code Examples​

Example Response​

Errors​

Related Resources​

List Tasks

Request Headers

Query Parameters

Response

Code Examples

Example Response

Rate Limit Headers

Task Detail

Path Parameters

Response

Example Response

Complete Task

Path Parameters

Request Body

Code Examples

Example Response

Reassign Task

Path Parameters

Request Body

Code Examples

Example Response

Errors

Related Resources