Get Approval Details

Endpoint

GET /v2/tasks/{task_id}/approval-details

Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

Authorization: Bearer your_access_token

Required scope: tasks:read

Path Parameters

Parameter	Type	Required	Description
`task_id`	integer	Yes	Unique identifier for the task

Query Parameters

Parameter	Type	Required	Description
`include_files`	boolean	No	Include presigned download URLs for file-type variables. Defaults to `false`

Request Example

curl -X GET "https://platform.chamelio.ai/v2/tasks/12345/approval-details?include_files=true" \
  -H "Authorization: Bearer your_access_token"

import requests

task_id = 12345

url = f"https://platform.chamelio.ai/v2/tasks/{task_id}/approval-details"
headers = {
    "Authorization": "Bearer your_access_token"
}
params = {
    "include_files": True
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const taskId = 12345;

const response = await fetch(
  `https://platform.chamelio.ai/v2/tasks/${taskId}/approval-details?include_files=true`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your_access_token'
    }
  }
);

const data = await response.json();
console.log(data);

Response

Success Response

Status Code: 200 OK

{
  "task_id": 12345,
  "step_run": {
    "step_run_id": "sr_abc123",
    "step_id": "approval_step",
    "step_name": "Legal Approval",
    "step_type": "approval",
    "status": "pending",
    "variables": [
      {
        "variable_type": "text",
        "value": "Acme Corporation",
        "step_id": "intake_step",
        "variable_id": "vendor_name"
      }
    ]
  },
  "eligible_approvers_active": ["manager@example.com"],
  "next_eligible_approvers": ["director@example.com"],
  "variables_to_approve": [
    {
      "variable_type": "number",
      "value": 150000,
      "step_id": "intake_step",
      "variable_id": "contract_value"
    },
    {
      "variable_type": "file",
      "value": "att_789",
      "step_id": "intake_step",
      "variable_id": "contract_file"
    }
  ],
  "files": [
    {
      "file_id": "att_789",
      "file_name": "contract_draft.pdf",
      "content_type": "application/pdf",
      "download_url": "https://storage.example.com/presigned-url...",
      "expires_at": "2025-01-20T12:00:00Z",
      "variable_id": "contract_file"
    }
  ]
}

Response Fields

Field	Type	Description
`task_id`	integer	ID of the task
`step_run`	object	Current approval step run details
`eligible_approvers_active`	array of strings	Emails of users currently eligible to approve
`next_eligible_approvers`	array of strings	Emails of users next in line for sequential approval (empty for parallel)
`variables_to_approve`	array	Variables pending approval review
`files`	array	Presigned download info for file-type variables (only present when `include_files=true`)

Step Run Object Fields

Field	Type	Description
`step_run_id`	string	Unique identifier for this step run
`step_id`	string	Identifier for the step definition
`step_name`	string	Human-readable step name
`step_type`	string	Type of workflow component (e.g., `"approval"`)
`status`	string	Step run status: `initiated`, `pending`, `in_progress`, `completed`, `failed`, `rejected`, `cancelled`
`variables`	array	Variables associated with this step run

Variable Object Fields

Used in both step_run.variables and variables_to_approve.

Field	Type	Description
`variable_type`	string	Type of the variable: `text`, `number`, `boolean`, `date`, `email`, `file`, `multiple_files`, `select`, `multi_select`, `user_entity`, `business`, `dynamic_list`, `dynamic_table`, `number_with_currency`, `conversation`
`value`	any	Current value of the variable (string, number, boolean, array of strings, or null)
`step_id`	string	ID of the step that collected this variable
`variable_id`	string	Unique identifier for the variable
`variable_title`	string or null	Human-readable variable name

File Object Fields

Only populated when include_files=true. Contains presigned download info for file-type variables.

Field	Type	Description
`file_id`	string	Unique file identifier
`file_name`	string	Name of the file
`content_type`	string	MIME type of the file
`download_url`	string	Presigned URL for downloading the file
`expires_at`	string	ISO 8601 timestamp when the download URL expires
`variable_id`	string	ID of the variable this file belongs to

Error Responses

400 Bad Request

Returned when the access token has no user behind it. client_credentials tokens act as the admin who created the application, so this applies only to tokens issued before application creators were recorded.

{
  "detail": "client_credentials tokens are not associated with a user"
}

401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an X-API-Key was sent instead of a bearer token. See OAuth error responses.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token lacks the required scope:

{
  "detail": "Insufficient scope; this endpoint requires: tasks:read"
}

Or when the user may not access this task:

{
  "detail": "You do not have access to this resource"
}

404 Not Found

Returned when the task does not exist.

{
  "detail": "Not found"
}

409 Conflict

Returned when the task is not currently at a pending approval step.

{
  "detail": "The task is not in a state that allows this operation"
}

422 Validation Error

Returned when request parameters are invalid.

{
  "detail": [
    {
      "loc": ["path", "task_id"],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ]
}

429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

{
  "detail": "Rate limit exceeded"
}

500 Internal Server Error

Returned when the request fails due to a server error.

{
  "detail": "Failed to get approval details"
}

Notes

For sequential approval workflows, eligible_approvers_active shows the approver(s) whose turn it is now, while next_eligible_approvers shows who comes after. For parallel approval workflows, all eligible approvers appear in eligible_approvers_active and next_eligible_approvers is empty.

Call this before Approve Task and check whether the access token’s user appears in eligible_approvers_active. Approving as a user who is not an eligible approver returns 400.

Presigned download URLs in the files array expire. Check the expires_at field and request new URLs if they have expired.

Use Cases

This endpoint is useful for:

Custom approval UIs - Build approval interfaces that display full context including variables and files
Pre-approval validation - Confirm the current user is an eligible approver before submitting
File review workflows - Download file attachments for external review before approving
Approval routing - Determine sequential vs parallel approval order and who is next in line

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Path Parameters

Query Parameters

Request Example

Response

Success Response

Response Fields

Step Run Object Fields

Variable Object Fields

File Object Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases

​Endpoint

​Authentication

​Path Parameters

​Query Parameters

​Request Example

​Response

​Success Response

​Response Fields

​Step Run Object Fields

​Variable Object Fields

​File Object Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​409 Conflict

​422 Validation Error

​429 Too Many Requests

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Path Parameters

Query Parameters

Request Example

Response

Success Response

Response Fields

Step Run Object Fields

Variable Object Fields

File Object Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases