Enroll a Payee in an Engagement template, creating a concrete PayeeEngagement record. Idempotent via Idempotency-Key.

engagementType must agree with the template's type, or the request returns 422 with detailCode payments.PayeeEngagementTypeMismatch. It must also agree with the Payee's context (only an Employee engagement agrees with Employee), or the request returns 409 ResourceConflict with detailCode payments.EngagementPayeeContextMismatch; change the context first with change-context. A Payee with no recorded context takes its context from its first engagement, unless it already has active engagements of the other type (409 with payments.PayeeContextIncompatibleEngagements).

When the payer's payroll profile is SingleEmployee, an Employee engagement is refused with 422 and detailCode payments.SingleEmployeeExists while the payer already has a non-terminated Employee engagement.

If externalId is supplied and already used by another resource of this type for the owning Account, the request returns 409 ResourceConflict; create is not an upsert. Use filter[externalId][eq] on the list endpoint to retrieve the existing resource.

worksiteId must name a worksite owned by the payer, or the request returns 422 with detailCode payments.WorksiteNotFound. For an Employee engagement, the worksite must also be in a country W-2 payroll supports and a state enabled on the payer's employer payroll profile. Otherwise the request returns 422 with payments.WorksiteCountryUnsupported, payments.WorksiteJurisdictionUnsupported, or payments.WorksiteJurisdictionNotEnabled. Nothing is saved when the request is rejected.