Workday RaaS: How to Authenticate and Extract Custom Report Data

Key takeaways

• Workday RaaS turns a custom report into a callable web service, but it stays read-only and pull-only, with no write or push path back into Workday.
• Workday offers two authentication routes to a RaaS report: Basic credentials for an Integration System User (ISU), or an OAuth token issued through an API Client for Integrations.
• The report URL follows a fixed pattern under /ccx/service/customreport2/, and a prompt name's !WID suffix is sent percent-encoded as %21WID.
• Workday documents a 6-hour timeout for RaaS SOAP and REST requests from a tenanted host, and 5 minutes for RaaS calls through its WCP Gateway (api.workday.com).
• A RaaS connection has six configuration points to check when a call fails or comes back empty, from an unshared report to a refresh token generated under the wrong account.
• Custom reports can be marked temporary and are deleted after seven days by default, which can explain a connection that worked last week and doesn't now.

Last verified 2026-09-30.

Workday's documentation refers to a custom report exposed this way as Reports as a Service (also written Report-as-a-Service, or RaaS). It sounds like a documented endpoint set. It's a report someone built in Workday's report writer, turned into a URL by a checkbox, and handed to you as "the API."

The report renders fine when an admin opens it in a browser, then returns nothing, or a permissions error, the moment your code calls the same URL with different credentials, and nothing in the response says which setting is missing.

RaaS exists for a real reason: Workday documents it as read-only, retrieving data that may not be available through its REST APIs at all. This page follows the whole chain, report, identity, URL, call, and the six places to check when it breaks, for the engineer who has to spec this out for a customer's Workday admin rather than build it inside Workday itself.

Where RaaS fits against SOAP and REST

Workday data is reachable through three routes, and RaaS is usually the one a customer offers, not necessarily the one that fits best. Workday's own documentation lists SOAP Web Services, REST, and RaaS as the three primary routes in. SOAP, Workday Web Services, handles core business operations, secured to a domain or business-process policy; REST exposes narrower, versioned endpoints through the API Gateway, generally the simpler route where it's available.

If a RaaS report is what you were handed, you're working within its limits, not choosing among these three. Our beginner's guide to Workday integrations covers the bigger picture, and pulling employees from the Workday API in Python walks the SOAP route when that's what's on offer instead.

Building the report so it can be called

Before any auth or URL work, the report has to be built to the requirements in Workday's Concept: Reports as a Service documentation, usually in conversation with the customer's Workday admin rather than something you configure yourself.

1. Use an Advanced or Search report: those are the report types Workday's documentation says can be enabled as a web service.
2. Build it as a custom copy, not the standard report, so Workday's own updates to the standard version don't silently change what your integration receives.
3. Set the data source, which fixes the report's primary business object, since a report has exactly one; filters on that source, not the web-service setting, decide which rows return.
4. Enable Web Service from the report's related actions: the step that makes it reachable by URL at all.
5. Check the report owner's username: Workday says it must not contain a backslash, or GET requests to the report fail.

Authenticating: Workday credentials or OAuth

Once the report exists, Workday needs to know who's asking. Its Orchestrate documentation describes two authentication types available for a RaaS request: OAuth, or what Workday calls Workday credentials. The choice is between two identity types Workday already provisions internally.

Both credentials travel in the same place, the Authorization header, under a named scheme, a framework HTTP itself defines (RFC 9110 §11). Basic and Bearer are two schemes inside that framework, which is why they look alike on the wire despite differing completely behind it.

Provisioning either route follows the same order, using Workday's own task names:

1. Create an Integration System User: the identity everything else attaches to, whichever route you end up on.
2. Share the report: grant that ISU access to it; an unshared report is the first thing to check when calls return no data.
3. Register an API Client for Integrations (OAuth only): a client ID and a secret Workday shows exactly once.
4. Scope the client: include the functional area behind Report Execution in that tenant, since it isn't included by default.
5. Generate a refresh token: under Manage Refresh Tokens for Integrations, with the ISU explicitly selected as the account it's bound to.

Choosing an output format

RaaS can hand back a report in six shapes, and the choice decides how much parsing you do afterward. Workday's Concept: Reports as a Service documentation lists JSON, CSV, Simple XML, Workday XML, GData, and RSS as the available formats, and the CSV quirks below come from that same page.

Workday XML, reached from the report's related actions rather than the format parameter, hands back XML alongside its XSD and WSDL, useful if the report ends up consumed over SOAP instead. JSON's UTF-8 guarantee and CSV's quoting rules, quotes around any field containing a comma or line break, both come from the format specifications themselves rather than from Workday (RFC 8259; RFC 4180).

Building the URL and making the call

Every RaaS report answers to the same URL, once the last two sections' pieces are in hand:

https://{host}/ccx/service/customreport2/{tenant}/{username}/{report_name}?{prompts}&format={format}

