SDK Utilization for Workday API Developers: Client Libraries for .NET and Java

You need access to a Workday tenant (sandbox is fine) and an Integration System User (ISU) account with the appropriate domain security permissions for the operations you intend to call. The examples in this article target Workday Web Services (WWS) v42.0, though the same approach applies to any supported version.

// Apply WS-Security header via custom endpoint behaviour (see below)
// Username MUST be: username@tenantname
client.ClientCredentials.UserName.UserName = “isvc_hrfeed@acmecorp”;
client.ClientCredentials.UserName.Password = “your_secure_password”;

var endpoint = new EndpointAddress(_tenantUrl);
var client = new Human_ResourcesPortClient(binding, endpoint);

// CRITICAL: Workday expects WS-Security in the SOAP header.
// This requires a custom endpoint behaviour , the built-in
// ClientCredentials does not produce the right header structure.
client.Endpoint.EndpointBehaviors.Add(
new WorkdayUsernameTokenBehaviour(_username, _password)
);

return client;
}

public async Task<Get_Workers_ResponseType> GetWorkerAsync(string employeeId)
{
var client = BuildClient();

var request = new Get_Workers_RequestType
{
version = “v42.0”,
Request_Criteria = new Worker_Request_CriteriaType
{
Worker_Reference = new[]
{
new WorkerObjectType
{
ID = new[]
{
new WorkerObjectIDType
{
type = “Employee_ID”,
Value = employeeId
}
}
}
}
},
Response_Filter = new Response_FilterType
{
Count = 1,
CountSpecified = true
},
Response_Group = new Worker_Response_GroupType
{
Include_Personal_Information = true,
Include_Personal_InformationSpecified = true,
Include_Employment_Information = true,
Include_Employment_InformationSpecified = true
}
};

try
{
var response = await client.Get_WorkersAsync(
new Get_WorkersInput(null, request)
);
return response.Get_Workers_Response;
}
catch (FaultException<Validation_FaultType> fault)
{
// Workday returns structured validation faults , catch them specifically
var errors = string.Join(“; “,
fault.Detail.Validation_Error.Select(e => e.Message));
throw new WorkdayApiException(
$“Workday validation fault for worker {employeeId}: {errors}”, fault);
}
catch (FaultException ex)
{
throw new WorkdayApiException(
$“SOAP fault calling Get_Workers: {ex.Message}”, ex);
}
finally
{
// Always close or abort , never let a faulted channel sit open
if (client.State == CommunicationState.Faulted)
client.Abort();
else
await client.CloseAsync();
}
}
}

WorkdayUsernameTokenBehaviour referenced above is a custom IEndpointBehavior / IClientMessageInspector that injects a wsse:Security header into every outbound SOAP message. Workday validates this header strictly , the password must be sent as PasswordText (not PasswordDigest), and the namespace prefix must match what Workday expects. If you get a SOAP fault with code E:AuthenticationError and no other detail, this header is almost certainly the issue.

// Other IEndpointBehavior methods are no-ops for this use case
public void AddBindingParameters(ServiceEndpoint ep, BindingParameterCollection bp) { }
public void ApplyDispatchBehavior(ServiceEndpoint ep, EndpointDispatcher ed) { }
public void Validate(ServiceEndpoint ep) { }
}

public class UsernameTokenInspector : IClientMessageInspector
{
private const string WssNs = “http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd”;
private const string PwType = “http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText”;

private readonly string _username;
private readonly string _password;

public UsernameTokenInspector(string username, string password)
{
_username = username;
_password = password;
}

public object BeforeSendRequest(ref Message request, IClientChannel channel)
{
var header = MessageHeader.CreateHeader(
“Security”, WssNs,
new UsernameTokenBody(_username, _password),
new UsernameTokenSerializer()
);
request.Headers.Add(header);
return null;
}

public void AfterReceiveReply(ref Message reply, object correlationState) { }
}

// Serialiser writes the exact XML structure Workday expects:
// <wsse:Security>
// <wsse:UsernameToken>
// <wsse:Username>user@tenant</wsse:Username>
// <wsse:Password Type=”…#PasswordText”>password</wsse:Password>
// </wsse:UsernameToken>
// </wsse:Security>

private final String username; // user@tenantname
private final String password;

public WorkdayHrService(String username, String password) {
this.username = username;
this.password = password;
}

private Human_ResourcesPort buildPort() {
// The generated service class is named after the WSDL service element
Human_Resources service = new Human_Resources();
Human_ResourcesPort port = service.getHuman_ResourcesPort();

BindingProvider bp = (BindingProvider) port;

// Override the WSDL-defined endpoint with your tenant’s URL
bp.getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY, ENDPOINT);

// Increase timeout defaults , Workday report-style calls can be slow
bp.getRequestContext().put(“com.sun.xml.ws.request.timeout”, 120_000);
bp.getRequestContext().put(“com.sun.xml.ws.connect.timeout”, 30_000);

