---
title: "Workday Custom Labels, Translations & API Descriptors"
description: "How Maintain Custom Labels, Translate Business Object, and Workday REST, WQL, RaaS, and SOAP Descriptor fields resolve tenant terminology and user locales."
url: https://kiweely.com/guides/workday-custom-labels-translations-reading-tenant-terminology
---

# How Workday Stores Custom Plan Names, Reason Codes, and Translated Labels Across APIs

Workday separates UI label overrides (Maintain Custom Labels) from tenanted object translations (Translate Business Object). Across REST, WQL, RaaS, and SOAP APIs, descriptor strings resolve dynamically from the caller’s language and locale hierarchy while IDs stay invariant.

-   **Checked** against Workday on November 15
-   Applies to **Workday Translations & APIs**
-   6 min read
-   Published November 15
-   By Kiweely

Workday manages tenant terminology across **two distinct configuration layers**—delivered UI term overrides (**Maintain Custom Labels** / **Maintain Non-English Custom Labels**) and tenanted business object data translations (**Translate Business Object** / **Translations Hub**)—and resolves human-readable `descriptor` strings in REST, WQL, RaaS, and SOAP responses dynamically according to the **authenticated caller’s language and locale hierarchy**.

Integrations and custom employee screens break when developers hardcode string comparisons against `descriptor` values (such as `"Vacation"` or `"Transfer > Move to another Manager"`), or wonder why French-Canadian and Spanish workers receive US English plan names when requests run through a single US-English Integration System User instead of [user-delegated OAuth 2.0](https://kiweely.com/guides/workday-authorization-code-grant-user-delegated-oauth-setup).

## Layer 1 vs. Layer 2: Custom UI Labels vs. Tenanted Object Translations

Before reading labels over an API, distinguish where a term actually lives inside Workday configuration:

| Dimension | Delivered UI Label Overrides | Tenanted Business Object Translations | Custom Report & RaaS Labels |
| --- | --- | --- | --- |
|  **Primary Admin Tasks** | `Maintain Custom Labels` (English) & `Maintain Non-English Custom Labels` + `Maintain Non-English Custom Label Overrides` | `Edit Tenant Setup - Global`, `Translations Hub`, `Translate Business Object`, or globe *In-Context Translation* icon | Related Actions on report: `Translation > Translate Instance` & `Custom Report > Translate` |
|  **Required Security Domain** | `Custom Label Management` and `Custom Label Management for Non-English` (*System* functional area) | `Data Translation` and `Data Translation: In-Context Translation` (*System* functional area) | `Data Translation` + `Custom Report Administration` (*System* functional area) |
|  **What It Renames** | Delivered platform nouns (singular, plural, possessive) within a **Term Context**—e.g., *Contingent Worker* -> *Contractor*, or Spanish *registro de entrada* -> *registro de ingreso* | Customer-created instances: Absence Plan names, Benefit Plan names, Job Change / Termination Reasons, Organizations, Questionnaires, Text Blocks | Report Name, Column Heading Overrides, Prompt Labels, Sort Group Overrides, Instructions |
|  **Effect on REST / SOAP Schema Keys** |  **None.** Workday does not apply custom labels to security or integration schema property names |  **Populates `descriptor` (REST/WQL) and `wd:Descriptor` (SOAP)** in the caller’s resolved display language | Translates RaaS UI headers/prompts; XML element tags stay fixed to the report’s XML alias |

### Critical Nuances on `Maintain Custom Labels` and Non-English Overrides

1.  **Integrations and Existing Report Titles Stay Unchanged:** Workday explicitly does not replace terms inside security administration or integration definitions, and creating a custom label for *Contingent Workers* does not automatically rename an existing custom report titled *Custom Report for Contingent Workers*.
2.  **Two-Task Activation for Non-English Custom Labels:** When overriding a Workday-delivered term in another language (for example, `Spanish (Neutral)` under the `Time Core` context), entering an **Override Value** and clearing **Disabled** on **Maintain Non-English Custom Labels** triggers a background preparation job. Once that job finishes, you must open **Maintain Non-English Custom Label Overrides** and select **Use Proposed Value** (or **Use All Proposed Values**) for the override to appear on self-service tasks (and via the `Get_Non-English_Custom_Label_Overrides` SOAP operation).
3.  **Search Index Timing:** Newly saved custom labels appear in Workday search results only after the Friday server restart index rebuild (or an explicit **Rebuild Search Index** run, which Workday recommends avoiding during peak hours).

## How Workday Determines Which Language an API Call Receives

Whenever a caller invokes a Workday REST endpoint, WQL query, RaaS report, or SOAP operation, Workday evaluates a strict **six-level fallback chain** for the authenticated *Run As User* to choose which language string populates `descriptor` fields:

1.  **User’s Selected Preferred Display Language** (set via **Change Preferences** or `Edit Workday Account`)
2.  **User’s Selected Preferred Locale**
3.  **Selected Language of the Worker’s Primary Business Site Location**
4.  **Selected Locale of the Worker’s Primary Business Site Location**
5.  **Default Language of the Tenant**
6.  **Default Locale of the Tenant** (typically `English (United States)`)

Two additional tenant switches govern what happens when a specific plan name or reason code has **not** been translated into the worker’s target language yet:

-   **Base Language Fallback & `Allow Mixed-Language Transactions`:** Every Workday object stores a **Base Language** (viewable via the **Base Languages** report). On self-service views, untranslated items may be suppressed unless **Allow Mixed-Language Transactions** is checked on **Edit Workday Account** / **Manage Workday Accounts** (or no translation exists for a text block, in which case Workday falls back to the base language).
-   **Base Value Edits (`Hide Translations after Base Value Change`):** On **Edit Tenant Setup - Global**, if **Hide Translations after Base Value Change** is checked and an admin edits the English base name of a Time Off Plan or Question, Workday clears the active translation (`Needs Translation` status on **Translate Business Object**). Note also that for **Effective-Dated Snapshot** objects (such as `Organization`), creating a new effective-dated snapshot copies existing translations forward, whereas editing the base value on an existing translated snapshot deletes its translations.

> \[!IMPORTANT\] Why User-Delegated OAuth Fixes Multilingual Self-Service Automatically If your external portal or assistant queries Workday through a shared Integration System User ([RaaS user-delegated OAuth vs. ISU Basic Auth](https://kiweely.com/guides/workday-raas-user-delegated-oauth-vs-isu-basic-auth)), every worker receives `descriptor` strings in the *ISU’s* language (almost always US English). When each worker authenticates via **Register API Client** (Authorization Code Grant with PKCE), Workday evaluates *that worker’s* `Preferred Display Language` and primary work location automatically—returning French, German, Spanish, or Japanese plan and reason names with zero external translation tables to maintain.

## Reading Plan Names, Reason Codes, and Descriptors Across REST, WQL, and SOAP

Across every Workday API surface, Workday pairs an **immutable identifier** (`id` / `WID` or `Reference_ID`) with a **localized human label** (`descriptor` / `@wd:Descriptor`).

### 1\. Workday REST APIs (`absenceManagement`, `common`, `staffing`)

Every object reference in a Workday REST response contains `id` (the 32-character Workday ID) and `descriptor` (localized for the current OAuth caller). Compare what `GET /common/v1/jobChangeReasons` or `GET /absenceManagement/v5/workers/me/eligibleAbsenceTypes` returns for two workers in the same tenant:

json

```
// Worker A (Preferred Display Language: English)
{
  "data": [
    {
      "id": "a18c426056a1100018b52d4e99c10042",
      "descriptor": "Annual Paid Vacation (Hours)"
    },
    {
      "id": "b7187dceedb34c8db3a8e15adf02a620",
      "descriptor": "Transfer > Transfer > Move to another Manager"
    }
  ]
}
```

json

```
// Worker B (Preferred Display Language: French - Canada, translated via Translate Business Object)
{
  "data": [
    {
      "id": "a18c426056a1100018b52d4e99c10042",
      "descriptor": "Vacances annuelles payées (Heures)"
    },
    {
      "id": "b7187dceedb34c8db3a8e15adf02a620",
      "descriptor": "Mutation > Mutation > Changement de gestionnaire"
    }
  ]
}
```

Notice that `id` (`a18c426056a1100018b52d4e99c10042`) is **identical** across both languages, including hierarchical `Category > Subcategory > Reason` strings configured on **Maintain Event Categories and Reasons**.

### 2\. Workday Query Language (WQL)

When querying WQL (`/ccx/api/wql/v1/{tenant}/data`), selecting any business object reference field returns `{ "id": "...", "descriptor": "..." }` localized to the authenticated caller:

Works

```
SELECT timeOffPlan,
       timeOffType,
       unitOfTime
FROM eligibleTimeOffPlansForWorker
```

**Rule for `WHERE` Clauses:** Never write `WHERE timeOffPlan = 'Annual Paid Vacation'` in WQL or filter arrays in TypeScript by `item.descriptor.includes("Vacation")`. Filter by immutable `WID` or `Reference_ID` so renaming a plan on `Edit Time Off Plan` or switching user locales never breaks query predicates.

### 3\. Workday Web Services (SOAP)

In SOAP responses (for example, `Get_Time_Off_Plans` in `Absence_Management` or `Get_Workers` in `Human_Resources`; see [calling SOAP with user-delegated Bearer credentials](https://kiweely.com/guides/workday-soap-api-bearer-token-user-delegated-oauth)), Workday includes the `wd:Descriptor` XML attribute on `*_Reference` elements when descriptors are not suppressed in the request header:

xml

```
<wd:Time_Off_Plan_Reference wd:Descriptor="Vacances annuelles payées (Heures)">
  <wd:ID wd:type="WID">a18c426056a1100018b52d4e99c10042</wd:ID>
  <wd:ID wd:type="Absence_Plan_ID">PTO_ANNUAL_HRS</wd:ID>
</wd:Time_Off_Plan_Reference>
```

Keep `<wd:Include_Reference_Descriptors_In_Response>true</wd:Include_Reference_Descriptors_In_Response>` inside `bsvc:Workday_Common_Header` whenever your application renders reference labels directly from SOAP responses.

## Audit Checklist for Missing or Stale Translated Labels

1.  **Verify Language Enablement:** Open **Edit Tenant Setup - Global** and confirm the target language has **Enabled** checked in the **Available Languages** grid.
2.  **Audit Base Value Resets:** Run the **Translation Base Value Change Audit** report (or **View Translatable Values for Language** / **Search Translatable Text** from **Translations Hub**) to catch plan names or reasons stuck in `Needs Translation` or `Needs Review` after an English copy edit.
3.  **Check Location vs. User Preference:** Remember that **localized country-specific fields** (such as `Maintain Local Termination Reasons` or custom country names on `Maintain Workday Delivered Country Names`) filter availability by the worker’s **primary work location**, whereas the **text translation** of those values follows the worker’s **Preferred Display Language**.
4.  **Test Under Real Worker Sessions:** Sign in as a test worker whose **Preferred Display Language** is set to Spanish or French via user-delegated OAuth—or build multilingual employee screens in **[Kiweely Leaf](https://kiweely.com/leaf)** (coming next), which reads each signed-in worker’s live tenant terminology and translated descriptors automatically without duplicating translation dictionaries outside Workday.

## Frequently asked questions

### Does Maintain Custom Labels change SOAP XML element names or REST JSON property keys?

No. Workday explicitly excludes security and integration schemas from Maintain Custom Labels overrides so API contracts remain stable. Overriding Contingent Worker to Contractor changes self-service UI labels, not JSON keys or WSDL element names.

### Why did editing the English name of an Absence Plan or Question clear its French and Spanish translations?

When Hide Translations after Base Value Change is checked on Edit Tenant Setup - Global, editing the base language value of a tenanted translatable attribute clears its active display status and marks existing translations as Needs Translation until reviewed on Translate Business Object.

### Why does a RaaS report or REST API return English plan names when called through an Integration System User?

Workday resolves object descriptors and custom report labels using the authenticated Run As User's Preferred Display Language and Locale hierarchy. Because an Integration System User typically defaults to US English, calling via an ISU strips individual worker language preferences—whereas user-delegated OAuth returns descriptors in each signed-in worker's language.

### Should external applications filter business logic on the descriptor string or on the Workday ID / Reference ID?

Always key programmatic logic on the 32-character Workday ID (id) or Reference ID, and treat descriptor / @Descriptor strictly as a localized human display label. Descriptor strings change whenever a user switches display languages or an admin renames a plan.

## Sources checked

-   [Workday Admin Guide — Create Custom Labels](https://doc.workday.com/admin-guide/en-us/manage-workday/tenant-configuration/custom-objects-and-labels/dan1370796580624.html)
-   [Workday Admin Guide — Concept: Translations](https://doc.workday.com/admin-guide/en-us/manage-workday/tenant-configuration/globalization/languages-and-translations/qye1503329511602.html)
-   [Workday Admin Guide — Steps: Manage Translations](https://doc.workday.com/admin-guide/en-us/manage-workday/tenant-configuration/globalization/languages-and-translations/dan1370797879452.html)
-   [Workday Admin Guide — Concept: Country-Specific Information, Locales, and Languages](https://doc.workday.com/admin-guide/en-us/manage-workday/tenant-configuration/globalization/global-tenant-setup/vec1511195045421.html)
-   [Workday Admin Guide — Steps: Set Up Non-English Custom Labels for Time Tracking](https://doc.workday.com/admin-guide/en-us/human-capital-management/time-tracking/time-tracking-basics/set-up-non-english-custom-labels-for-time-tracking.html)

## Related guides

[All guides](https://kiweely.com/guides)

-   [### How Workday Calculates Projected Time-Off Balances as of a Future Date Workday computes a projected time-off balance dynamically from the worker’s last stored balance date through the target future date by adding scheduled period accruals, applying carryover and upper accrual caps in sequence, and subtracting both approved and pending time-off requests.](https://kiweely.com/guides/workday-accrued-time-off-balance-as-of-future-date)
-   [### Authenticating Workday SOAP Web Services with a User-Delegated OAuth Bearer Token Send Workday SOAP requests with an HTTP Authorization Bearer header issued from a user-delegated OAuth 2.0 Authorization Code grant and leave the SOAP XML Header element empty. Workday evaluates both the API Client Functional Area scope and the signed-in worker’s Integration Permissions.](https://kiweely.com/guides/workday-soap-api-bearer-token-user-delegated-oauth)
-   [### Calling Workday RaaS Reports with User-Delegated OAuth Instead of an ISU Replace shared Integration System User Basic authentication on Workday Reports as a Service (RaaS) with user-delegated OAuth 2.0 Bearer credentials so custom reports automatically enforce each signed-in worker’s row-level and field-level security.](https://kiweely.com/guides/workday-raas-user-delegated-oauth-vs-isu-basic-auth)
-   [### How to Configure User-Delegated OAuth 2.0 Authorization Code Grant in Workday Register a user-delegated Workday OAuth 2.0 client using Register API Client with Authorization Code Grant, PKCE (S256), and Bearer credentials so external applications authenticate employees through SSO and run under their own Workday permissions.](https://kiweely.com/guides/workday-authorization-code-grant-user-delegated-oauth-setup)

### More guides on Tenants and developer accounts

[All 25 guides](https://kiweely.com/guides#tenants)

-   [Why Workday W-2 Box 1, 3, or 5 Wages Don’t Match Payroll Summary (and How to Fix Them)](https://kiweely.com/guides/workday-w2-box-mismatch-adjust-tax-balances)
-   [How to Customize the Workday Home Page, Daily Brief, and Global Navigation Sidebar](https://kiweely.com/guides/workday-configurable-home-page-daily-brief-setup)
-   [Workday Payroll Parallel Testing and Retro Calculation Audits in Sandbox](https://kiweely.com/guides/workday-payroll-parallel-testing-retro-audit)
-   [Workday Test Data: How to Build Realistic Data in a Sandbox or Implementation Tenant](https://kiweely.com/guides/workday-test-data-sandbox)
-   [How do I plan end-to-end and regression testing in Workday, and what does a test scenario cover?](https://kiweely.com/guides/workday-end-to-end-testing)
-   [How to get a Workday developer account and a free development tenant](https://kiweely.com/guides/workday-open-developer-program-getting-started)
-   [Multi-Persona Testing in Workday: Verifying the Proxy Chain in Sandbox](https://kiweely.com/guides/workday-multi-persona-proxy-testing)
-   [Preparing for Workday 2027 R1 With a Small Team: The Timeline, What to Test in Sandbox Preview, and Who Does What](https://kiweely.com/guides/workday-release-preparation-audit-checklist)

### From the blog on Tenants and developer accounts

[All posts](https://kiweely.com/blog)

-   [Why Workday Community answers fail you—and how to verify in the tenant](https://kiweely.com/blog/workday-community-answers-verify-in-tenant-method)
-   [Check a Workday Community answer against your tenant](https://kiweely.com/blog/verify-workday-community-answers-with-tenant)
-   [Prototype in an Implementation tenant, then keep what you meant to keep](https://kiweely.com/blog/ai-workday-prototype-tenant-builds)

## Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

[Start for free](https://kiweely.com/download) [See how it works](https://kiweely.com/vine/how-it-works)

## Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.
