Fetch actors

When to use this

Use GET /external/v1/actors to resolve actor IDs returned by external API responses. Actor records help partner systems identify ChartHero users and API keys without embedding repeated actor details in every record.

The actor list supports limit, offset, sort_order, and repeated actor_id filters. Pagination is offset-based and is not snapshot-consistent across repeated calls. See Pagination for parameter limits and unsupported-filter behavior.

Required scopes

The API key must be organization-scoped. Actor responses are limited to user and API-key actors in the caller organization.

Request

List available actors:

curl "https://api.charthero.ai/external/v1/actors?limit=50&offset=0&sort_order=asc" \
  -H "Authorization: Bearer <api_key>"

Fetch specific actors by repeating actor_id:

curl "https://api.charthero.ai/external/v1/actors?actor_id=11111111-1111-4111-8111-111111111111&actor_id=22222222-2222-4222-8222-222222222222" \
  -H "Authorization: Bearer <api_key>"

Response

User actor:

{
  "items": [
    {
      "actor_id": "11111111-1111-4111-8111-111111111111",
      "actor_type": "user",
      "external_ids": [
        {"source": "partner_ehr", "type": "provider_id", "value": "provider-778"}
      ],
      "display_name": "Dr. Synthetic Clinician",
      "first_name": "Synthetic",
      "last_name": "Clinician",
      "active": true
    }
  ],
  "limit": 50,
  "offset": 0,
  "total": 1
}

API-key actor:

{
  "items": [
    {
      "actor_id": "22222222-2222-4222-8222-222222222222",
      "actor_type": "api_key",
      "display_name": "Northfield sync key",
      "active": true,
      "status": "active"
    }
  ],
  "limit": 50,
  "offset": 0,
  "total": 1
}

Actor IDs are opaque ChartHero IDs. User actors use the same public name, discriminator, active-state, and provider external-identifier vocabulary as organization-adapter callback actors where those concepts overlap. Adapter launch-context callbacks may include adapter-only user context such as email, specialty, governance role, and functional roles. A user actor's external_ids lists the active identifiers ChartHero has on file for that user in your organization, such as a provider ID, using source, type, and value; it is empty when none is on file. API-key actors include status so consumers can preserve reference integrity when API keys create or update records.

Common errors