Skip to main content

Organization Groups

What is an Organization Group?​

An Organization Group is an administrative container that groups related Organizations so they can be managed as a unit. A typical example is a holding company with multiple subsidiaries — each subsidiary is its own Organization, and the holding company is the Organization Group.

Organization Groups have a name, an optional EIN (Employer Identification Number), and an optional physical address.

API operations​

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

List Organization Groups​

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

query OrganizationGroups($where: OrganizationGroupsFilterInput, $after: String, $first: Int) {
  organizationGroups(where: $where, after: $after, first: $first) {
    ... on OrganizationGroupsResults {
      nodes {
        id
        name
        ein
        address {
          addressLine1
          addressLine2
          city
          state
          country
          zip
        }
        organizations {
          nodes {
            id
            name
          }
          pageInfo {
            hasNextPage
            endCursor
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

Variables:

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

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

Example response:

{
  "data": {
    "organizationGroups": {
      "nodes": [
        {
          "id": "org-group-1",
          "name": "Acme Holdings",
          "ein": "12-3456789",
          "address": {
            "addressLine1": "123 Main St",
            "addressLine2": null,
            "city": "Austin",
            "state": "TX",
            "country": "US",
            "zip": "78701"
          },
          "organizations": {
            "nodes": [
              { "id": "org-1", "name": "Acme East" },
              { "id": "org-2", "name": "Acme West" }
            ],
            "pageInfo": { "hasNextPage": false, "endCursor": null }
          }
        }
      ],
      "pageInfo": { "hasNextPage": false, "endCursor": null }
    }
  }
}

Get an Organization Group​

Returns a single Organization Group by ID.

query OrganizationGroup($where: OrganizationGroupFilterInput!) {
  organizationGroup(where: $where) {
    ... on OrganizationGroup {
      id
      name
      ein
      address {
        addressLine1
        addressLine2
        city
        state
        country
        zip
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

Variables:

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

Example response:

{
  "data": {
    "organizationGroup": {
      "id": "org-group-1",
      "name": "Acme Holdings",
      "ein": "12-3456789",
      "address": {
        "addressLine1": "123 Main St",
        "addressLine2": null,
        "city": "Austin",
        "state": "TX",
        "country": "US",
        "zip": "78701"
      }
    }
  }
}

Create an Organization Group​

Creates a new Organization Group. Only name is required. ein and address are optional.

mutation CreateOrganizationGroup($input: CreateOrganizationGroupInput!) {
  createOrganizationGroup(input: $input) {
    ... on CreateOrganizationGroupResult {
      organizationGroup {
        id
        name
        ein
        address {
          addressLine1
          city
          state
          zip
        }
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

Variables:

{
  "input": {
    "name": "Acme Holdings",
    "ein": "12-3456789",
    "address": {
      "addressLine1": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "country": "US",
      "zip": "78701"
    }
  }
}

Example response:

{
  "data": {
    "createOrganizationGroup": {
      "organizationGroup": {
        "id": "new-org-group-id",
        "name": "Acme Holdings",
        "ein": "12-3456789",
        "address": {
          "addressLine1": "123 Main St",
          "city": "Austin",
          "state": "TX",
          "zip": "78701"
        }
      }
    }
  }
}

Update an Organization Group​

Updates an existing Organization Group. Only id is required. Include only the fields you want to change.

mutation UpdateOrganizationGroup($input: UpdateOrganizationGroupInput!) {
  updateOrganizationGroup(input: $input) {
    ... on UpdateOrganizationGroupResult {
      organizationGroup {
        id
        name
        ein
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

Variables:

{
  "input": {
    "id": "org-group-1",
    "name": "Acme Holdings International"
  }
}

Example response:

{
  "data": {
    "updateOrganizationGroup": {
      "organizationGroup": {
        "id": "org-group-1",
        "name": "Acme Holdings International",
        "ein": "12-3456789"
      }
    }
  }
}

Linking Organizations to a Group​

When creating an Organization, you can associate it with an Organization Group by passing organizationGroupId. You can also query the organizationGroup field on any Organization to see which group it belongs to.

Create an Organization within a Group​

mutation CreateOrganization($input: CreateOrganizationInput!) {
  createOrganization(input: $input) {
    ... on CreateOrganizationResult {
      organization {
        id
        name
        address {
          addressLine1
          city
          state
          zip
        }
        organizationGroup {
          id
          name
        }
      }
    }
    ... on BadRequestError {
      code
      message
    }
    ... on InternalServerError {
      code
      message
    }
  }
}

Variables:

{
  "input": {
    "name": "Acme East",
    "organizationGroupId": "org-group-1",
    "address": {
      "addressLine1": "100 East Blvd",
      "city": "New York",
      "state": "NY",
      "country": "US",
      "zip": "10001"
    }
  }
}

Query an Organization's Group​

query Organization($where: OrganizationFilterInput!) {
  organization(where: $where) {
    ... on Organization {
      id
      name
      organizationGroup {
        id
        name
      }
    }
  }
}

Relationships​

  • An Organization Group contains zero or more Organizations (one-to-many).
  • The organizations field on an Organization Group returns a paginated list of its member Organizations.
  • When creating an Organization, pass organizationGroupId to associate it with a group.
  • The organizationGroup field on the Organization type returns the group the Organization belongs to, if any.

Common scenarios​

Set up a holding company with subsidiaries​

Create the Organization Group first, then create Organizations linked to it:

Step 1 — Create the group:

mutation {
  createOrganizationGroup(input: {
    name: "National Benefits Corp"
    ein: "98-7654321"
    address: {
      addressLine1: "500 Corporate Blvd"
      city: "Chicago"
      state: "IL"
      country: "US"
      zip: "60601"
    }
  }) {
    ... on CreateOrganizationGroupResult {
      organizationGroup {
        id
        name
      }
    }
  }
}

Step 2 — Create Organizations within the group (using the returned id as organizationGroupId):

mutation {
  createOrganization(input: {
    name: "National Benefits — East"
    organizationGroupId: "<org-group-id-from-step-1>"
    address: {
      addressLine1: "100 East Blvd"
      city: "New York"
      state: "NY"
      country: "US"
      zip: "10001"
    }
  }) {
    ... on CreateOrganizationResult {
      organization {
        id
        name
        organizationGroup { id name }
      }
    }
  }
}

Repeat for each subsidiary Organization.

View all Organizations in a group​

Once several Organizations are linked, you can list them through the group's organizations field:

query {
  organizationGroup(where: { id: "<org-group-id>" }) {
    ... on OrganizationGroup {
      id
      name
      organizations {
        nodes {
          id
          name
        }
        pageInfo { hasNextPage endCursor }
      }
    }
  }
}