API Reference

Create an engagement template

post
https://api.wingspan.app/v3/payments/engagements

Create a reusable Engagement template that defines requirements, work definitions, and compensation structure for payee engagements. If externalId is supplied and already exists for the acting Account, the request fails with 409 ResourceConflict; this create is not an upsert. When the Account's payroll profile is SingleEmployee, an Employee engagement with a worksiteId returns 422 with detailCode payments.SingleEmployeeEngagementExists while the Account already has an active Employee engagement. An Employee engagement template must set worksiteId or isRemote: true; omitting both returns 422 with detailCode payments.EngagementWorkLocationRequired.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
required
string
string

Customer's own ID for reconciliation. Accepted on create, echoed on every read.

metadata
object

Free-form key-value pairs. Max 50 keys; key length at most 40 characters; value length at most 500 characters. Where a list endpoint declares metadata filtering, it uses the QueryQL namespace via filter[metadata.{key}][eq]=value or filter[metadata.{key}][in][]=value. Endpoints that do not declare the dynamic Metadata filter do not support Metadata filtering.

requirementDefinitionIds
array of strings
requirementDefinitionIds
workDefinitions
array of objects
workDefinitions
boolean

Creates the account's default engagement. Payables and batch items that name a payee without an engagement are issued under it. Only a Contractor engagement can be the default (otherwise 422), and an account has at most one (409 if it already has one). The default engagement cannot be archived or deleted, and requirements cannot be added to it.

string

Base RateCard for the Engagement. The referenced RateCard must belong to the acting Account selected by the session or X-Wingspan-Account.

string
enum

The kind of work agreement between payer and payee.

  • Contractor — 1099-NEC payment relationship; no withholding.
  • Employee — W-2 payroll relationship; gross-to-net withholding.
    Location is selected on each PayeeEngagement; omitting its
    worksiteId means remote work.
    An Employee engagement template must set worksiteId or isRemote: true.
  • EmployeeOfRecord — EOR engagement; Wingspan or partner is the
    legal employer-of-record. Requires resolved natural-person identity
    before the EOR flow completes.
  • AgentOfRecord — AOR engagement; agent acts on behalf of the
    payer for engagement administration.
Allowed:
string

Worksite for onsite Employee work. An Employee engagement template needs either this or isRemote: true.

boolean

Set true for remote Employee work. An Employee engagement template needs either this or worksiteId.

Headers
string
length between 1 and 255
^[\x21-\x7e]{1,255}$

Optional idempotency token for authenticated POST and PATCH requests. Reusing the same key and body returns the cached response for 24 hours, except credential operations that explicitly document a 409 because one-time secret material is never cached; reusing it with a different body returns 409 IdempotencyKeyConflict. Use 1-255 printable ASCII characters.

string
^(?:[A-Za-z0-9_.]{22}|[a-f0-9]{24})$

Select the Account for an Account-scoped operation. A direct ServiceAccount API key MUST supply this header, and the target must be within the ServiceAccount owner's or Authorization grant's Account boundary. A Person bearer may select an Account on which it has an active Stakeholder, and an Account session may select its bound Account (or a descendant only when the session explicitly includes descendants).

string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Updated 5 months ago

Did this page help you?
Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
application/problem+json

Updated 5 months ago

Did this page help you?