API Reference

Create a form

post
https://api.wingspan.app/v3/compliance/forms

Creates a form directly. The type field selects the kind of form (for example W9, W4, W8Ben, 1099Nec, W2). Any type may be created this way; the resulting form is owned by the caller's account and starts in Draft. Forms produced by an automation are created by that automation (see TaxFiling), not here, and cannot be edited directly afterwards.

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.

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

Direct creation of a form of any type. Forms produced by an automation are created by that automation, not through this request.

string
enum
required

The kind of form. W9, W4, and W8Ben are collected directly from a worker; the 1099*, W2, and T4A forms are produced and filed by a TaxFiling automation. W8Ben is the non-US-person analogue of W-9. The schema governing each type's formData is published by the FormSchema registry.

string
integer
owner
object

The account or person that created and owns the form.

parties
object

References to the accounts and people the new form concerns. Omit unresolved parties.

recipient
object

A party named on the form (recipient or issuer).

payer
object

A party named on the form (recipient or issuer).

formData

Type-specific form data. The nested type discriminator must match the parent Form.type, which remains the canonical form kind for filtering and lifecycle decisions. The full schema for each type is published by the FormSchema registry.

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.

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
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Updated 4 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 4 months ago

Did this page help you?