The Employee Demographics API v2 provides employee demographic data in a more structured, flexible model than v1. It is designed for clients and partners that need to retrieve employee data for reporting, synchronization, onboarding, verification, or downstream HR workflows.

How to use the API

When building to v2, developers should treat the API as a flexible employee record that can support both point-in-time lookups and broader synchronization use cases.

• Use the employee payload by domain rather than expecting a flat employee object.
• Expect some sections to represent current, future, and historical records instead of a single current-state object.
• Design your integration to read arrays and select the right record based on your use case, especially for pay, status, and position.
• Use filtering, pagination, and inclusion options to request only the data needed for your workflow.
• Plan for webhook-driven or repeated polling sync patterns where your solution needs to stay aligned with employee changes over time.

For most integrations, the best approach is to store the employee identifier, ingest only the domains you need, and build logic that can distinguish between current records and future or historical records.

What developers should expect in the response model

V2 organizes employee data into clearer domains rather than mixing many unrelated fields together. Depending on the integration, developers may interact with domains such as contact, sensitive data, employment information, rates, position, status, assignments, work authorization, and other work-related details.

This means implementers should build parsers that are resilient to nested objects, arrays, and structured values such as code-and-description pairs.

Key functionality to pay attention to

Temporal records for pay, status, and position

One of the most important functional differences in v2 is that pay, status, and position are no longer modeled only as current-state values.

• Pay is represented through rate records that can include current, future, and historical entries.
• Status is modeled as records rather than a single status object.
• Position is also modeled as records rather than a single position object.

This allows integrations to do more than simply ask, "What is true right now?" They can also support upcoming changes and history-based use cases, such as:

• consuming a future pay rate before it becomes effective
• tracking historical position changes
• understanding status changes over time

If your integration only needs the current state, do not assume the first record is the correct one. Your logic should intentionally select the record that represents the current effective state.

Sensitive data is separated behind its own security boundary

In v1, sensitive fields were part of the general employee information shape. In v2, sensitive data is separated into its own domain and access boundary.

This is important for both security planning and implementation design. Partners and clients should determine up front whether they need access to sensitive employee data or whether their use case can operate without it.

• If sensitive data is not needed, integrations should avoid depending on it.
• If sensitive data is required, consumers must ensure they are provisioned for the appropriate access.
• Developers should build for the possibility that sensitive fields may be omitted or masked depending on access and request configuration.

Do not assume all clients or partner applications will receive the same dataset. The payload a consumer can use may vary based on the security resources granted to that client.

Security resource options for v2

Employee Demographics API v2 supports different security resources so clients and partners can be provisioned according to the data they actually need. The available resources are below:

• EmployeeDemographicv2ThirdPartyInfo — access to general employee information
• EmployeeDemographicv2ThirdPartyRates — access to compensation and rate-related data
• EmployeeDemographicv2ThirdPartySensitive — access to sensitive employee demographic data

During onboarding, clients and partners should identify whether they want:

• access to general employee information only
• access to compensation or rate information
• access to sensitive data in addition to standard employee information

Example use case: identity management access

A client or partner may need Employee Demographics API v2 for identity management workflows, such as provisioning user accounts, keeping directory information in sync, or validating active employee identity details.

In this scenario, the integration needs general employee information but does not need SSN, date of birth, pay, or other compensation-related data. The appropriate security resource would be EmployeeDemographicv2ThirdPartyInfo, because it supports access to general employee demographic information without requiring sensitive or rates access.

• Use EmployeeDemographicv2ThirdPartyInfo when the use case only requires general employee identity and demographic details.
• Do not request EmployeeDemographicv2ThirdPartySensitive unless SSN, date of birth, or other sensitive fields are required.
• Do not request EmployeeDemographicv2ThirdPartyRates unless pay or rate-related data is required.

Teams should request only the minimum access needed for their integration. A consumer that does not need sensitive data should not build a dependency on the sensitive domain or request the associated access.

Structured fields instead of flat primitives

Many fields that were simple primitive values in v1 are now modeled as structured objects in v2. This commonly appears as code-and-description pairs, normalized name structures, and more explicit nested objects.

This gives the API a more extensible contract, but integrations will need to account for the shape change.

Assignments and expanded employment modeling

V2 introduces clearer separation of employment-related concepts and expands the model with additional domains such as assignments, employment information, and work authorization-related data.

For consumers, this means the API can support richer workforce scenarios, but implementers should not assume all work-related attributes live in one location.

Functional differences from v1

Documented breaking changes called out for v2 include field relocations, flattened-to-nested model changes, address key renaming, single-object to array conversions, and primitive-to-structured object changes.

Examples of v1 to v2 functional changes

Some of the most important documented examples include:

• info.firstName in v1 maps to contact.name.firstName in v2
• personalEmail in v1 maps to a normalized email field in v2
• currentPayRate in v1 maps to the current record within rates.records[] in v2
• futurePayRates in v1 maps to future records within rates.records[] in v2

These are not just naming updates. In many cases, they represent a functional change in how the consuming system must locate and interpret data.

Implementation guidance

For new integrations

• Build to the v2 schema directly instead of designing around v1 assumptions.
• Consume only the domains your use case requires.
• Implement record-selection logic for pay, status, and position from the start.
• Design your schema handling for nested objects and arrays.
• Decide early whether your application truly requires sensitive data access.

For migrations from v1

• Map all field relocations before development begins.
• Identify every place your current integration assumes a single object instead of a collection.
• Update any transformation logic that expects flat primitive values.
• Test for cases where sensitive data is no longer present in the general employee object.
• Retest downstream reporting, matching, and synchronization logic against current, future, and past records.

The cleanest v2 implementations are the ones that treat the API as a structured employee domain model, not as a direct field-for-field replacement of v1.

Best practices

• Use only the domains and access levels your integration needs.
• Be explicit about how your application determines the current effective record.
• Handle optional or restricted domains gracefully.
• Do not assume v1 field paths, shapes, or object locations still apply.
• Test with employees that have future changes, historical changes, and varying access permissions.