Workday User Management API Guide

Auth method: OAuth 2.0 (Bearer token via Client Credentials or Authorization Code grant)

Setup steps

1. In Workday, navigate to Edit Tenant Setup – Security and enable OAuth 2.0.
2. Create an API Client: go to Register API Client for Integrations task, set grant type (Client Credentials for server-to-server), and assign required functional areas/scopes.
3. Note the Client ID and generate a Client Secret.
4. Request a token: POST to https:///ccx/oauth2//token with grant_type=client_credentials, client_id, and client_secret.
5. Use the returned access_token as a Bearer token in the Authorization header for all API calls.
6. For SCIM, additionally configure an SSO integration and map the SCIM client to the tenant's SCIM endpoint.

Required scopes

List Workers

• Method: GET
• URL: https://<host>/ccx/api/v1/<tenant>/workers
• Watch out for: Returns summary worker objects only. Use the individual worker endpoint or SOAP Get_Workers for full field detail.

Request example

GET /ccx/api/v1/mycompany/workers?limit=100&offset=0
Authorization: Bearer <token>

Response example

{
  "data": [
    {"id": "abc123", "descriptor": "Jane Doe",
     "href": "/workers/abc123"}
  ],
  "total": 5000,
  "offset": 0
}

Get Worker

• Method: GET
• URL: https://<host>/ccx/api/v1/<tenant>/workers/{id}
• Watch out for: Field availability depends on domain security policy configuration in the tenant. Missing fields often indicate a security permission gap, not an API bug.

Request example

GET /ccx/api/v1/mycompany/workers/abc123
Authorization: Bearer <token>

Response example

{
  "id": "abc123",
  "descriptor": "Jane Doe",
  "primaryJob": {"jobTitle": "Engineer"},
  "businessTitle": "Senior Engineer"
}

Hire Employee (SOAP)

• Method: POST
• URL: https://<host>/ccx/service/<tenant>/Staffing/v43.1 (Hire_Employee operation)
• Watch out for: Hire is a multi-step business process in Workday. The API call initiates the process; subsequent steps (background check, onboarding tasks) may require additional API calls or manual completion depending on tenant configuration.

Request example

<bsvc:Hire_Employee_Request>
  <bsvc:Business_Process_Parameters/>
  <bsvc:Hire_Employee_Data>
    <bsvc:Applicant_Reference bsvc:Descriptor="Jane Doe"/>
    <bsvc:Organization_Reference bsvc:Descriptor="Engineering"/>
  </bsvc:Hire_Employee_Data>
</bsvc:Hire_Employee_Request>

Response example

<bsvc:Hire_Employee_Response>
  <bsvc:Event_Reference bsvc:Descriptor="Hire: Jane Doe"/>
  <bsvc:Employee_Reference bsvc:Descriptor="Jane Doe"/>
</bsvc:Hire_Employee_Response>

Terminate Employee (SOAP)

• Method: POST
• URL: https://<host>/ccx/service/<tenant>/Staffing/v43.1 (Terminate_Employee operation)
• Watch out for: Termination date must be on or after the most recent hire date. Terminating a worker does not automatically disable the Workday user account; that requires a separate Maintain User Account call or security group removal.

Request example

<bsvc:Terminate_Employee_Request>
  <bsvc:Employee_Reference bsvc:Descriptor="Jane Doe"/>
  <bsvc:Termination_Data>
    <bsvc:Termination_Date>2025-06-01</bsvc:Termination_Date>
    <bsvc:Primary_Reason_Reference bsvc:Descriptor="Resignation"/>
  </bsvc:Termination_Data>
</bsvc:Terminate_Employee_Request>

Response example

<bsvc:Terminate_Employee_Response>
  <bsvc:Event_Reference bsvc:Descriptor="Termination: Jane Doe"/>
</bsvc:Terminate_Employee_Response>

Get Workers (SOAP – full detail)

• Method: POST
• URL: https://<host>/ccx/service/<tenant>/Human_Resources/v43.1 (Get_Workers operation)
• Watch out for: Response size can be very large. Use Response_Group flags to limit returned data segments (e.g., Include_Personal_Information, Include_Employment_Information).

Request example

<bsvc:Get_Workers_Request>
  <bsvc:Request_Criteria>
    <bsvc:Worker_Reference bsvc:Descriptor="Jane Doe"/>
  </bsvc:Request_Criteria>
  <bsvc:Response_Filter>
    <bsvc:Page>1</bsvc:Page>
    <bsvc:Count>100</bsvc:Count>
  </bsvc:Response_Filter>
</bsvc:Get_Workers_Request>

Response example

<!-- Returns full Worker_Data including Personal_Data,
     Employment_Data, Organization_Data, etc. -->
<bsvc:Get_Workers_Response>
  <bsvc:Response_Data>
    <bsvc:Worker>...</bsvc:Worker>
  </bsvc:Response_Data>
