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.
The full containment hierarchy is Organization → Company → Division → Business Unit → Department. Location is a separate, parallel concept, not nested under department. See the Glossary for definitions.
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",
"companies": [
{ "id": 101, "code": "ACME", "name": "Acme Corp" }
]
}
]
}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", "code": "ACME", "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "organizationName": "Acme Corporation" },
{ "id": 102, "name": "Acme West", "code": "ACMEW", "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "organizationName": "Acme Corporation" }
]
}Step 3: Fetch departments
Departments can be filtered by organization, company, division, or business unit. In practice, most integrations only need company and department, division and business unit exist for companies that use them, but aren't something every integration has to account for.
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",
"code": "ENG",
"businessUnitId": 1,
"businessUnitName": "Product",
"businessUnitCode": "PROD",
"divisionId": 1,
"divisionName": "Corporate",
"divisionCode": "CORP",
"companyId": 101,
"companyName": "Acme Corp",
"companyCode": "ACME",
"organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"organizationName": "Acme Corporation"
}
]
}A department carries its full chain back up to the organization: division, business unit, company, and organization all come back on every department record, not just the department's own ID.
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": 2,
"items": [
{
"id": 3,
"code": "HQ",
"description": "Headquarters",
"organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"companyId": 101,
"street1": "100 Main St",
"street2": null,
"city": "New York",
"state": "NY",
"zipCode": "10001",
"isWorkFromHome": false
}
]
}There's no name or address field on a location. It's description (a label) plus separate street1/street2/city/state/zipCode fields, and an isWorkFromHome flag, this is the same shape referenced in Employee Write-Back when assigning a work location.
Try it in the playground
Test these endpoints interactively in the API reference: