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
    }
    ... on BadRequestError {
      code
      message
    }
  }
}

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 }
  }
}

If no entity matches, organization, division and organizationGroup return BadRequestError with code: NOT_FOUND. Treat only NOT_FOUND as "no match". Treat any other error as a failed request, not as a missing entity.

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.

Member IDs for Individuals

An Individual's ID in your system is a member ID on their Organization membership, not an External ID on the Individual. Set it as externalUserId with createOrUpdateOrganizationMembership. A member ID is unique within one Organization, not across Organizations.

To find Individuals by member ID, pass externalUserIds to the individuals query. Add organizationIds to limit the lookup to one Organization, because the same member ID can exist in more than one Organization.

query IndividualsByMemberId($where: IndividualsFilterInput!) {
  individuals(where: $where) {
    ... on IndividualsResults {
      nodes {
        id
        name {
          firstName
          lastName
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
    ... on BadRequestError {
      code
      message
    }
  }
}

{
  "where": {
    "externalUserIds": ["HRIS-EMP-00042"],
    "organizationIds": ["<organizationId>"]
  }
}

Things to know about this lookup:

• Matching ignores case, spaces and punctuation, so AB-123-456 and ab123456 find the same Individual.
• Former members are returned too. Add statuses to return only current members.
• You can send a maximum of 100 values in one request.
• To look up the identifier that an external platform holds for an Individual, add platformIds with an id from linkedExternalPlatforms. See IndividualsFilterInput for how a platform lookup differs.