Shared file requests

A shared file request asks a Payee to upload one file. A configuration decides what is asked for, which file types are accepted, and which automated check runs on the upload. You open a request for one payer-payee relationship, the Payee uploads, and the request completes or fails.

Read Compliance and verification first for the payer and payee rules shared by order-style resources.

Before you start

• Scopes: shared-files.shared-file-settings:read and :write for configurations, shared-files.shared-file:read and :write for requests.
• The file you attach must already be in the vault.

Endpoints

1. Create a configuration

curl -X POST https://api.wingspan.app/v3/compliance/shared-file-request-configurations \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "title": "Driver license",
    "instructions": "Upload a photo of the front of your license.",
    "acceptedMimeTypes": ["image/jpeg", "image/png"],
    "contextType": "DriversLicense"
  }'

The response also carries cost (the per-verification price) and jobs, the planned checklist for the contextType. The id is what a DocumentUpload requirement definition passes as dataSourceId.

A non-None contextType is allowed once per account. A second create with the same one returns 409. Find the existing configuration with GET ...?filter[contextType][eq]=DriversLicense. Any number of None configurations is allowed.

List filters: contextType, externalId (each eq or anyOf), accountIds[anyOf], and includeDescendants. PATCH changes externalId, title, instructions, acceptedMimeTypes, and metadata, but not contextType.

2. Open a request

POST /v3/compliance/shared-file-requests:

The request copies title, instructions, acceptedMimeTypes, and contextType from the configuration and inlines a configuration summary on every read. That summary leaves out cost, externalId, and metadata, which belong to the payer.

curl -X POST https://api.wingspan.app/v3/compliance/shared-file-requests \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "payerPayeeId": "PAYER_PAYEE_ID", "configurationId": "CONFIGURATION_ID" }'

// 201 Created (trimmed)
{
  "id": "REQUEST_ID",
  "title": "Driver license",
  "contextType": "DriversLicense",
  "status": "PendingUpload",
  "uploadHistory": [],
  "jobs": []
}

3. Upload and submit

1. The Payee puts the file in the vault (Vault files).
2. POST .../{sharedFileRequestId}/upload with { "fileId": "VAULT_FILE_ID" }. The file's MIME type must match acceptedMimeTypes. The service limits re-uploads. Each upload is recorded in uploadHistory with fileId and uploadedAt.
3. If validation doesn't pass, the request sits in PendingSubmission. The Payee can upload again or call POST .../submit, which finalizes it as Complete or Failed.

Status

PendingUpload to Processing (extraction and validation running) to PendingSubmission (a validation did not pass) to Complete or Failed. Each entry in jobs has a type (Extraction or Validation), status (Created, Pending, Processing, Complete, Error, Failed), statusReason, and extractedFields. Only validation jobs affect the request status. An extracted driver's license expiration date can become the requirement's expiry. Timestamps are under events. expiresAt is the request's expiry.

List filters on requests: status, payeeAccountId, externalId (each eq or anyOf), accountIds[anyOf], and includeDescendants.

Errors

A repeat create that cites a requirementId and no externalId returns the outstanding request and doesn't merge the repeat's metadata.

Events

SharedFileRequest.Created, Uploaded, Processing, PendingSubmission, Submitted, Completed, Failed.