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 benefit packages, members, and bank accounts while still belonging to a parent Organization.

Divisions let you model structures where different parts of a company need separate benefit configurations. For example, a company's "West Region" office might offer different benefits than its "East Region" office, even though both belong to the same Organization.

Divisions can nest under other Divisions for deeper hierarchies (for example, Organization > Region > Department).

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
        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",
          "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.

query Division($where: DivisionFilterInput!) {
  division(where: $where) {
    ... on Division {
      id
      name
      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",
      "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. 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
        address {
          addressLine1
          city
          state
          zip
        }
        parentOrganization {
          id
          name
        }
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

Variables:

{
  "input": {
    "organizationId": "org-1",
    "name": "West Region",
    "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",
        "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 or address. Only id is required. Include only the fields you want to change.

mutation UpdateDivision($input: UpdateDivisionInput!) {
  updateDivision(input: $input) {
    ... on UpdateDivisionResult {
      division {
        id
        name
        address {
          addressLine1
          city
          state
          zip
        }
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

Variables:

{
  "input": {
    "id": "division-1",
    "name": "West Region HQ"
  }
}

Example response:

{
  "data": {
    "updateDivision": {
      "division": {
        "id": "division-1",
        "name": "West Region HQ",
        "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 parentDivisionId when creating it.
• The parentOrganization field on a Division references the top-level Organization.
• The divisions field on a Division lists its child Divisions.
• The Organization.divisions field 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
      }
    }
  }
}