Vault files

The vault at /v3/compliance/vault-files holds every file that other compliance resources point at. This page lists the routes and fields, and explains the two download routes. For the three-step upload flow, attaching files, and sharing, see Files and documents.

Scopes: files.files:read and files.files:write.

Endpoints

File fields

A VaultFile has id, title, description, filename, fileUrl, mimeType, fileSize, kind, status, visibility, document, payeeId, externalId, accountId, events, actors, and metadata.

fileUrl is a stored reference, never a signed link. For a Public file it is the permanent unsigned link. For any other file it is the absolute URL of the /file route, so opening it still needs your token. File contents, kind, and document lineage can't change after create.

List filters: payeeId, visibility, kind, externalId, each eq.

Download a file: /file and /file-url

Both routes return the same signed link. They differ in how:

• GET .../{fileId}/file answers 302 with the link in Location. Use it from a server or a client that follows redirects.
• GET .../{fileId}/file-url answers 200 with JSON. Use it where a redirect can't be followed, such as a browser page that must navigate to the file instead of fetching it from script.

curl https://api.wingspan.app/v3/compliance/vault-files/FILE_ID/file-url \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

// 200 OK
{ "url": "https://files.example.com/signed-link", "expiresAt": "2026-11-02T17:35:00Z" }

• Anyone holding url can download the file until expiresAt. Don't store or log it. Call the route again for each download.
• expiresAt is null when the link doesn't expire, as for a Public file.
• Both routes send Cache-Control: no-store.
• 404 when the file doesn't exist for you. 503 when no link could be issued.

The same pair exists for insurance certificates (see Insurance coverage) and tax form PDFs.

Summary

GET .../{fileId}/summary returns fileId, title, extractedFields, and pageCount.

Delete a file

DELETE soft-deletes the file and returns 204. It returns 409 when the file is referenced by an active attachment, template, signature request, tax form, or identity record.

Errors

Events

VaultFile.Created and VaultFile.Updated.