// Attach WS-Security handler
List<Handler> handlers = bp.getBinding().getHandlerChain();
handlers.add(new WorkdaySecurityHandler(username, password));
bp.getBinding().setHandlerChain(handlers);

return port;
}

public GetWorkersResponseType getWorker(String employeeId) throws Exception {
Human_ResourcesPort port = buildPort();

GetWorkersRequestType request = new GetWorkersRequestType();
request.setVersion(“v42.0”);

// Build criteria , filter to a specific employee
WorkerRequestCriteriaType criteria = new WorkerRequestCriteriaType();
WorkerObjectType workerRef = new WorkerObjectType();
WorkerObjectIDType workerId = new WorkerObjectIDType();
workerId.setType(“Employee_ID”);
workerId.setValue(employeeId);
workerRef.getID().add(workerId);
criteria.getWorkerReference().add(workerRef);
request.setRequestCriteria(criteria);

// Response filter , limit to 1 record
ResponseFilterType filter = new ResponseFilterType();
filter.setCount(new java.math.BigDecimal(1));
request.setResponseFilter(filter);

// Response group , include personal and employment data
WorkerResponseGroupType group = new WorkerResponseGroupType();
group.setIncludePersonalInformation(true);
group.setIncludeEmploymentInformation(true);
request.setResponseGroup(group);

try {
return port.getWorkers(request);
} catch (ValidationFaultMsg fault) {
// Workday validation faults carry structured detail
String errors = fault.getFaultInfo()
.getValidationError()
.stream()
.map(e -> e.getMessage())
.collect(java.util.stream.Collectors.joining(“; “));
throw new RuntimeException(
“Workday validation fault for worker “ + employeeId + “: “ + errors, fault);
}
}
}

private final String username;
private final String password;

public WorkdaySecurityHandler(String username, String password) {
this.username = username;
this.password = password;
}

@Override
public boolean handleMessage(SOAPMessageContext ctx) {
Boolean outbound = (Boolean) ctx.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
if (!outbound) return true; // only process outbound messages

try {
SOAPMessage message = ctx.getMessage();
SOAPEnvelope envelope = message.getSOAPPart().getEnvelope();
SOAPHeader header = envelope.getHeader();
if (header == null) header = envelope.addHeader();

// <wsse:Security>
SOAPElement security = header.addChildElement(
“Security”, “wsse”, WSSE_NS);
security.addAttribute(
envelope.createName(“mustUnderstand”, “soap”,
envelope.getNamespaceURI()),
“1”);

// <wsse:UsernameToken>
SOAPElement token = security.addChildElement(
“UsernameToken”, “wsse”, WSSE_NS);

// <wsse:Username>user@tenantname</wsse:Username>
SOAPElement user = token.addChildElement(“Username”, “wsse”, WSSE_NS);
user.addTextNode(username);

// <wsse:Password Type=”…#PasswordText”>password</wsse:Password>
SOAPElement pw = token.addChildElement(“Password”, “wsse”, WSSE_NS);
pw.addAttribute(envelope.createName(“Type”), PW_TYPE);
pw.addTextNode(password);

message.saveChanges();

} catch (SOAPException e) {
throw new RuntimeException(“Failed to attach WS-Security header”, e);
}

return true;
}

@Override public boolean handleFault(SOAPMessageContext ctx) { return true; }
@Override public void close(MessageContext ctx) { }
@Override public Set<QName> getHeaders() { return null; }
}

do {
filter.setPage(new java.math.BigDecimal(page));
request.setResponseFilter(filter);

GetWorkersResponseType response = port.getWorkers(request);
ResponseResultsType results = response.getResponseResults();

// Total pages tells you when to stop
totalPages = results.getTotalPages().intValue();

if (response.getResponseData() != null) {
allWorkers.addAll(response.getResponseData().getWorker());
}

System.out.printf(“Page %d of %d , retrieved %d workers so far%n”,
page, totalPages, allWorkers.size());

page++;

} while (page <= totalPages);

return allWorkers;
}

Retrieving a full worker population for a large enterprise (10,000+ employees) using Get_Workers with all response groups enabled can take several minutes and produce very large XML payloads. In practice, use the most targeted request criteria possible and only include the response groups you actually need. For bulk data extraction, Workday’s RaaS (Report-as-a-Service) API is often faster than paginated Get_Workers calls.

If you are building a .NET or Java client against Workday’s API and running into WS-Security issues, pagination gaps, or WSDL versioning problems, our Workday Integration Services team has dealt with all of these in production environments across dozens of tenant configurations.

If your integration is already live but behaving unpredictably , wrong data, missed records, authentication errors that appear randomly , our Support & Troubleshooting service covers SDK-level diagnostics and API call analysis.

For teams at the design stage deciding how to connect Workday to their application stack, our Custom Integration Development practice builds production-ready .NET and Java Workday clients from the ground up.