Create a signature request

post

https://api.wingspan.app/v3/compliance/signature-requests

Opens a signature request against an existing DocumentTemplate. The title and signer roles come from that template.

Either party may call this. You name the RELATIONSHIP you are acting in (payerPayeeId) and never an account, and both account seats are resolved from it. A payer needs no requirement and may name a template directly.

The two payee rules are checked IN ORDER, which decides the status you get. A payee must send requirementId; without it the answer is 400 whatever else the body carries. With it, a payee who also sends templateId, externalId or metadata gets 422. So a 400 here means the requirement is missing — not that the rest of the body is malformed — and retrying with a requirementId is the fix.

A create that cites a requirementId is deduplicated: a repeat for the same relationship and template while an earlier request is still outstanding returns that request rather than opening a second one, so a payee's retry is safe. Three things opt out and open a NEW request — a payer's direct order (no requirementId), an externalId, and a payer reset of the requirement behind it.

Supplying an externalId already in use for this payer account returns 409 ResourceConflict — create is not an upsert. Recover by listing with ?filter[externalId][eq]= to retrieve the existing request. An externalId also opts the request out of the deduplication above, and is rejected outright from the payee seat.

This opens the request; it does not send it for signature. The payee calls POST /compliance/signature-requests/{requestId}/start next to mint the document and receive signing URLs.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Open a signature request against an existing DocumentTemplate. The title and the signer roles come from that template and are not restated here: one template backs many requests, which is how a RequirementType: Signature definition fans one document out across its payees.

ONE body for both parties. You name the RELATIONSHIP you are acting in and never an account, so both account seats are resolved from it. A payee must cite the requirementId that justifies the request and may name neither templateId nor externalId; a payer needs no requirement, and may name a template directly. A payer who sends both has the requirement's template win.

Opening the request does not send it for signature. The payee calls POST /compliance/signature-requests/{requestId}/start to mint the document and get signing URLs.

payerPayeeId

string

required

The payer-payee relationship this request is opened in; never an Account id. Both account seats are resolved from it, and you name neither.

Accepts canonical Wingspan ids and the legacy composite relationship ids the V3 read and list endpoints still return — Requirement publishes payerPayeeId including the complete legacy Account-pair id, and that requirement read is where a payee gets this value. So this is deliberately NOT format: wingspan-id, which would reject a legacy id at the edge and make the endpoint unreachable for the relationships it most needs to serve.

requirementId

string

The requirement this request satisfies, and what authorises it. REQUIRED when the payee opens the request — omitting it returns 400. Optional for the payer, whose direct request needs no requirement behind it.

templateId

string

length ≥ 1

The DocumentTemplate to open against. Unformatted, matching SignatureRequest.templateId on the read side, so a template id read back off a request can be sent straight here. Must be owned by the relationship's payer account; 404 otherwise. Payer only — from the payee seat it is 422 when a requirementId is present, because the requirement names the template (with no requirementId the answer is 400 for that instead). A payer who sends it alongside requirementId has it overridden.

externalId

string

Caller-supplied reconciliation id, unique per payer account. A duplicate returns 409 ResourceConflict. Payer only — the namespace is the payer's, so from the payee seat it is 422 when a requirementId is present (with no requirementId the answer is 400 for that instead).

metadata

object

Annotations stored on the request. Payer only — from the payee seat a non-empty map is 422 when a requirementId is present, because the row carries one annotation bag and it is the payer's (with no requirementId the answer is 400 for that instead). A create that matches an existing outstanding request returns THAT request unchanged, so these are not merged onto it. Send an externalId when you need a distinct request.

Headers

X-Wingspan-Account

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).

Idempotency-Key

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

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json

400Malformed request syntax

401Unauthenticated

403Forbidden

404Resource not found

409Conflict

422Validation error