Skip to main content

IndividualsFilterInput

Filter criteria used when querying for Individuals

input IndividualsFilterInput {
  benefitIds: [ID!]
  benefitsProgramIds: [ID!]
  externalUserIds: [ID!]
  ids: [ID!]
  organizationIds: [ID!]
  platformIds: [ID!]
  statuses: [AccountEnrollmentStatus!]
}

Fields​

IndividualsFilterInput.benefitIds ● [ID!] list scalar​

If specified, only returns Individuals who are enrolled in these Benefits

IndividualsFilterInput.benefitsProgramIds ● [ID!] list scalar​

If specified, only returns Individuals who are enrolled in these Benefits Programs

IndividualsFilterInput.externalUserIds ● [ID!] list scalar​

If specified, only returns Individuals who hold one of these values as an external identifier.

Without platformIds, the values are matched against the external user ID on the Individual's organization memberships — the member identifier supplied through createOrUpdateOrganizationMembership. With platformIds, they are matched against the identifiers recorded for those external platforms instead, and membership external user IDs are not searched at all; see platformIds for how that lookup differs.

In both cases an explicitly empty list matches no Individuals (it is not treated as "no filter"), a maximum of 100 values may be supplied (more than that is rejected as a top-level GraphQL error with extension code BAD_USER_INPUT, not as the BadRequestError member of this query's result union), and Individuals without a resolvable first and last name are never returned by this query, so an Individual whose profile never captured a name will not be found by an external identifier. The rest of this description covers the membership lookup.

Matching ignores case, whitespace and punctuation, so values differing only in those respects are treated as the same identifier (AB-123-456 and ab123456 match the same Individual). A value consisting only of punctuation or whitespace matches no Individuals. A value that is already a 64-character lowercase hexadecimal string is looked up as sent and, unlike other values, matched case-sensitively: a member identifier supplied to createOrUpdateOrganizationMembership in that form is found by that same string.

A membership matches regardless of employment status: an Individual whose membership has been terminated is still returned, so that looking up an identifier you hold on file never reports "not found" for a former member. Compose statuses to narrow to current members.

An external user ID is unique within an organization, not across them, and this filter searches every organization you can see. One value can therefore return more than one Individual when separate organizations independently use the same member identifier. Compose organizationIds to scope a lookup to a single organization.

IndividualsFilterInput.ids ● [ID!] list scalar​

If specified, only returns Individuals matching these Individual IDs

IndividualsFilterInput.organizationIds ● [ID!] list scalar​

If specified, only returns Individuals who are members of these Organizations

IndividualsFilterInput.platformIds ● [ID!] list scalar​

If specified, qualifies externalUserIds with one or more external platforms linked to your account: only Individuals holding one of the supplied values as their identifier on one of the supplied platforms are returned. Each value is an id returned by linkedExternalPlatforms. Values within externalUserIds are ORed, values within platformIds are ORed, and the two lists are ANDed; they are not paired positionally.

A platform qualifies a lookup and is not a filter on its own: supplying platformIds without externalUserIds is rejected as a top-level GraphQL error with extension code BAD_USER_INPUT. An explicitly empty platformIds beside a non-empty externalUserIds matches no Individuals. Omitting platformIds (or passing null) keeps the membership lookup described on externalUserIds; the two sources are never combined in one query. A value that is not one of your linked platform IDs is rejected as a top-level GraphQL error with extension code BAD_USER_INPUT.

Matching ignores case, whitespace and punctuation, as for the membership lookup, and a value of only punctuation or whitespace matches no Individuals. Every value is matched as an identifier; a 64-character lowercase hexadecimal value is not treated as a pre-hashed identifier.

An identifier is not unique on a platform: one value can return more than one Individual, even within one organization, and one Individual can match through several platforms in one query. The response does not say which platform or identifier matched. To resolve a single Individual, send one platform per query and compose ids or organizationIds when more than one is returned. organizationIds filters the Individuals returned; it does not restrict which organization an identifier was recorded for.

Terminated members are still returned here too; compose statuses to narrow. The 100-value maximum on externalUserIds applies unchanged.

IndividualsFilterInput.statuses ● [AccountEnrollmentStatus!] list enum​

If specified, returns a filtered list of Individuals based on the specified statuses

Member Of​

individuals query