• {host} / {tenant}: the tenant's Workday web-services host and identifier.
• {username}: the report owner's username, without a backslash.
• {report_name}: the report name, with spaces replaced by underscores.
• {prompts}: required prompt values, URL-encoded.
• {format}: one of the five values above.

Get the exact URL, and for SOAP consumption the WSDL, from the report's related actions, View URLs, or Web Service, View WSDL, as Workday's Concept: Accessing RaaS Output documentation describes. A required prompt without a value fails the call. A single-instance prompt looks like Organization%21WID=<id>: the ! in the prompt name's !WID suffix is sent percent-encoded as %21, since ! is a reserved sub-delimiter under RFC 3986. Multiple values for one prompt are then joined with a raw !, as in Workday's own example, Location%21WID=<wid_1>!<wid_2>.

OAuth is a two-step call: exchange the refresh token for an access token, then use it on the report.

# 1. Exchange the refresh token for an access token
curl -X POST "https://{host}/ccx/oauth2/{tenant}/token" \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=refresh_token" \
  -d "refresh_token={refresh_token}"

# 2. Call the report with the access token
curl "https://{host}/ccx/service/customreport2/{tenant}/{username}/{report_name}?Organization%21WID={org_wid}&format=json" \
  -H "Authorization: Bearer {access_token}"

Six values cover what any OAuth caller needs:

For a pull that only needs what changed, build it into the report itself rather than looking for a separate incremental endpoint. Some Workday integrations support extracting only data changed since the last run, which for RaaS means adding a date-range prompt in the report writer and passing its value in the query string like any other prompt.

Limits, and when WQL fits better

Workday's Reference: WQL and RaaS Comparisons documents a 6-hour timeout for RaaS SOAP and REST requests from a tenanted host, and a 5-minute timeout for RaaS calls made through the Workday Cloud Platform (WCP) Gateway at api.workday.com. If you've seen 30 minutes quoted for RaaS, that is the documented tenanted-host timeout for WQL, Workday's other reporting interface.

RaaS hands back the whole report Workday built for you, simple until the report is wide or the pull is frequent; WQL trades that simplicity for pagination and field control instead. Reach for WQL when a report needs GROUP BY, has to run against several tenants unchanged, or returns more than a single pull can use comfortably; otherwise RaaS's full-output behavior is usually the simpler path.

Running RaaS extraction in production

None of the six checks above is a one-time cost. Refresh tokens need ongoing care as tenant configurations change, reports get rebuilt as temporary by accident, and every new customer starts the provisioning chain above from step one, on their own tenant. A team that built the connection correctly still owns that upkeep across every tenant it connects to.

Bindbee's Workday RaaS connector uses the OAuth route this page just walked through: an API Client for Integrations and a refresh token bound to the ISU, with the report shared to that ISU. There's no screen scraping, so nothing about the identity chain above changes when a provider runs it instead of your own code.

What changes is who's watching it:

• Sync runs on a 24-hour default, adjustable per connection.
• Webhooks fire when a sync starts, finishes or fails, and when it finds records created or updated. A failed pull raises connector_sync_error, and a connector whose credentials stop working shows RELINK_NEEDED.
• Custom Fields extend Bindbee's unified models with other values from the raw upstream payload, mapped by JMESPath.

The same API reaches 110+ HRIS, payroll, ATS, and benefits systems, including Workday's full API through a separate connector for when a customer opens that instead of a single report. Bindbee is SOC 2 Type II compliant, ISO 27001 certified, HIPAA compliant and GDPR compliant, and encrypts data in transit (TLS 1.2+) and at rest (AES-256).

If a customer has handed you a RaaS report and six checks per tenant is more than you want to own, Bindbee's Workday RaaS connector is built to run this chain for you.

Frequently asked questions

Can you create a Workday RaaS report through the API?

No, not through RaaS itself. Reports are built in Workday's report writer, in the UI, and RaaS exposes a report that already exists rather than defining a new one, per Workday's security documentation. This reflects Workday's documentation as reviewed on 2026-09-30, and isn't a claim that programmatic report creation is impossible everywhere in Workday, only that RaaS doesn't do it.

Does Workday RaaS support webhooks?

No. Workday's RaaS documentation describes retrieval by request, a URL or WSDL call, with no subscription or change-notification mechanism. Treat RaaS as pull-only: poll on a schedule and use a date prompt on the report itself to pull only what changed, the pattern covered in the URL-building section above.

What is the Workday RaaS URL format?

Reports sit under /ccx/service/customreport2/: https://{host}/ccx/service/customreport2/{tenant}/{username}/{report_name}?{prompts}&format={format}. A prompt name's !WID suffix is sent percent-encoded as %21WID.

How long can a Workday RaaS request run?

Workday documents a 6-hour timeout for RaaS SOAP and REST requests from a tenanted host, and 5 minutes for RaaS calls through the WCP Gateway at api.workday.com.

Why did a Workday RaaS connection that worked last week stop?

One common cause: custom reports can be marked temporary, and temporary reports are deleted after seven days by default. Check that the report still exists before you debug credentials.