Get Tasks by External Source ID

Looks up tasks by the external source identifier recorded on them, so you can resolve one of your own records back to the Chamelio tasks it produced.

Endpoint

GET /v2/tasks/by-external-source-id

Authentication

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

Authorization: Bearer your_access_token

Required scope: tasks:read

Query Parameters

Parameter	Type	Required	Description
`external_source_id`	string	Yes	The external source identifier to filter tasks by. Must not be empty

External source IDs are assigned by whichever system created the task. This endpoint only reads them - there is no API field for setting one.

Request Example

curl -X GET "https://platform.chamelio.ai/v2/tasks/by-external-source-id?external_source_id=OPP-00123" \
  -H "Authorization: Bearer your_access_token"

import requests

url = "https://platform.chamelio.ai/v2/tasks/by-external-source-id"
headers = {
    "Authorization": "Bearer your_access_token"
}
params = {
    "external_source_id": "OPP-00123"
}

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

const params = new URLSearchParams({
  external_source_id: 'OPP-00123'
});

const response = await fetch(
  `https://platform.chamelio.ai/v2/tasks/by-external-source-id?${params}`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your_access_token'
    }
  }
);

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

Response

Success Response

Status Code: 200 OK

{
  "tasks": [
    {
      "task_id": 12345,
      "task_url": "https://app.chamelio.ai/workflows/tasks/12345",
      "task_title": "Vendor Contract Review - Acme Corporation",
      "workflow_id": "vendor_contract_review",
      "workflow_name": "Vendor Contract Review",
      "workflow_version": 1,
      "workflow_state_id": "ws_abc123",
      "status": "in_progress",
      "priority": "high",
      "current_step_run_id": "sr_002",
      "current_step_id": "review_step",
      "current_step_name": "AI Review",
      "current_step_type": "review",
      "created_at": "2025-01-20T10:30:00Z",
      "updated_at": "2025-01-20T10:35:00Z",
      "completed_at": null,
      "owner_email": "john.doe@example.com",
      "assignee_email": "legal@example.com",
      "collaborator_emails": [],
      "requester_email": "john.doe@example.com",
      "step_runs": [],
      "variables": []
    }
  ]
}

Response Fields

Field	Type	Description
`tasks`	array	Matching tasks the user is allowed to see. Empty when nothing matches

Task Object Fields

Each entry is a task object, the same shape returned by Get Task. See that page for the full field list, including the step_runs and variables structures.

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 does not carry the required scope.

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

422 Validation Error

Returned when external_source_id is missing or empty.

{
  "detail": [
    {
      "loc": ["query", "external_source_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

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

Notes

An external source ID can match more than one task, so tasks is always an array. A source ID with no matching tasks returns an empty array rather than a 404.

Only tasks the access token’s user is allowed to see are returned, so the same source ID can yield different results for different users.

Use Cases

Cross-system lookup - Jump from a record in your own system to its Chamelio tasks
Deduplication - Check whether a record already produced a task before creating another
Status embedding - Show Chamelio task status inside your own record view

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Query Parameters

Request Example

Response

Success Response

Response Fields

Task Object Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases

​Endpoint

​Authentication

​Query Parameters

​Request Example

​Response

​Success Response

​Response Fields

​Task Object Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​422 Validation Error

​429 Too Many Requests

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Query Parameters

Request Example

Response

Success Response

Response Fields

Task Object Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases