Divisions
What is a Division?
A Division is a subdivision of an Organization. It represents a department, office, or business unit that has its own members and bank accounts while still belonging to a parent Organization, and that inherits the parent Organization's benefit offerings.
Divisions let you model the structure of a company — its regions, offices, or business units — while administering benefits centrally. For example, a company's "West Region" and "East Region" offices can be tracked as separate Divisions with their own members and bank accounts, even though both inherit the same benefits from the parent Organization.
Divisions can nest under other Divisions for deeper hierarchies (for example, Organization > Region > Department).
Offerings & enrollment
You do not create benefits or enroll members per Division. Benefits are managed once on the parent Organization and apply to every Division automatically, and you enroll members against the parent Organization's benefit — coverage applies within the member's Division. See Offerings & Enrollment Across Divisions for the full flow.
API operations
All Division operations are available through the Partner API (GraphQL).
List Divisions for an Organization
Returns a paginated list of Divisions belonging to a specific Organization. You can filter by IDs or names. organizationId is required.
query Divisions($where: DivisionsFilterInput!, $after: String, $first: Int) {
divisions(where: $where, after: $after, first: $first) {
... on DivisionsResults {
nodes {
id
name
ein
externalId
address {
addressLine1
addressLine2
city
state
country
zip
}
parentOrganization {
id
name
}
# Child divisions (non-paginated flat list, unlike the top-level `divisions` query)
divisions {
id
name
}
}
pageInfo {
hasNextPage
endCursor
}
}
... on BadRequestError {
code
message
}
... on InternalServerError {
code
message
}
}
}
Variables:
{
"where": {
"organizationId": "org-1"
},
"first": 10
}
Example response:
{
"data": {
"divisions": {
"nodes": [
{
"id": "division-1",
"name": "West Region",
"ein": "12-3456789",
"externalId": "WEST-001",
"address": {
"addressLine1": "456 Division Ave",
"addressLine2": null,
"city": "Austin",
"state": "TX",
"country": "US",
"zip": "78702"
},
"parentOrganization": {
"id": "org-1",
"name": "Acme Corp"
},
"divisions": []
}
],
"pageInfo": { "hasNextPage": false, "endCursor": null }
}
}
}
Get a Division
Returns a single Division by ID or external ID.
query Division($where: DivisionFilterInput!) {
division(where: $where) {
... on Division {
id
name
ein
externalId
address {
addressLine1
addressLine2
city
state
country
zip
}
parentOrganization {
id
name
}
# Child divisions (non-paginated flat list, unlike the top-level `divisions` query)
divisions {
id
name
}
}
... on BadRequestError {
code
message
}
... on InternalServerError {
code
message
}
}
}
Variables:
{
"where": { "id": "division-1" }
}
Example response:
{
"data": {
"division": {
"id": "division-1",
"name": "West Region",
"ein": "12-3456789",
"externalId": "WEST-001",
"address": {
"addressLine1": "456 Division Ave",
"addressLine2": null,
"city": "Austin",
"state": "TX",
"country": "US",
"zip": "78702"
},
"parentOrganization": {
"id": "org-1",
"name": "Acme Corp"
},
"divisions": []
}
}
}
Create a Division
Creates a new Division within an Organization. organizationId and name are required. You can optionally provide an externalId, and an ein (Employer Identification Number) for tax identification. To nest the Division under an existing Division instead of directly under the Organization, pass parentDivisionId.
mutation CreateDivision($input: CreateDivisionInput!) {
createDivision(input: $input) {
... on CreateDivisionResult {
division {
id
name
ein
externalId
address {
addressLine1
city
state
zip
}
parentOrganization {
id
name
}
}
}
... on BadRequestError {
code
message
}
... on InternalServerError {
code
message
}
}
}
Variables:
{
"input": {
"organizationId": "org-1",
"name": "West Region",
"ein": "12-3456789",
"externalId": "WEST-001",
"address": {
"addressLine1": "456 Division Ave",
"city": "Austin",
"state": "TX",
"country": "US",
"zip": "78702"
}
}
}
Example response:
{
"data": {
"createDivision": {
"division": {
"id": "new-division-id",
"name": "West Region",
"ein": "12-3456789",
"externalId": "WEST-001",
"address": {
"addressLine1": "456 Division Ave",
"city": "Austin",
"state": "TX",
"zip": "78702"
},
"parentOrganization": {
"id": "org-1",
"name": "Acme Corp"
}
}
}
}
}
Nesting a Division under another Division
To create a Division nested under an existing Division, include parentDivisionId:
{
"input": {
"organizationId": "org-1",
"parentDivisionId": "division-1",
"name": "Sales Team"
}
}
Update a Division
Updates an existing Division's name, address, external ID, or EIN. Only id is required. Include only the fields you want to change.
mutation UpdateDivision($input: UpdateDivisionInput!) {
updateDivision(input: $input) {
... on UpdateDivisionResult {
division {
id
name
ein
externalId
address {
addressLine1
city
state
zip
}
}
}
... on BadRequestError {
code
message
}
... on InternalServerError {
code
message
}
}
}
Variables:
{
"input": {
"id": "division-1",
"name": "West Region HQ",
"ein": "12-3456789"
}
}
Example response:
{
"data": {
"updateDivision": {
"division": {
"id": "division-1",
"name": "West Region HQ",
"ein": "12-3456789",
"address": {
"addressLine1": "456 Division Ave",
"city": "Austin",
"state": "TX",
"zip": "78702"
}
}
}
}
}
Query Divisions on an Organization (nested field)
You can also query Divisions directly through the divisions field on the Organization type. This supports optional filtering and pagination.
query Organization($where: OrganizationFilterInput!) {
organization(where: $where) {
... on Organization {
id
name
divisions {
nodes {
id
name
}
pageInfo {
hasNextPage
endCursor
}
}
}
}
}
Relationships
- A Division belongs to exactly one parent Organization.
- A Division can be nested under another Division by passing
parentDivisionIdwhen creating it. - The
parentOrganizationfield on a Division references the top-level Organization. - The
divisionsfield on a Division lists its child Divisions. - The
Organization.divisionsfield returns a paginated list of all Divisions for that Organization.
Common scenarios
Build a regional hierarchy with departments
Create top-level regional Divisions, then nest department Divisions under them:
Step 1 — Create a regional Division:
mutation {
createDivision(input: {
organizationId: "org-1"
name: "West Region"
address: {
addressLine1: "456 Division Ave"
city: "Austin"
state: "TX"
country: "US"
zip: "78702"
}
}) {
... on CreateDivisionResult {
division {
id
name
}
}
}
}
Step 2 — Nest a department under the region (using parentDivisionId):
mutation {
createDivision(input: {
organizationId: "org-1"
parentDivisionId: "<division-id-from-step-1>"
name: "Engineering"
}) {
... on CreateDivisionResult {
division {
id
name
parentOrganization { id name }
}
}
}
}
Repeat for additional departments (Sales, Operations, etc.).
Step 3 — Verify the hierarchy by querying the region and its child Divisions:
query {
division(where: { id: "<division-id-from-step-1>" }) {
... on Division {
id
name
divisions {
id
name
}
}
}
}