Organizations

What is an Organization?

An Organization is an employer group. It represents a company or entity that manages benefits programs on behalf of individuals — for example, an employer offering health benefits to its employees.

Organizations sit in the middle of the hierarchy. An Organization can belong to an Organization Group and can contain Divisions.

API operations

All Organization operations are available through the Partner API (GraphQL).

List Organizations

Returns a paginated list of Organizations. You can filter by IDs or names.

query Organizations($where: OrganizationsFilterInput, $after: String, $first: Int) {
  organizations(where: $where, after: $after, first: $first) {
    ... on OrganizationsResults {
      nodes {
        id
        name
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

Variables:

{
  "where": {
    "names": ["Acme East"]
  },
  "first": 10
}

All filter fields are optional. Omitting where returns all Organizations.

Example response:

{
  "data": {
    "organizations": {
      "nodes": [
        {
          "id": "org-1",
          "name": "Acme East"
        }
      ],
      "pageInfo": { "hasNextPage": false, "endCursor": null }
    }
  }
}

Get an Organization

Returns a single Organization by ID.

query Organization($where: OrganizationFilterInput!) {
  organization(where: $where) {
    ... on Organization {
      id
      name
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

Variables:

{
  "where": { "id": "org-1" }
}

Example response:

{
  "data": {
    "organization": {
      "id": "org-1",
      "name": "Acme East"
    }
  }
}

Create an Organization

Creates a new Organization. name is required.

mutation CreateOrganization($input: CreateOrganizationInput!) {
  createOrganization(input: $input) {
    ... on CreateOrganizationResult {
      organization {
        id
        name
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

Variables:

{
  "input": {
    "name": "Acme East"
  }
}

Example response:

{
  "data": {
    "createOrganization": {
      "organization": {
        "id": "new-org-id",
        "name": "Acme East"
      }
    }
  }
}

Update an Organization

Updates an existing Organization. Both id and name are required.

mutation UpdateOrganization($input: UpdateOrganizationInput!) {
  updateOrganization(input: $input) {
    ... on UpdateOrganizationResult {
      organization {
        id
        name
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

Variables:

{
  "input": {
    "id": "org-1",
    "name": "Acme East Regional"
  }
}

Example response:

{
  "data": {
    "updateOrganization": {
      "organization": {
        "id": "org-1",
        "name": "Acme East Regional"
      }
    }
  }
}

Relationships

• An Organization can belong to an Organization Group (many-to-one). See Organization Groups for how to link an Organization to a Group.
• An Organization can contain zero or more Divisions (one-to-many). See Divisions for how to create Divisions within an Organization.
• An Organization manages Benefits Programs on behalf of Individuals. See Setup & Enrollment for how to create programs and enroll members.

Common scenarios

Create an Organization and add Divisions

Step 1 — Create the Organization:

mutation {
  createOrganization(input: {
    name: "Acme East"
  }) {
    ... on CreateOrganizationResult {
      organization {
        id
        name
      }
    }
  }
}

Step 2 — Create Divisions within the Organization (using the returned id as organizationId):

mutation {
  createDivision(input: {
    organizationId: "<org-id-from-step-1>"
    name: "Sales"
  }) {
    ... on CreateDivisionResult {
      division {
        id
        name
        parentOrganization { id name }
      }
    }
  }
}

Repeat for each Division (Engineering, Operations, etc.).

Find an Organization by name

Use the names filter to search for a specific Organization:

query {
  organizations(where: { names: ["Acme East"] }) {
    ... on OrganizationsResults {
      nodes {
        id
        name
      }
    }
  }
}