Which operation to call: Import_Payroll_Input or Submit_Payroll_Input

For a payroll input file with more than a handful of lines, call Import_Payroll_Input. Workday's payroll setup guidance says to prefer it because it is optimized for bulk import, and that Submit_Payroll_Input is also available (Setup Considerations: Payroll Input).

The two differ in shape. Submit_Payroll_Input takes a list of Payroll_Input_Data elements and returns a reference to each payroll input it created. Import_Payroll_Input takes the same Payroll_Input_Data list plus a required Default_Batch_ID, and returns the reference of a background process, not of the inputs. Import_Payroll_Input does not use a business process (Import Payroll Input).

How to call it from an orchestration

In an orchestration the call is a Send Workday API Request step with method POST (Reference: Send Workday API Request). Workday's Supplier Invoices Inbound sample in the App Catalog wires a different Import operation the same way: a Create Text Template step holds the full SOAP envelope with content type text/xml, and Send Workday API Request POSTs it to a relative path, soap/v43.0/Resource_Management in that sample. For payroll input the service is Payroll, so the path becomes soap/{version}/Payroll. The step runs as the default Workday credential or the initiating user, and that account needs permission for the Import Payroll Input operation; see integration system users and API clients.

A minimal request for one one-time earning, with placeholder IDs:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:wd="urn:com.workday/bsvc">
  <soapenv:Body>
    <wd:Import_Payroll_Input_Request wd:version="{version}">
      <wd:Default_Batch_ID>PAYIN-2026-11-04</wd:Default_Batch_ID>
      <wd:Payroll_Input_Data>
        <wd:Payroll_Input_ID>2026-11-04-21001-BONUS-1</wd:Payroll_Input_ID>
        <wd:Batch_ID>PAYIN-2026-11-04</wd:Batch_ID>
        <wd:Ongoing_Input>false</wd:Ongoing_Input>
        <wd:Start_Date>2026-11-01</wd:Start_Date>
        <wd:End_Date>2026-11-30</wd:End_Date>
        <wd:Worker_Reference>
          <wd:ID wd:type="Employee_ID">21001</wd:ID>
        </wd:Worker_Reference>
        <wd:Earning_Reference>
          <wd:ID wd:type="Earning_Code">BONUS</wd:ID>
        </wd:Earning_Reference>
        <wd:Amount>500.00</wd:Amount>
      </wd:Payroll_Input_Data>
    </wd:Import_Payroll_Input_Request>
  </soapenv:Body>
</soapenv:Envelope>

Element order follows the Payroll web service schema. The Employee_ID and Earning_Code ID types and the values are placeholders: confirm the types your tenant accepts with the Integration IDs report. Build the body from your source rows in the orchestration with a text template or an expression, and put every row inside the one request.

Batch the whole file into one request

Workday recommends at least 1,000 payroll inputs per Import request, and suggests testing in a non-production tenant to find the batch size that works for you. The reason is the way the service works: it groups entries into jobs and processes them asynchronously, so calling it once per line, say 1,000 times for 1,000 lines, creates 1,000 queued background jobs. Workday states there is no easy way to recover from that except waiting for them all to finish (Import Payroll Input).

So the orchestration should not put the SOAP call inside a per-row loop. Loop to build the request body, call once. Incoming Import requests can be as large as 2 GB, against 500 MB for other web service requests (Reference: Integrations, EIB, and Web Service Limits). For general loop limits see Orchestrate looping and pagination limits.

Batch ID and Payroll_Input_ID decide whether you can recover

Default_Batch_ID is used for any input that carries no Batch_ID of its own. Use the same batch ID for every entry of one load. Workday's batch tasks, Payroll Input by Batch ID and Delete Payroll Input by Batch ID, work on that value.

Payroll_Input_ID is the duplicate guard. To update an input you must send its existing ID. For a new one you can let Workday generate the ID, or supply one that is unique to that transaction. Workday calls this ID your best protection against duplicate entries. Reuse of one ID across lines makes each line wipe out the one before it, and the guide's advice is to prefix a new ID with a date.

Ongoing, adjustment and worktag fields

  • Ongoing_Input defaults to false. Start_Date and End_Date are both required for one-time entries. An ongoing entry needs a Start_Date, and an End_Date only when you end-date it.
  • Once an ongoing input is in a completed payroll you cannot update or delete it. End-date it and create a new input with the new amount or rate, so an orchestration that maintains ongoing inputs has to look up the right end date itself.
  • Adjustment defaults to false, which overrides any matching input including its amount and related calculations. Set it to true to add an entry that increases or decreases the pay component on the payroll result.
  • Earning_Reference and Deduction_Reference are mutually exclusive on a line. Depending on the pay component, Amount, Hours, Rate, Position and worktags may also be required.
  • Worktags go into dedicated elements in Worktag_Data, not a generic reference list. The ID type is case sensitive and has to match the element. A Custom Worktag 3 value, with type Custom_Worktag_3, goes in Custom_Worktag_03_Reference.
  • For related calculations, Workday-owned ones use Workday_Related_Calculation_ID and the others use Related_Calculation_ID.

Import_Payroll_Input errors and what to change

Workday's Import Payroll Input guide documents these three (Import Payroll Input).

Message or symptom Cause and fix
Message or symptomRequest returns but some inputs are missingCause and fixThe import is asynchronous, so the job may still be running. Check Payroll Input by Batch ID again. A repeated Payroll_Input_ID also overwrites earlier lines.
Message or symptomChanging the worker associated with a Payroll Input is not allowed when updating an existing Payroll Input.Cause and fixAn ID in the request already exists for a different worker or in a completed input. Give new inputs fresh IDs.
Message or symptomValidation error occurred. Invalid ID value. 'W_NETGU is not a valid ID value for type = 'Related_Calculation_ID'Cause and fixWrong ID type for a Workday-owned related calculation. Use Workday_Related_Calculation_ID, and check types in the Integration IDs report.

How to confirm the load and back it out

The response only proves the request was accepted. It carries the reference of the import process, and you track that process in Process Monitor or with the Get Import Processes operation of the Integrations web service. Get Import Process Messages returns its messages (Concept: Import Web Service Pattern). Then run the Payroll Input by Batch ID report for your batch ID and compare the count and totals with the source file.

To test without writing anything, send the X-Validate-Only: 1 HTTP header on a version of the web service that supports it (v27.0 or later). For Import operations the response then holds the process ID and the validation messages come from Get Import Process Messages. Only the validations listed for the operation are tested, so custom and post-processing checks still run only on a real load (Concept: Workday SOAP API Headers). In Send Workday API Request, add it on the Headers tab.

To back out a bad load, run Delete Payroll Input by Batch ID. It fails for the whole batch if even one entry is part of a completed payroll. In that case run Cancel Pay Complete on the affected payrolls first, then delete the batch, then resend. Batches are deleted one at a time, not by multiselect.

If a step fails before Workday accepts the request, read the step error as described in Orchestrate errors.

Sources checked