</bsvc:Get_Workers_Response>

Maintain User Account (SOAP)

• Method: POST
• URL: https://<host>/ccx/service/<tenant>/Human_Resources/v43.1 (Maintain_User_Account operation)
• Watch out for: This operation manages the Workday application login account, not the worker record. Disabling the account (Account_Disabled=true) revokes Workday UI access but does not terminate the worker.

Request example

<bsvc:Maintain_User_Account_Request>
  <bsvc:User_Account_Data>
    <bsvc:User_Name>jdoe@company.com</bsvc:User_Name>
    <bsvc:Worker_Reference bsvc:Descriptor="Jane Doe"/>
    <bsvc:Account_Disabled>false</bsvc:Account_Disabled>
  </bsvc:User_Account_Data>
</bsvc:Maintain_User_Account_Request>

Response example

<bsvc:Maintain_User_Account_Response>
  <bsvc:User_Account_Reference bsvc:Descriptor="jdoe@company.com"/>
</bsvc:Maintain_User_Account_Response>

SCIM Get Users

• Method: GET
• URL: https://<host>/ccx/scim/v2/<tenant>/Users
• Watch out for: Workday's SCIM endpoint is primarily used for inbound provisioning into Workday (e.g., Strategic Sourcing). For outbound provisioning FROM Workday to other apps, Workday acts as the IdP/source and pushes via Workday Studio or EIB integrations, not SCIM pull.

Request example

GET /ccx/scim/v2/mycompany/Users?startIndex=1&count=100
Authorization: Bearer <token>

Response example

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 500,
  "startIndex": 1,
  "Resources": [
    {"id": "abc123", "userName": "jdoe@company.com",
     "active": true}
  ]
}

SCIM Create User

• Method: POST
• URL: https://<host>/ccx/scim/v2/<tenant>/Users
• Watch out for: SCIM user creation in Workday does not create a full worker/employee record. It creates a Workday user account. Full worker creation requires the Hire business process via SOAP/REST Staffing API.

Request example

POST /ccx/scim/v2/mycompany/Users
Authorization: Bearer <token>
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "jdoe@company.com",
  "name": {"givenName": "Jane", "familyName": "Doe"},
  "active": true
}

Response example

{
  "id": "abc123",
  "userName": "jdoe@company.com",
  "active": true,
  "meta": {"resourceType": "User"}
}

• Rate limits: Workday does not publicly document specific numeric rate limits. Limits are enforced at the tenant level and vary by deployment. Workday may throttle or queue requests under high load.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No official rate-limit headers or Retry-After behavior documented. Workday recommends using asynchronous integration patterns (EIB, Studio) for bulk operations rather than high-frequency REST calls.

• Pagination method: offset

• Default page size: 100

• Max page size: 999

• Pagination pointer: offset / limit (REST); startIndex / count (SCIM)

• Webhooks available: No

• Webhook notes: Workday does not offer native outbound webhooks in the traditional sense. Event-driven integrations are handled through Workday Business Process Framework notifications, Workday Studio, or the Workday Extend platform.

• Alternative event strategy: Use Workday's Business Process notifications to trigger outbound calls via Workday Studio integrations or EIB (Enterprise Interface Builder). Workday Extend (formerly Workday Cloud Platform) allows building custom event-driven apps on the Workday platform. Some IdP connectors (Okta, Entra ID) poll Workday via SCIM or SOAP on a schedule.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise (custom pricing; SSO configuration is a prerequisite)

• Endpoint: https:///ccx/scim/v2//

• Supported operations: GET /Users, GET /Users/{id}, POST /Users, PUT /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, GET /Groups/{id}, POST /Groups, PUT /Groups/{id}, PATCH /Groups/{id}, GET /ServiceProviderConfig, GET /Schemas

Limitations:

• SSO must be configured before SCIM can be enabled; SCIM token is tied to the SSO integration.
• Workday primarily acts as the source of truth (outbound) for HR data; inbound SCIM is scoped to specific Workday products (e.g., Strategic Sourcing, Workday Extend apps).
• SCIM user creation does not initiate the Hire business process; it only creates a Workday user account.
• Tenant hostname and tenant name are customer-specific and must be obtained from the Workday admin.
• SCIM Groups map to Workday security groups; group membership changes may be subject to business process approval workflows.
• Attribute mapping between SCIM schema and Workday worker fields is limited compared to full SOAP/REST API capabilities.

Three integration patterns cover the majority of provisioning use cases against Workday's API.

Inbound provisioning (external system → Workday): Authenticate via Client Credentials, resolve prerequisite references (Position, Job Profile, Org, Location) via GET or SOAP Get_ calls, then invoke SOAP Hire_Employee (Staffing v43.x).

Poll the returned Event_Reference via Get_Business_Process_Parameters to confirm completion status before treating the worker as active.

