Basics of Using Workday SOAP API for Learning Integration

If you’re looking to build a Workday Learning integration to push content and completions to Workday you will need to use the SOAP API, this guide covers the basics - from authentication and permissions to managing learning content and completions sync.

At StackOne, we wanted to build a deep, robust integration that could support learning content providers surfacing their external hosting training content within their customers’ Workday environments. This improves discoverability of the providers’ content and enriches the learning options available to the end customer, whilst still maintaining Workday as the source of truth for learning content and user training records.

Additionally it creates a seamless learning experience where end users can access content from different providers in a single place, whilst actually consuming that content in the best environment, namely the learning content provider’s own platform.

These are the basics to help you integration with any Workday integration (and any SOAP operation), and a in-depth use-case on building a Workday Learning Integration.

Workday SOAP API

Unlike 83% of the rest of API providers who use REST, Workday most comprehensive API offering uses the SOAP protocol. The main implication of this is that data is expected and returned in XML. See below

Workday uses SOAP which involves handling complex XML structures

This means you will need to transform data from your native structure into XML to push data to Workday, as well as transforming the response from XML to your expected structure.

This can be especially tricky when it comes to managing content on the third party platform (more on this later)

Workday SOAP API Authentication and Permissions Setup

While the SOAP authentication is relatively simple, the way this ties into configuring an admin user and permissions is more complicated. There is also limited available information on what permissions are required for which web services, so in an ideal world you’ll have a Workday expert on hand to help you navigate this.

If you don’t, then some digging on the Workday UI will help. There are 3 levels of permissions on Workday:

Modules

In order to access Workday Learning, the end user must have purchased the Workday Learning module.

Security Group Permissions

These must be configured on a Security Group level, which an integration user is then assigned to. You can find which security group permissions are required for which web services by using the View Security for Securable Item task

Business Processes

These are the background tasks which handle the actual job which is kicked off by the web service. In our use-case we need to configure a Manage_Course business process to ensure we kick of the process of creating or updating a course on the tenant.

You can find which business policies are required in the SOAP web service docs. They can be configured by searching the business policy, clicking Edit Business Process Policy and then adding the required security group.

Now you’re nearly ready to start making requests.

You just need to construct the SOAP Envelop header with your system user credentials:

Navigating Workday SOAP API Documentation Inconsistencies

Once you have the infrastructure in place to handle SOAP requests and have correctly configured a system user, group and permissions/business processes, you can get ready to make a request.

Sometimes the Workday docs are just plain wrong

Workday does provide some helpful documentation, in particular pre-made xml request objects, see below:

Unfortunately, you may sometimes find that the documentation is just plain wrong.

For example in the above block it says the second nested block within Manage_Learning_Course_Data should be Learning_Digital_Course when in fact it should be Put_Learning_Digital_Course_Request.

Handling Workday SOAP API Errors and Fault Responses

The final thing to note in getting to grips with the basics of Workday SOAP API is that Workday does not confirm to standard error codes.

Usually you’d expect to see something that represents the underlying error but Workday will always return a 500 error for unsuccessful requests

Workday always returns a 500 for all errors

In order to understand the true errors that may have occurred you need to dig into the nested body which may look something like this:

Over time, you’ll need to build up a library of responses and identify all the major issues that can arise.

Managing Content and Learner Completions via Workday SOAP API

Now we’ve covered some of the basics of Workday, we can look at how we actually manage content and completions via a Workday Learning Integration.

Creating and Updating Content via Workday SOAP API

We use the Manage_Digital_Courses endpoint to create content which is wrapped in a course layer and then is discoverable and consumable on the Workday platform.

Workday SOAP API Docs

Implementing Upsert behaviour on Workday

Workday has some restrictions when it comes to adding content to a Workday tenant. The Learning_Course title must be unique, as must the Learning_Course_ID. The title is required in the request body but Workday will automatically create a Learning_Course_ID if one isn’t passed in.

Workday have a single operation which is used for both creating and updating content

Finally, Workday also will overwrite any fields in an existing content item which are not passed in the request, so it is impossible to just patch specific fields.

Workday doesn’t allow patch, so you will need to spread in any existing content information to ensure it isn’t lost

However, you can use the quirks to your benefit by creating a flexible upsert approach that will avoid you having to store identifiers and will ensure you create and update content as efficiently as possible.

You can do this as follows:

