Skip to content

Workday API Guide: SOAP, REST, RaaS and Resume Files

How the Workday API works: SOAP Web Services vs REST vs RaaS, integration system users and OAuth, Get_Candidates paging and resume files, with Python code.

Published · 7 minutes read

Cover reading “Workday API guide for developers” with a code icon and a shield icon

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

https://<host>/ccx/service/<tenant>/Recruiting/v47.1

Recruiting RESTRecruiting v4: prospects, job postings, interviews, offers. No candidates, job applications or requisitions
AuthSOAP: 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
VersionsTwo releases a year, each with new web service versions; v47.1 is 2026R2. You pin one in the URL
PaginationSOAP: Page and Count (1 to 999, default 100) with a fixed As_Of_Entry_DateTime. REST: limit (up to 100) and offset
ThrottlingUnder load, 429 on REST and RaaS, 500 on SOAP; back off exponentially. RaaS has daily and hourly caps
Resume filesBase64 in Resume_Attachment_Data of Get_Candidates; attachments up to 30 MB
DocsWorkday Web Services directory, REST API directory and Workday developer site, checked November 19, 2026

SOAP, REST or RaaS?

APIBest forWatch out for
Web Services (SOAP)Candidates, job applications, resume files, requisitions, moving a candidate, adding attachmentsXML envelopes, one version per URL
REST (Recruiting v4)JSON reads of prospects and their resumes, job postings, interviews and offersNo candidates or job applications
RaaSBulk reads shaped by a custom report, as JSON, CSV or XMLRead-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 root

Get_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 504 after 145 seconds. For async, send a webhook_url: the call answers 202 at once.
  • Errors: 422 is not a readable resume, 403 is out of credits, 429 and 5xx can 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

  1. Workday Web Services directory (SOAP)
  2. Workday: Recruiting web service, Get_Candidates (v47.1)
  3. Workday developer site: API throttling and limits
  4. Workday REST API directory
  5. HireLayer: Workday integration
  6. HireLayer API documentation: Parse a resume
  7. HireLayer API documentation: Errors and retries

Louis Desclous

Published on · Reading time: 7 minutes