If the tenant has approval steps, the hire will not be fully active until all steps clear - the API call initiates the process, it does not complete it.

Deprovisioning (termination + account disable): SOAP Terminate_Employee sets the termination effective date, but this does not immediately revoke UI access.

A separate Maintain_User_Account call with Account_Disabled=true is required to cut off login independently of the termination date.

Security group assignments added via User-Based Security Groups must also be removed explicitly - they are not always cleared automatically on termination depending on tenant configuration.

Outbound sync via SCIM (Workday → IdP → downstream apps): Configure SSO in Workday first - SCIM cannot be enabled without it.

The IdP polls GET /Users on a schedule (typically every 15–40 minutes) and translates changes to downstream targets.

The SCIM token does not auto-rotate;

rotation requires manual regeneration in Workday and a corresponding update in the IdP.

Complex HR attributes such as cost center, custom fields, and multi-job assignments are often not available via SCIM and require a supplemental SOAP or REST integration.

Provision a new employee into Workday from an external HR system

1. Authenticate: POST to /ccx/oauth2//token with client_credentials grant to obtain Bearer token.
2. Look up or create prerequisite objects: verify Position_Reference, Job_Profile_Reference, Organization_Reference, and Location_Reference exist via GET calls or SOAP Get_ operations.
3. If the person is a new applicant, create an Applicant record via SOAP Put_Applicant (Recruiting web service) or use an existing worker reference.
4. Invoke SOAP Hire_Employee (Staffing v43.x) with required Hire_Employee_Data including organization, position, start date, and personal data.
5. Poll the resulting Event_Reference via Get_Business_Process_Parameters to confirm the hire process completed (status = Successfully Completed).
6. Optionally call Maintain_User_Account (Human_Resources) to set the Workday username and assign security groups for application access.

Watch out for: If the tenant has approval steps in the Hire business process, the API call initiates but does not complete the hire. The worker record will not be fully active until all process steps are approved, which may require human action.

Deprovision a terminated employee (disable Workday access)

1. Authenticate and obtain Bearer token.
2. Invoke SOAP Terminate_Employee (Staffing) with the worker reference, termination date, and primary reason reference.
3. Separately call Maintain_User_Account with Account_Disabled=true to immediately revoke Workday UI login, independent of the termination effective date.
4. If the worker has security group assignments that should be removed, call Put_Security_Group_Assignment to remove them.
5. For downstream app deprovisioning, configure Workday outbound integrations (EIB or Studio) to push termination events to connected systems, or rely on IdP (Okta/Entra) polling Workday SCIM/SOAP for status changes.

Watch out for: Termination effective date and account disable are independent. A future-dated termination will not disable the account until that date unless Account_Disabled is set explicitly. Workday does not automatically push termination events to external systems without a configured integration.

Sync Workday workers to an external directory via SCIM (IdP-mediated)

1. In Workday, configure an SSO integration (e.g., with Okta or Entra ID) as a prerequisite.
2. Enable SCIM provisioning in the IdP connector settings; the IdP will be provided the Workday SCIM base URL (https:///ccx/scim/v2//) and a SCIM Bearer token generated in Workday.
3. Configure attribute mappings in the IdP between Workday SCIM attributes and the target directory schema.
4. The IdP polls Workday SCIM GET /Users on a schedule (typically every 15–40 minutes depending on IdP) to detect new, updated, or deactivated workers.
5. The IdP translates changes and provisions/updates/deprovisions accounts in the target application.
6. Test with a single user before enabling for all workers; validate that termination sets active=false in SCIM and triggers deprovisioning downstream.

Watch out for: Workday SCIM exposes a limited attribute set compared to the full SOAP API. Complex HR attributes (cost center, custom fields, multiple jobs) may not be available via SCIM and may require a supplemental SOAP/REST integration. Additionally, the SCIM token does not auto-rotate; rotation requires manual regeneration in Workday and update in the IdP.

The most common integration trap is treating Workday's termination API call as equivalent to access revocation. Termination effective date and account disable are independent operations - a future-dated termination leaves the account active until that date unless Account_Disabled is set explicitly via a separate Maintain_User_Account call.

Teams that automate only the termination step and skip the account disable step leave a window of active access.

A second trap is SCIM scope assumptions. Workday's SCIM endpoint is primarily designed for inbound provisioning into specific Workday products (Strategic Sourcing, Workday Extend apps). Using SCIM as the sole outbound sync mechanism to build an identity graph will miss attributes that are only accessible via the full SOAP Human_Resources web service.

For any integration requiring rich worker context - org hierarchy, position data, security group membership, custom fields - SOAP Get_Workers with selective Response_Group flags is the correct path, not SCIM.

API versioning is a third operational risk. Workday releases two major updates per year and deprecates older API versions on a rolling basis. Integrations pinned to a specific version (e.g., v43.1) must be actively tracked against Workday's release calendar or they will break silently when the version is retired.