Skip to main content

Workflow Definitions

Retrieve the blueprint configurations for your automated workflows. List all definitions with filtering and pagination, or retrieve the full profile for a single definition including its steps summary and triggers.

Prerequisites

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

List Definitions​

Retrieve a paginated list of workflow definitions.

GET/apidev/v1/workflow/definitions
PermissionAPICLI_WORKFLOW_READ
Rate Limit30 req/min (sliding window)
Cache30s

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
statusstringNoactiveFilter by status: active, inactive, or all
entity_typestringNo—Filter by entity type: TAREA, CUENTA, CLIENTE, PERSONAL, DISPOSITIVO, NINGUNA
searchstringNo—Partial match on name or description. Max length: 120

Response​

A successful response returns an array of workflow definition objects inside the data field.

FieldTypeDescription
idstringDefinition unique identifier (BigInt)
namestringDefinition display name
descriptionstring | nullDescription of the workflow
statusstring"active" or "inactive"
entity_typestringEntity type this workflow applies to
versionintegerDefinition version number
steps_countintegerNumber of steps in the workflow
triggers_countintegerNumber of triggers configured
created_atstringCreation timestamp (ISO 8601, no timezone)
updated_atstringLast update timestamp (ISO 8601, no timezone)

Code Examples​

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

Example Response​

{
  "success": true,
  "data": [
    {
      "id": "482938470192837465",
      "name": "New Account Onboarding",
      "description": "Triggered when a new account is created to complete the onboarding checklist.",
      "status": "active",
      "entity_type": "CUENTA",
      "version": 3,
      "steps_count": 5,
      "triggers_count": 2,
      "created_at": "2025-08-10T14:30:00",
      "updated_at": "2026-01-20T09:15:00"
    }
  ],
  "meta": {
    "total": 12,
    "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

Definition Detail​

Retrieve the full profile for a single workflow definition, including its steps summary and trigger configurations.

GET/apidev/v1/workflow/definitions/{id}
PermissionAPICLI_WORKFLOW_READ
Rate Limit30 req/min (sliding window)
Cache30s

Path Parameters​

ParameterTypeRequiredDescription
idstringYesThe unique identifier of the workflow definition (BigInt)

Response​

Returns the same fields as the List endpoint, plus the following additional fields:

FieldTypeDescription
steps_summaryarrayOrdered list of steps in the workflow (see below)
triggersarrayList of triggers that start this workflow (see below)

steps_summary array items:

FieldTypeDescription
node_idstringNode identifier within the definition
namestringStep display name
typestringStep type: human_task, automatic, condition, notification
assignee_typestring | nullAssignment type: user, group, role, or null
has_formbooleanWhether this step has a capture form

triggers array items:

FieldTypeDescription
typestringTrigger type: manual, event, schedule
descriptionstring | nullHuman-readable trigger description

Example Response​

{
  "success": true,
  "data": {
    "id": "482938470192837465",
    "name": "New Account Onboarding",
    "description": "Triggered when a new account is created to complete the onboarding checklist.",
    "status": "active",
    "entity_type": "CUENTA",
    "version": 3,
    "steps_count": 5,
    "triggers_count": 2,
    "created_at": "2025-08-10T14:30:00",
    "updated_at": "2026-01-20T09:15:00",
    "steps_summary": [
      {
        "node_id": "node_a1b2c3",
        "name": "Verify Contact Information",
        "type": "human_task",
        "assignee_type": "group",
        "has_form": true
      },
      {
        "node_id": "node_d4e5f6",
        "name": "Send Welcome Email",
        "type": "automatic",
        "assignee_type": null,
        "has_form": false
      }
    ],
    "triggers": [
      {
        "type": "event",
        "description": "Fires when a new account is created"
      },
      {
        "type": "manual",
        "description": null
      }
    ]
  },
  "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