API fundamentals

Use these pages to apply the conventions shared by every Wingspan V3 endpoint.

They cover:

• Request and response shapes
• Pagination, filtering, sorting, and related-resource expansion
• Errors, retries, idempotency, concurrency, and asynchronous operations
• Acting on behalf of another Account
• Files, batches, custom fields, and search rows

Read the pages in order when you start an integration, or open the page that answers your question.

Every V3 path starts with /v3/{domain}/, where the domain is payments, finance, onboarding, compliance, or platform. The read-only search surface lives under /v3/search/. Production requests go to https://api.wingspan.app. See Environments and authentication for tokens and the staging host.

Pages

1. Request and response conventions: IDs, field casing, money, dates, metadata, externalId, events and actors, and how updates work.
2. Pagination: page through any list with page[size] and page[token].
3. Filtering, sorting, and expanding: narrow lists with filter[...], order them with sort[...], and inline related resources with expand.
4. Errors: the error format, every error code, and which errors to retry.
5. Idempotency: retry creates and money movement without doing the work twice.
6. Concurrency and ETags: avoid overwriting someone else's change with If-Match.
7. Async operations: follow long-running work that returns 202 Accepted.
8. Acting on behalf of Accounts: use X-Wingspan-Account to work in a child or authorized Account.
9. Versioning: how the V3 API version and the Wingspan-Version header work today.
10. Rate limiting: the four rate-limit buckets, the headers that report them, and how to back off.
11. Files and documents: upload to the vault, attach by fileId, download PDFs, and share secure links.
12. Batches and bulk operations: import payees or payables in bulk and track each item.
13. Custom fields: define your own fields on payees, line items, and engagements.
14. Search: query the eventually consistent search rows under /v3/search.