• Provide a Learning_Course_ID to the content which can then be used as the primary identifier for further update requests and also to create enrollments.
• Workday will throw an error if you are trying to create content with a non unique Learning_Course or Learning_Course_ID, so you must check if content exists by both these references.
• If content already exists, retrieve the content data and over-write the specific fields you want to update
• Push the content with the Learning_Course_ID as the reference, which will flag Workday to update that specific content item

The Learning_Course_ID then becomes your own identifier which can be used to reference the content in future.

Sample Manage_Learning_Course SOAP API Request

You should use the following request, with the required fields:

What’s happening is as follows:

We create a course object, with the external url created as a lesson within that course

Creating Enrollments via Workday SOAP API

Workday SOAP API Docs

We need 2 specific IDs to create a completed enrollment - the user id and the course id.

We know from the previous step that we can use our external reference as the course id, and there a couple of ways to get the user id.

1. SSO (internal workers only) - if you are just creating completions for employees (not external learners or contingent workers) then you can, in most cases, have the employee_id set in the SSO be passed across in the SAML data. You can they use this directly in the completions request
2. SSO (external workers/learners) - if you want to use SSO but also need to record learning for external workers/learners then you must handle 3 ids in the SSO and use the correct id type accordingly in the completions request (Employee_ID, Contingent_Worker_ID, External_Learning_User_ID)
3. List Users - If you need a more flexible approach to matching users, you can list the users via the Workday API and than match across a number of identifiers.

There are a number of other quirks involved with creating completions that must be considered to ensure a consistent reporting experience. We will touch on these in a later post

Sample Put_Learning_Enrollment SOAP API Request

You should use the following request, with the required fields:

Why integrate with your customers’ LMS platforms

Modern, API-first integrations into LMS platforms enable Learning Content providers to provide a seamless experience for their end users, a ‘best of both worlds’ scenario in which content is made available within their core LMS - the customer’s ’source of truth’ for learning - and all user training data is recorded there, but the content can be consumed on the Learning Content provider’s purpose-built platform.

This approach also allows Learning Content providers to;

• improve discoverability of their content
• increase their distribution channels
• stay in control of their content
• avoid the many pains of dealing with SCORM files

API-based integrations are also uniquely well suited to more modern learning paradigms like;

• dynamic content generation
• gamified learning
• AI role-play based learning
• VR based learning

But, as we see from the Workday example above, integrating into even a single LMS platform is fraught with complexity; scaling integrations across multiple LMS is an even greater challenge.

About StackOne

StackOne enables Learning Content providers to rapidly scale integrations across an entire category of enterprise LMS platforms - including Workday, SAP, Oracle, Cornerstone, 360Learning and more - by abstracting the complexity of their differing APIs and authentication methods behind a single, standardised API, backed by powerful underlying integrations infrastructure that includes webhooks, observability, multi-region data processing, AI-enabled debugging and much more.

StackOne LMS API Docs

Key Takeaways

• Workday’s most comprehensive web services uses a SOAP-based API, meaning all requests and responses use XML. Understanding how to construct and parse SOAP envelopes is essential for any Workday Learning integration.
• Authentication depends on correctly configured permissions, including module access, security group permissions, and business process policies.
• Documentation can be inconsistent — validating payload structures against your tenant schema is often necessary.
• Workday’s error handling is unconventional; failed requests return a 500 status, so you must inspect SOAP fault responses for meaningful messages.
• Upsert operations are powerful but destructive — Workday overwrites fields not included in the request body. Always manage field data carefully.
• Learning content and completions sync rely on correct mapping of Learning_Course_ID and user identifiers (Employee_ID, Contingent_Worker_ID, etc.).
• Efficient integrations require balancing automation (via Manage_Learning_Course_Request and Put_Learning_Enrollment_Request) with tenant-specific configuration and permissions setup.
• StackOne are a unified API layer that allow companies to massively scale API integrations

Conclusion

Building a Workday Learning integration via the SOAP API can be complex, but mastering authentication, permissions, and XML structures unlocks deep control over learning content and completions across your Workday environment.

Next time we will share more information on improving content discoverability, handling completions quirks and other gotchas of working with the Workday SOAP API.

Interested in Learning more?

Join us for a Webinar on building a REST based Workday Learning integration and embedding this into your Agentic Ecosystem powering a content discovery engine.

https://luma.com/dtkpbdnc?utm_source=blog

‍