Workday

Sync data from your warehouse to Workday HCM. Update worker records and tenant-defined custom objects using the Workday REST API.

Prerequisites

• A Workday tenant with REST API access enabled
• An Integration System User (ISU) with appropriate domain permissions
• A registered API Client in Workday (for OAuth authentication)
• Your tenant REST API base URL (e.g., https://wd5-impl-services1.workday.com)
• Your tenant ID (e.g., mycompany or mycompany_impl)

Permissions

The Integration System User must have the following domain permissions:

• Worker Data: Public Worker Reports — for reading and writing worker records
• Worker Data: Workers — for creating and updating worker profiles
• Custom Object: {Object Name} — for syncing to custom objects (grant per object)
• Integration: Build — required for API client registration and token generation
• Assign the ISU to an Integration System Security Group with the above domain permissions

Authentication

Zeotap authenticates to Workday using a registered API Client and a non-expiring refresh token generated for an Integration System User (ISU).

Client Credentials

1. In your Workday tenant, navigate to Register API Client for Integrations (search in the Workday search bar)
2. Register a new API Client and note the Client ID and Client Secret
3. Generate a Refresh Token for your Integration System User:
   • Navigate to the ISU’s profile in Workday
   • Go to Security and select Generate Non-Expiring Refresh Token
   • Select the API Client you registered and generate the token
4. In Zeotap, navigate to Destinations and click Add Destination
5. Select Workday and choose Client Credentials
6. Enter your Client ID, Client Secret, and Refresh Token
7. These credentials are stored securely and never exposed in the UI after saving

Configuration

Target Settings

Supported Object Types

Supported Operations

Sync Modes

Audience Sync Modes

Workday does not have a native list or audience membership concept, so audience sync modes are not supported.

Features

• Field Mapping: Yes — map your warehouse columns to any Workday object field
• Schema Introspection: No — configure field mappings manually based on your target object type

Required Mapping Fields

Default Destination Fields

These common Workday fields appear as suggestions in the field mapping editor:

How It Works

1. Record mapping: Zeotap maps each warehouse row to a Workday record using your configured field mappings
2. API calls: Each record is sent individually via the Workday REST API:
   • Workers Update: PATCH /ccx/api/v1/\{tenant\}/workers/\{id\} (partial update — only mapped fields are modified)
   • Workers Insert: POST /ccx/api/v1/\{tenant\}/workers (limited — only supported for worker types the REST API exposes; hires that require business process workflows must use SOAP)
   • Custom Objects Upsert: PUT /ccx/api/v1/\{tenant\}/customObjects/\{name\}/\{id\} when a primary key is available, otherwise POST /ccx/api/v1/\{tenant\}/customObjects/\{name\}
3. Token refresh: Access tokens are refreshed before expiry using the registered API client and refresh token
4. Retry logic: Transient failures (HTTP 429 rate limits, 5xx server errors) are retried with exponential backoff (up to 3 retries per request)
5. Progress tracking: Rows are processed sequentially with progress logged every 50 records

Batch Size

The Workday REST API processes one record per request. Zeotap handles batching internally, sending records sequentially with automatic retry and error tracking for each individual record.

Rate Limits

Workday enforces strict rate limits per tenant:

• Default: Approximately 10 API calls per second per tenant
• Rate limit response: HTTP 429 (Too Many Requests)
• Zeotap behavior: Automatically retries with exponential backoff when rate limited

If you experience frequent rate limiting, consider:

• Reducing sync frequency to allow more time between runs
• Syncing smaller datasets by filtering your source model
• Scheduling syncs during off-peak hours (evenings or weekends relative to your tenant region)
• Contacting Workday support to review your tenant’s API rate limit configuration

Best Practices

• Use a dedicated Integration System User rather than a personal admin account for all API integrations
• Map the Worker_ID field as the primary key for upsert and update operations to ensure correct record matching
• Test with a small batch in your implementation or sandbox tenant before running a full sync in production
• Use upsert mode when you want to create new records and update existing ones in a single sync
• Grant minimal permissions to the ISU — only the domain permissions required for your target object types
• Monitor sync results in the Zeotap sync run history to catch mapping errors and permission issues early

Troubleshooting

Authentication failed: invalid client credentials

Verify that the Client ID and Client Secret are correct and that the API Client registration is active in Workday. Ensure the API Client was registered using Register API Client for Integrations (not the general API Client registration).

HTTP 403: insufficient permissions

The Integration System User lacks the required domain permissions for the target object. Add the appropriate domain security policies to the ISU’s Integration System Security Group and activate the pending security policy changes in Workday.

Refresh token expired or revoked

Workday refresh tokens are typically non-expiring, but they can be revoked by an administrator. Generate a new refresh token for the ISU and update the credentials in Zeotap.

Worker not found (404) during update

The Worker ID provided does not match any existing worker in the tenant. Verify that the primary key mapping is correct and that the worker record exists in Workday. Use Upsert mode if some rows may not have existing records.

Tenant URL validation failed

The tenant URL must match the pattern https://*.workday.com. Do not include trailing slashes, paths, or query parameters. Examples: https://wd5-impl-services1.workday.com, https://wd5-services1.workday.com.

Rate limited (HTTP 429)

Your sync is exceeding the tenant’s API rate limit (~10 requests/second). Zeotap automatically retries with backoff, but persistent rate limiting may require reducing the sync frequency or scheduling during off-peak hours.

Custom object name not found

Verify that the custom object API name matches exactly what is configured in your Workday tenant. Custom object names are case-sensitive. Navigate to Custom Objects in your Workday tenant to confirm the correct API name.

Connection timeout

Large syncs may experience timeouts if the Workday tenant is under heavy load or if network latency is high. Zeotap uses a 120-second timeout per request. If timeouts persist, try syncing during off-peak hours or reducing the dataset size.