Register an Employer

​

Registers an Employer using a partnerEmployerId from your product. The ID:

  • Is case-sensitive.
  • Must be unique within your Partner account.
  • Cannot be changed after registration.

If the ID is already registered, PayrollKit returns 409 partner_employer_id_conflict. When this happens, use List Employers with partnerEmployerId=YOUR_PARTNER_EMPLOYER_ID, then confirm that the returned Employer represents the same business.

OAuth scopes
  • employers:write

Headers

  • Idempotency-Key
    Type: string
    min length:  
    16
    max length:  
    200
    required

    Identifies one write for safe retries. Reuse it only for the same method, URL, content type and body and, when present, the same If-Match value and acting-user headers. PayrollKit retains the result for 30 days, then treats a request using the same key as new.

  • X-Request-Id
    Type: stringFormat: uuid

    Client-generated UUID for tracing. This does not make retries safe.

Body

required
application/json
  • legalName
    Type: string
    min length:  
    1
    max length:  
    200
    required

    Employer's legal name.

  • partnerEmployerId
    Type: string
    min length:  
    1
    max length:  
    200
    required

    Stable, case-sensitive Employer ID from the Partner product. It must be unique within the Partner and cannot be changed after registration.

Responses

  • application/json
  • application/problem+json
  • application/problem+json
  • application/problem+json
  • application/problem+json
  • application/problem+json
  • application/problem+json
  • application/problem+json
post/employers
Registered Employer
{
  "id": "er_7d91f2c8",
  "partnerEmployerId": "company_4821",
  "legalName": "Lantern House Hospitality Ltd",
  "revision": "rev_8c41d2a7",
  "createdAt": "2026-08-20T09:00:00Z"
}

Employer registered