Get Approval Details

Endpoint

GET /tasks/{task_id}/approval-details

Authentication

This endpoint requires authentication via API key. Include your API key in the X-API-Key header:

X-API-Key: ca_your_api_key_here

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/tasks/12345/approval-details?include_files=true" \
  -H "X-API-Key: ca_your_api_key_here"

import requests

task_id = 12345

url = f"https://platform.chamelio.ai/tasks/{task_id}/approval-details"
headers = {
    "X-API-Key": "ca_your_api_key_here"
}
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/tasks/${taskId}/approval-details?include_files=true`,
  {
    method: 'GET',
    headers: {
      'X-API-Key': 'ca_your_api_key_here'
    }
  }
);

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`, `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, or null)
`step_id`	string	ID of the step that collected this variable
`variable_id`	string	Unique identifier for the variable

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

401 Unauthorized

Returned when authentication fails. See the authentication errors section for details.

{
  "detail": "Invalid API key"
}

404 Not Found

Returned when the task doesn’t exist or you don’t have access to it.

{
  "detail": "Task not found"
}

409 Conflict

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

{
  "detail": "Task is not at a pending approval step"
}

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"
    }
  ]
}

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.

Use this endpoint before calling Approve Task to verify the task is ready for approval and inspect what variables need review. Set include_files=true when you need to download file attachments for review.

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 - Check eligible approvers and pending variables before submitting a decision
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

401 Unauthorized

404 Not Found

409 Conflict

422 Validation Error

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

​401 Unauthorized

​404 Not Found

​409 Conflict

​422 Validation Error

​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

401 Unauthorized

404 Not Found

409 Conflict

422 Validation Error

500 Internal Server Error

Notes

Use Cases