Skip to main content

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:

HeaderRequiredDescription
AuthorizationYesBearer token obtained from the Login endpoint. Format: Bearer <token>
X-API-KeyYesCompany integration key provided during onboarding. Format: gtk_xxx...
tenantYesYour company hostname (e.g., yourcompany.geotareas.com)
Content-TypeConditionalapplication/json — required for POST and PUT requests

Query Parameters​

ParameterTypeRequiredDefaultDescription
limitintegerNo25Number of records per page. Min: 1, Max: 100
offsetintegerNo0Number of records to skip for pagination
statusstringNo—Filter by status: PENDING, IN_PROGRESS, COMPLETED
definition_idstringNo—Filter by workflow definition ID. Max length: 30
entity_typestringNo—Filter by entity type
overdue_onlybooleanNofalseReturn only overdue tasks

Response​

FieldTypeDescription
idstringTask unique identifier (BigInt)
instance_idstringParent workflow instance ID (BigInt)
workflow_namestringWorkflow definition name
step_namestringStep display name
statusstring"PENDING", "IN_PROGRESS", or "COMPLETED"
assigned_to_userobject | nullAssigned user {id, name}
assigned_to_groupobject | nullAssigned group {id, name}
entityobjectAssociated entity {type, id, label}
due_datestring | nullTask due date (ISO 8601, no timezone)
escalatedbooleanWhether the task has been escalated
created_atstringTask creation timestamp (ISO 8601, no timezone)

Code Examples​

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"

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:

HeaderDescription
X-RateLimit-LimitMaximum number of requests allowed in the current window
X-RateLimit-RemainingNumber of requests remaining in the current window
X-RateLimit-ResetUnix timestamp (seconds) when the current window resets
Retry-AfterSeconds to wait before retrying (only present on 429 responses)
X-Request-IdUnique 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​

ParameterTypeRequiredDescription
idstringYesThe unique identifier of the task (BigInt)

Response​

FieldTypeDescription
idstringTask unique identifier (BigInt)
instance_idstringParent workflow instance ID (BigInt)
workflow_namestringWorkflow definition name
step_namestringStep display name
step_descriptionstring | nullStep description
statusstring"PENDING", "IN_PROGRESS", or "COMPLETED"
assigned_to_userobject | nullAssigned user {id, name}
assigned_to_groupobject | nullAssigned group {id, name}
due_datestring | nullTask due date
escalatedbooleanWhether the task has been escalated
entityobjectAssociated entity {type, id, label}
available_resultsarrayPossible completion results (see below)
fieldsarrayForm fields to capture (see below)
previous_steps_dataarrayData captured in earlier steps (see below)
created_atstringTask creation timestamp

available_results array items:

FieldTypeDescription
codestringResult code to send when completing the task
labelstringDisplay label for the result

fields array items:

FieldTypeDescription
idstringField identifier
namestringField name to use in captured_data
typestringField type: text, number, date, boolean, select, file
requiredbooleanWhether this field is required
valueany | nullCurrent value (pre-filled or null)

previous_steps_data array items:

FieldTypeDescription
step_namestringStep display name
completed_bystringUser who completed the step
completed_atstringCompletion timestamp
resultstringResult code
captured_dataobjectKey-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​

ParameterTypeRequiredDescription
idstringYesThe unique identifier of the task (BigInt)

Request Body​

FieldTypeRequiredDescription
result_codestringYesOne of the codes from available_results. Max length: 80
captured_dataobjectNoKey-value pairs matching the task fields
commentstringNoOptional comment. Max length: 2000

Code Examples​

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."
  }'

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​

ParameterTypeRequiredDescription
idstringYesThe unique identifier of the task (BigInt)

Request Body​

FieldTypeRequiredDescription
assign_to_user_idstringConditionalUser ID to assign the task to. Max length: 30
assign_to_group_idstringConditionalGroup ID to assign the task to. Max length: 30
commentstringNoOptional comment explaining the reassignment. Max length: 500

Code Examples​

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."
  }'

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.

CodeHTTPDescription
BAD_REQUEST400Missing required headers
VALIDATION_ERROR400Invalid params
UNAUTHORIZED401Invalid or expired JWT / API Key
FORBIDDEN403User lacks required permission
NOT_FOUND404Resource not found
RATE_LIMITED429Exceeded rate limit
INTERNAL_ERROR500Unexpected server error