> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peerlogic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Organization, practice, and resource IDs

> Discover the organizations, regions, and practices your account can access, and use Peerlogic resource IDs correctly.

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](/authentication). For an overview of how API resources connect after you establish access, see [Resource relationships](/concepts/data-model).

<Note>
  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.
</Note>

## 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.

```json theme={null}
{
  "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:

1. Index organizations by `organization.id`.
2. Group each practice under its organization using `practice.organization_id`.
3. Index regions by `region.id` and associate each region with its organization using `region.organization_id`.
4. 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.

```bash theme={null}
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](/peerlogic-api-reference/organizations-and-practices/list-accessible-organizations-and-practices) |
| List accessible organization records | [List organizations](/peerlogic-api-reference/organizations-and-practices/list-organizations) |
| Retrieve one organization and its practice summaries | [Get organization](/peerlogic-api-reference/organizations-and-practices/get-organization) |
| List and filter accessible practice records | [List practices](/peerlogic-api-reference/organizations-and-practices/list-practices) |
| Retrieve one practice | [Get practice](/peerlogic-api-reference/organizations-and-practices/get-practice) |

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


## Related topics

- [Analytics scope and time ranges](/concepts/analytics-scope-and-time-ranges.md)
- [Pagination and filtering](/concepts/pagination-and-filtering.md)
- [List accessible organizations and practices](/peerlogic-api-reference/organizations-and-practices/list-accessible-organizations-and-practices.md)
- [List practices](/peerlogic-api-reference/organizations-and-practices/list-practices.md)
- [How Peerlogic data fits together](/concepts/data-model.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.