Onboard an employer

Create the Employer, send any confirmed payroll information your product already holds, then open PayrollKit so the employer can finish setup.

Some tips before you start

Use your server-side PayrollKit access token to authenticate all API requests.
Include an Idempotency-Key with every request that creates or changes data.
Keep a stable ID for each employer, person, employment record and pay schedule you send.
You can save returned PayrollKit IDs to avoid lookup calls.
An ETag identifies the version of a PayrollKit record you last retrieved. When updating that record, send its ETag in the If-Match header so PayrollKit can stop you from overwriting a newer change. If you did not keep it, retrieve the record again before updating it.

Call POST /employers with the employer's legal name and your stable partnerEmployerId.
Use the returned Employer id in later API calls. You can save it to avoid looking it up from your partnerEmployerId.

Optional: Prefill confirmed payroll setup information

If you hold the PAYE reference and Accounts Office reference for an employer, call POST /employers/{employerId}/paye-scheme.
If your product already groups employees by how often they are paid, create one Pay Schedule for each group. For example, create separate schedules for weekly-paid and monthly-paid employees. Call POST /employers/{employerId}/pay-schedules for each group and save the returned Pay Schedule ID.

Send employee information

For each employee, call POST /employers/{employerId}/employments to create their Person and Employment. Send your stable partnerPersonId, their legal name and employment start date, plus any other confirmed payroll details.
Include partnerEmploymentId only if your product identifies the employment separately.

Finish setup in PayrollKit

Create a session with POST /employers/{employerId}/embedded-sessions, using the signed-in user's stable partnerUserId, current displayName and browser origin where you will mount PayrollKit.
Pass the returned token to the component:

<PayrollKit
  sessionToken={session.sessionToken}
  onSessionEnded={({ reason }) => handleSessionEnd(reason)}
/>

PayrollKit shows the employer what remains to be completed.
Use signed webhooks to learn when PayrollKit changes a record, then retrieve its latest state through the API. Follow Keep data in sync when your product also updates PayrollKit records.