Integrations
Organization Structure
Traverse the organization hierarchy — organizations, companies, departments, and locations.
This guide shows how to traverse the Netchex organization hierarchy: fetching the top-level organizations, then drilling into companies, departments, and locations.
Overview
Four v3 endpoints represent the hierarchy:
GET /organizations— top-level organization nodesGET /companies— companies within an organizationGET /departments— departments within companies or divisionsGET /locations— physical work locations
Step 1 — Fetch organizations
GET https://external-api.netchexonline.net/organizations?api-version=3.0
Authorization: ApiKey YOUR_API_KEYKey parameters:
| Parameter | Type | Description |
|---|---|---|
organization-ids | GUID[] | Filter to specific organizations |
company-ids | integer[] | Filter organizations that contain these companies |
page-number / page-size | integer | 1-based pagination |
{
"pageNumber": 1,
"pageSize": 50,
"totalItemsCount": 1,
"items": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Acme Corporation"
}
]
}Most API calls across v3 accept organization-id (singular GUID) or company-ids (array of integers). Start by fetching organizations to obtain the GUID, then use it to filter all subsequent requests.
Step 2 — Fetch companies
GET https://external-api.netchexonline.net/companies?organization-ids=a1b2c3d4-e5f6-7890-abcd-ef1234567890&api-version=3.0
Authorization: ApiKey YOUR_API_KEY{
"pageNumber": 1,
"pageSize": 50,
"totalItemsCount": 2,
"items": [
{ "id": 101, "name": "Acme Corp", "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
{ "id": 102, "name": "Acme West", "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
]
}Step 3 — Fetch departments
Departments can be filtered by organization, company, division, or business unit:
GET https://external-api.netchexonline.net/departments?company-ids=101&api-version=3.0
Authorization: ApiKey YOUR_API_KEYKey parameters:
| Parameter | Type | Description |
|---|---|---|
organization-ids | GUID[] | Filter by organization |
company-ids | integer[] | Filter to one or more companies |
division-ids | integer[] | Filter by division |
business-unit-ids | integer[] | Filter by business unit |
page-number / page-size | integer | Pagination |
{
"pageNumber": 1,
"pageSize": 50,
"totalItemsCount": 5,
"items": [
{ "id": 10, "name": "Engineering", "companyId": 101 },
{ "id": 11, "name": "Sales", "companyId": 101 }
]
}You can also fetch a single department by ID:
GET https://external-api.netchexonline.net/departments/10?api-version=3.0
Authorization: ApiKey YOUR_API_KEYStep 4 — Fetch locations
GET https://external-api.netchexonline.net/locations?company-ids=101&api-version=3.0
Authorization: ApiKey YOUR_API_KEY{
"pageNumber": 1,
"pageSize": 50,
"totalItemsCount": 3,
"items": [
{ "id": 3, "name": "HQ", "companyId": 101, "address": "100 Main St" },
{ "id": 4, "name": "Warehouse", "companyId": 101, "address": "200 Dock Rd" }
]
}Try it in the playground
Test these endpoints interactively in the API reference: