Skip to main content

Supporting documents

A collection of documents (think of a folder) containing documents gathered for a specific reason, such as when onboarding a new account holder or to collect information about a transaction. Swan collects these documents according to local regulations.

Overview​

Swan is sometimes required to collect documents to verify account holders and transaction details.

Each document is uploaded individually into a collection. After all required documents are uploaded, Swan reviews the collection.

Supporting document collections are empty when created. Swan can upload some documents, and you can add documents to these collections as requested. For each required document, you'll create a document within the collection.

Options for collecting documents​

There are two primary options to collect required supporting documents:

OptionExplanation
Use the API

✅ Recommended
  1. No emails are exchanged.
  2. You'll know every time a document is needed with webhook notifications.
  3. You communicate with your end users to gather the required documents.
  4. Choose the API or the Dashboard for most actions, including uploading documents.
Email communication
  1. Swan communicates directly with you or your end users.
  2. You or your end user receives an email.
  3. When Swan emails your end users directly, you can be copied (CCd) on the email. Let a member of the Swan team know to save this preference.

Required documents​

Documents might be required to support verifying an account holder or proving the validity of a transaction. The documents required vary significantly depending on why Swan needs to collect the documents, where your users are located, whether they're onboarding as individuals or companies, and more.

Refer to the API Reference for a list of possible supporting document purpose Enums.

Onboarding tip

For a better user experience, always include a list of required documents in your onboarding flows.

Statuses​

Collections and documents have unique statuses.

Collection statuses​

Collection statusExplanation
Waiting for documentOnboarding is created and ready for documents, or documents were submitted but Swan is requesting additional documents

Next step: moves to Pending review after onboarding is finalized
Pending reviewOnboarding is finalized and a document review is needed

Next step: Can move to Approved, Rejected, or Canceled depending on partner actions and Swan decisions (or, if documents are insufficient → Waiting for document)
ApprovedSwan approved the supporting document collection
RejectedSwan rejected the supporting document collection
CanceledSwan canceled the supporting document collection (this could also be at the partner's request)

Document statuses​

Document statusExplanation
Waiting for uploadURL to upload the document has been generated

Next step:
  • If the document is uploaded → Uploaded
  • If the collection switches to a final status before the document is uploaded → Not uploaded
UploadedDocument is uploaded; if a review is completed on the uploaded document, the status moves to Validated, Refused, or Deleted depending on Partner actions and Swan decisions
ValidatedSwan approved the document
RefusedSwan refused the document
DeletedSwan or the partner deleted the document
Not uploadedURL was generated but collection was closed before a document was uploaded

Document purposes and types​

For all supporting documents, there is a high-level purpose and a more specific type (supportingDocumentPurpose and supportingDocumentType). Both purpose and type can be exposed in the onboarding success payload.

Common purposes (not exhaustive):

  • CompanyRegistration
  • SignedStatus
  • ProofOfAddress
  • ProofOfIncome
  • Other

Guides​

Use the following guides to manage required documents for the onboarding process.