External IDs

What is an External ID?

An external ID is an optional, partner-scoped identifier that you can assign to Organization Groups, Organizations, and Divisions. It lets you map First Dollar entities to corresponding records in your own systems (HR platforms, benefits administration tools, payroll systems, etc.) without needing to store First Dollar's internal IDs on your side.

External IDs are:

• Optional — you can create and manage entities without them.
• Partner-scoped — they must be unique within your account.
• Mutable — you can set them at creation time or add/change them later via an update.
• Queryable — you can look up any entity by its external ID instead of its First Dollar ID.

Supported entity types

Entity	Create Input	Update Input	Filter (single)	Filter (batch)
Organization Group	CreateOrganizationGroupInput	UpdateOrganizationGroupInput	externalId	externalIds
Organization	CreateOrganizationInput	UpdateOrganizationInput	externalId	externalIds
Division	CreateDivisionInput	UpdateDivisionInput	externalId	externalIds

Assigning external IDs

At creation time

Pass externalId alongside the other fields when creating an entity:

mutation {
  createOrganization(input: {
    name: "Acme East"
    externalId: "HRIS-ORG-4521"
  }) {
    ... on CreateOrganizationResult {
      organization {
        id
        externalId
      }
    }
  }
}

The same field is available on createOrganizationGroup and createDivision.

On an existing entity

Use the corresponding update mutation to add or change an external ID:

mutation {
  updateOrganization(input: {
    id: "<first-dollar-org-id>"
    name: "Acme East"
    externalId: "HRIS-ORG-4521"
  }) {
    ... on UpdateOrganizationResult {
      organization {
        id
        externalId
      }
    }
  }
}

Backfilling external IDs in bulk

If you have existing entities that need external IDs, iterate through them and call the update mutation for each one:

Step 1 — List entities that need external IDs:

query {
  organizations(first: 100) {
    ... on OrganizationsResults {
      nodes {
        id
        name
        externalId
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Step 2 — For each entity where externalId is null, call the update mutation with your system's identifier. Use pagination (after / endCursor) to walk through all pages.

Looking up entities by external ID

Single lookup

Use the singular filter input to fetch one entity by its external ID:

query {
  organization(where: { externalId: "HRIS-ORG-4521" }) {
    ... on Organization {
      id
      name
      externalId
    }
  }
}

This works the same way for Divisions and Organization Groups:

# Division
query {
  division(where: { externalId: "HRIS-DIV-100" }) {
    ... on Division { id name externalId }
  }
}

# Organization Group
query {
  organizationGroup(where: { externalId: "HRIS-GRP-10" }) {
    ... on OrganizationGroup { id name externalId }
  }
}

Batch lookup

The plural list queries accept externalIds (an array) to fetch multiple entities at once:

query {
  organizations(where: { externalIds: ["HRIS-ORG-4521", "HRIS-ORG-4522", "HRIS-ORG-4523"] }) {
    ... on OrganizationsResults {
      nodes {
        id
        name
        externalId
      }
    }
  }
}

This is useful for syncing a batch of records from your system. The same externalIds filter is available on the divisions and organizationGroups queries.