Workday has three APIs. Workday Web Services is a versioned SOAP API that covers every functional area, and its Recruiting service is the one that returns candidates, job applications and their resume files. The REST API returns JSON with OAuth 2.0, but Recruiting v4 only exposes prospects, job postings, interviews and offers. Reports-as-a-Service (RaaS) turns a custom report into a URL that returns JSON, CSV or XML. All three run against your own tenant, with credentials your Workday security administrator sets up.
Key facts
| SOAP endpoint | |
| Recruiting REST | Recruiting v4: prospects, job postings, interviews, offers. No candidates, job applications or requisitions |
| Auth | SOAP: WS-Security username token of an integration system user, or OAuth 2.0. REST: OAuth 2.0 with an API client registered in the tenant |
| Versions | Two releases a year, each with new web service versions; v47.1 is 2026R2. You pin one in the URL |
| Pagination | SOAP: Page and Count (1 to 999, default 100)
with a fixed As_Of_Entry_DateTime. REST:
limit (up to 100) and offset |
| Throttling | Under load, 429 on REST and RaaS, 500 on
SOAP; back off exponentially. RaaS has daily and hourly caps |
| Resume files | Base64 in Resume_Attachment_Data of
Get_Candidates; attachments up to 30 MB |
| Docs | Workday Web Services directory, REST API directory and Workday developer site, checked November 19, 2026 |
SOAP, REST or RaaS?
| API | Best for | Watch out for |
|---|---|---|
| Web Services (SOAP) | Candidates, job applications, resume files, requisitions, moving a candidate, adding attachments | XML envelopes, one version per URL |
| REST (Recruiting v4) | JSON reads of prospects and their resumes, job postings, interviews and offers | No candidates or job applications |
| RaaS | Bulk reads shaped by a custom report, as JSON, CSV or XML | Read-only, with daily and hourly request caps |
In practice, an integration that screens applicants reads and writes through the SOAP Recruiting service, becuase it is the only one that returns applications with their resume and takes attachments back. Use REST for prospects and job postings, and RaaS when a recruiting analyst already maintains the report you need.
1. Set up an integration system user
- Your Workday security administrator creates an integration system user (ISU), an account meant only for web service integrations, and puts it in an integration system security group.
- The group gets the recruiting domains your service needs, for example candidate data to read applications and Candidate Data: Attachments to add files.
- For OAuth, the administrator runs Register API Client for Integrations, then generates a refresh token for the ISU with Manage Refresh Tokens for Integrations, wich your service exchanges for short-lived access tokens.
Work in an implementaton or sandbox tenant first: its host and tenant name differ from production, and both go in the endpoint URL.
2. Read applications with Get_Candidates
Every SOAP call is an XML envelope posted to the service URL, here with the ISU credentials in a WS-Security header. Validation, security and throttling errors come back as a SOAP fault, so check for one before reading the body:
import base64
import os
import xml.etree.ElementTree as ET
from datetime import datetime, timedelta, timezone
from xml.sax.saxutils import escape
import requests
WD_VERSION = "v47.1"
WORKDAY = (
f"https://{os.environ['WD_HOST']}/ccx/service/"
f"{os.environ['WD_TENANT']}/Recruiting/{WD_VERSION}"
)
NS = {"wd": "urn:com.workday/bsvc"}
SOAP_FAULT = "{http://schemas.xmlsoap.org/soap/envelope/}Fault"
ENVELOPE = """<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wd="urn:com.workday/bsvc">
<env:Header><wsse:Security><wsse:UsernameToken>
<wsse:Username>{user}</wsse:Username>
<wsse:Password>{password}</wsse:Password>
</wsse:UsernameToken></wsse:Security></env:Header>
<env:Body>{body}</env:Body>
</env:Envelope>"""
def workday(body: str) -> ET.Element:
"""POST one Recruiting request, signed as the integration system user."""
envelope = ENVELOPE.format(
user=escape(os.environ["WD_ISU_USER"]),
password=escape(os.environ["WD_ISU_PASSWORD"]),
body=body,
)
response = requests.post(
WORKDAY,
data=envelope.encode("utf-8"),
headers={"Content-Type": "text/xml; charset=utf-8"},
timeout=120,
)
root = ET.fromstring(response.content)
fault = root.find(f".//{SOAP_FAULT}")
if fault is not None: # validation, security and throttling errors are faults
raise RuntimeError(fault.findtext("faultstring"))
response.raise_for_status()
return rootGet_Candidates filters on Job_Requisition_Reference,
Applied_From, Recruiting_Stage_Reference and a few
more. Each job application carries its resume as base64 in
Resume_Attachment_Data, and attachments come back by default: set
Exclude_All_Attachments when you only need the data.
One gotcha with paging: Workday asks for As_Of_Entry_DateTime
whenever you set Page, so every page comes from the same moment.
Fix it once per run, then read Total_Pages from
Response_Results:
def new_resumes(requisition_id: str, since: datetime):
"""Yield (job application ID, file name, bytes) for each resume since a date."""
entry_moment = datetime.now(timezone.utc).isoformat() # same results on every page
page, total_pages = 1, 1
while page <= total_pages:
root = workday(f"""<wd:Get_Candidates_Request wd:version="{WD_VERSION}">
<wd:Request_Criteria>
<wd:Job_Requisition_Reference>
<wd:ID wd:type="Job_Requisition_ID">{escape(requisition_id)}</wd:ID>
</wd:Job_Requisition_Reference>
<wd:Applied_From>{since.isoformat()}</wd:Applied_From>
</wd:Request_Criteria>
<wd:Response_Filter>
<wd:As_Of_Entry_DateTime>{entry_moment}</wd:As_Of_Entry_DateTime>
<wd:Page>{page}</wd:Page>
<wd:Count>100</wd:Count>
</wd:Response_Filter>
</wd:Get_Candidates_Request>""")
total_pages = int(float(root.findtext(".//wd:Total_Pages", "0", NS)))
for application in root.iterfind(".//wd:Job_Application_Data", NS):
application_id = application.findtext(
"wd:Job_Application_Reference/wd:ID[@wd:type='Job_Application_ID']",
namespaces=NS,
)
for resume in application.iterfind("wd:Resume_Attachment_Data", NS):
yield (
application_id,
resume.findtext("wd:Filename", "resume", NS),
base64.b64decode(resume.findtext("wd:File_Content", "", NS)),
)
page += 1
# Resumes received on requisition R-00123 in the last 24 hours
since = datetime.now(timezone.utc) - timedelta(days=1)
for application_id, file_name, content in new_resumes("R-00123", since):
print(application_id, file_name, len(content), "bytes")Workday keeps a paged result for two hours between pages. A loop that parses each resume before asking for the next page can run past that on a busy requisition, so page through first and queue the files.
3. Parse the resumes with the Resume Parser
Workday's own resume parsing fills a candidate's profile for the
recruiter to review, but it leaves the Languages and Skills sections empty.
When you need those, or the same schema across several ATSs, send each file to HireLayer Resume Parser with one POST /api/v4/resumes/parse. It reads resumes in 70
languages, scans included.
Pass the Workday job application ID as application_id: it comes
back at the top of the response, so the parsed resume stays linked to its
application.
HIRELAYER_PARSER = "https://hirelayer.co/api/v4/resumes/parse"
def parse_resume(file_name: str, content: bytes, application_id: str):
"""Send one resume file to HireLayer Resume Parser and return its JSON."""
response = requests.post(
HIRELAYER_PARSER,
headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]},
files={"file": (file_name, content)},
data={"application_id": application_id},
timeout=150, # a parse takes about 35 s, and the API stops at 145 s
)
if response.status_code == 422:
return None # resume_unreadable: empty, damaged or not a resume, no credit used
response.raise_for_status()
return response.json()["resume"]
for application_id, file_name, content in new_resumes("R-00123", since):
parsed = parse_resume(file_name, content, f"workday-{application_id}")
if parsed is None:
continue
print(
application_id,
parsed["info_candidate"]["job_title"],
[skill["skill_title"] for skill in parsed["skills"]][:5],
[(lang["language"], lang["level"]) for lang in parsed["languages"]],
)A trimmed response:
{
"application_id": "workday-JOB_APPLICATION-6-1042",
"stored": true,
"already_stored": false,
"resume": {
"info_candidate": {
"full_name": "Alex MORGAN",
"job_title": "Senior Payroll Analyst",
"email": "alex.morgan@example.com",
"location": { "city": "Denver", "country_code": "US" }
},
"skills": [
{ "skill_title": "Payroll", "skill_type": "Hard skill", "status": "normalized" },
{ "skill_title": "Workday", "skill_type": "Software skill", "status": "normalized" }
],
"languages": [
{ "language": "English", "level": "Native or Bilingual (C2)" },
{ "language": "Spanish", "level": "Professional Working Proficiency (B2)" }
]
},
"warnings": [],
"credits_used": 1
}- Cost: 1 credit per successful parse, 0 when the same file is already stored under that id; failed calls are free. The Free plan includes 50 credits a month.
- Timing: about 35 seconds per resume, with a
504after 145 seconds. For async, send awebhook_url: the call answers202at once. - Errors:
422is not a readable resume,403is out of credits,429and5xxcan be retried. See the errors guide.
4. Write the results back
Put_Candidate_Attachment adds a file to a candidate or to their
job application, as long as you pass an active recruiting document category.
Put_Candidate can add skills, languages and a candidate tag, but
what it acepts depends on your job application template, so test it in your
implementation tenant first. Move_Candidate moves a candidate to
the next stage or to a disposition.
Need a score per application, not only the parsed fields? The Workday integration page scores each application against its requisition and maps every result to its place in Workday, with the attachment request in full. Honestly, that's the part most teams end up wanting once the parsing works.
Frequently asked questions
Does Workday have a REST API for recruiting?
Yes, Recruiting v4. It returns JSON for prospects and their resume
attachments, job postings, interviews and offers, with OAuth 2.0 and
limit/offset paging up to 100. It has no
candidates, job applications or requisitions resource, so integrations
that read applicants' resumes still call the SOAP
Get_Candidates operation.
What is the difference between Workday SOAP and REST APIs?
SOAP (Workday Web Services) covers every functional area with versioned
XML operations such as Get_Candidates and
Put_Candidate_Attachment. REST returns JSON for a smaller set
of resources and authenticates with OAuth 2.0.
What is Workday RaaS?
Reports-as-a-Service: a custom report enabled as a web service, called by the URL the report gives you and returned as JSON, CSV, Simple XML, Workday XML, RSS or GData. It is read-only and capped per day and per hour by company size.
Which resume parser does Workday use?
Workday's documentation names no third-party parsing engine. Its resume parsing fills fields for the recruiter to review and does not fill the Languages or Skills fields.
What are the Workday API rate limits?
Workday throttles requests under high load: 429 on REST and
RaaS, 500 on SOAP, with exponential backoff recommended. It
gives no per-second figure for SOAP or REST. RaaS is capped by company
size, for example 75,000 requests a day and 15,000 an hour below 3,500
workers.
See what a parsed Workday resume looks like
Upload one of your candidates’ resumes in the live demo to see every JSON field, then check limits and errors in the API reference.
Sources and further reading
- Workday Web Services directory (SOAP)
- Workday: Recruiting web service, Get_Candidates (v47.1)
- Workday developer site: API throttling and limits
- Workday REST API directory
- HireLayer: Workday integration
- HireLayer API documentation: Parse a resume
- HireLayer API documentation: Errors and retries
Louis Desclous
Published on · Reading time: 7 minutes
