Organization, practice, and resource IDs

Authentication establishes who is making a request. Organization and practice access establishes which customer resources that account is authorized to use. Peerlogic organizes customer data around organizations and practices, with optional region groupings:

An organization represents the top-level customer account.
A practice represents a location and is the primary scope for calls, contacts, patients, appointments, subscriptions, and reporting data.
A region is a named grouping of practices within an organization. A practice can belong to no regions, one region, or multiple regions.

Use GET /api/org-hierarchy/ after authentication to discover the resources available to your account. The response includes only resources your account can access. If you have not obtained an access token yet, begin with Authentication. For an overview of how API resources connect after you establish access, see Resource relationships.

Authentication identifies your account. The hierarchy response identifies the organizations and practices that account can use. A valid access token does not grant access to every Peerlogic customer.

Resource identifiers

Most Peerlogic-owned resources are identified by short UUIDs. These are 22-character strings, such as 9AxAFr4n63uputNXKo89x1, and appear throughout the API:

In resource responses as id
In request paths such as /api/practices/{id}/
In filters such as organization_id, region_id, practice_id, and practice_ids
In relationship fields such as organization_id and call_id

Treat every resource ID as an opaque, case-sensitive string. Store and send the value exactly as returned. Do not convert it to a 36-character UUID, derive meaning from its characters, or assume that IDs from different resource types are interchangeable. Organization and practice IDs are especially important because they define the customer scope of most API activity. A practice ID commonly scopes calls, contacts, patients, appointments, conversations, subscriptions, tasks, and analytics. An organization or region ID commonly selects a group of accessible practices.

Response structure

The endpoint returns three flat arrays under data:

Array	Purpose	Relationship fields
`organization`	Accessible organizations	`id`
`regions`	Accessible practice groupings	`organization_id` links each region to its organization
`practices`	Accessible customer locations	`organization_id` links the practice to its organization; `region_practices` lists every region that includes the practice

The organization property is an array even though its name is singular. Depending on your access scope, any array can be empty. For example, an account with direct access to one practice can receive that practice without receiving its parent organization or regions.

{
  "data": {
    "organization": [
      {
        "id": "9AxAFr4n63uputNXKo89W2",
        "name": "Example Veterinary Group",
        "view": true,
        "manage": false
      }
    ],
    "regions": [
      {
        "id": "AfRqcLmujyiMWu96qP5uze",
        "name": "West",
        "organization_id": "9AxAFr4n63uputNXKo89W2",
        "view": true,
        "manage": false
      },
      {
        "id": "ZWriUzHDX6CutF9wfLNxvx",
        "name": "Pilot practices",
        "organization_id": "9AxAFr4n63uputNXKo89W2",
        "view": true,
        "manage": false
      }
    ],
    "practices": [
      {
        "id": "9AxAFr4n63uputNXKo89x1",
        "name": "Example Veterinary Group - Phoenix",
        "organization_id": "9AxAFr4n63uputNXKo89W2",
        "region_practices": [
          "AfRqcLmujyiMWu96qP5uze",
          "ZWriUzHDX6CutF9wfLNxvx"
        ],
        "view": true,
        "manage": false,
        "direct": false
      }
    ]
  }
}

Build organization and region views

Organizations and practices form the primary hierarchy. Regions are overlapping groupings, not an intermediate parent level. If your integration needs organization and region views, build them from the returned identifiers:

Index organizations by organization.id.
Group each practice under its organization using practice.organization_id.
Index regions by region.id and associate each region with its organization using region.organization_id.
Add a practice to every region listed in practice.region_practices.

Do not select a single “parent region” for a practice or assume that regions partition an organization’s practices. Use every returned region association. Do not infer access to another organization, practice, or region that is absent from the response.

Permission indicators

Each hierarchy object includes permission indicators for the authenticated account:

Field	Meaning
`view`	The account has view-level access at this object level.
`manage`	The account has management-level access at this object level.
`direct`	For practices only, the account’s practice access is assigned directly rather than through an organization or region.

These indicators describe access at that hierarchy level. They do not replace the authorization rules of another endpoint. An API request can still return 403 Forbidden when the account lacks permission for the requested operation.

Filter the response

You can request the complete accessible hierarchy or filter it using exactly one of these parameter families:

Parameter	Type	Example
`organization_id`	string	`?organization_id=9AxAFr4n63uputNXKo89W2`
`region_ids`	repeated string	`?region_ids=AfRqcLmujyiMWu96qP5uze&region_ids=ZWriUzHDX6CutF9wfLNxvx`
`practice_ids`	repeated string	`?practice_ids=9AxAFr4n63uputNXKo89x1&practice_ids=azmG9tvad5WJXWX8aF8qiP`

Do not combine organization_id, region_ids, and practice_ids in the same request. The API returns 400 Bad Request when more than one filter family is supplied.

curl --request GET \
  --url 'https://api.prod.peerlogic.com/api/org-hierarchy/?organization_id=9AxAFr4n63uputNXKo89W2' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Accept: application/json'

Use practice IDs

Most operational endpoints are practice-scoped. Preserve the returned practice.id values and use them wherever an endpoint accepts practice_id or practice_ids. Common examples include:

Retrieving calls and call insights for selected locations
Looking up contacts, patients, and appointments
Creating event subscriptions for a practice
Aggregating reporting data across accessible practices

Refresh the hierarchy periodically and whenever the API returns an authorization error for a previously stored identifier. Access assignments and customer organization structures can change.

Entity endpoints

Use the hierarchy endpoint to discover access and region membership. Use the organization and practice endpoints when you need the full resource details:

Need	Endpoint
Discover accessible organizations, regions, and practices	List accessible organizations and practices
List accessible organization records	List organizations
Retrieve one organization and its practice summaries	Get organization
List and filter accessible practice records	List practices
Retrieve one practice	Get practice

These customer-facing endpoints are read-only. Peerlogic staff administration operations are intentionally excluded from the public API reference.

Start here

Core Concepts

Workflows

Organization, practice, and resource IDs

Resource identifiers

Response structure

Build organization and region views

Permission indicators

Filter the response

Use practice IDs

Entity endpoints

​Resource identifiers

​Response structure

​Build organization and region views

​Permission indicators

​Filter the response

​Use practice IDs

​Entity endpoints

Resource identifiers

Response structure

Build organization and region views

Permission indicators

Filter the response

Use practice IDs

Entity endpoints