Skip to main content

Supporting document collection

A collection of documents (think of a folder) containing documents gathered for a specific reason, such as during account holder verification. Swan collects these documents according to local regulations.

Swan is sometimes required to collect documents to verify account holder details. Each document is uploaded individually into a collection. After all required documents are uploaded, Swan reviews the collection.

Required documents​

The documents required varies significantly depending on where your users are located, whether they're individuals or companies, and more. The best way to understand what is required from your user is to always get a list of required documents when you create the onboarding link.

You can review accepted document formats in the document center.

Options for collecting documents​

There are two primary options to collect required supporting documents:

  1. Use the API.
    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.
  2. Swan communicates directly with you or your end users.
    1. You or your end user receives an email.
Recommendation

Swan recommends using the API to manage documents and collections.

Collecting documents with the API​

Collecting supporting documents impacts multiple elements of the onboarding process. Consider these steps, including the statuses of both account holder verification and the supporting document collection.

StepEventAccount holder
verification status		Supporting document
collection status
1
Onboarding finalized
NotStarted
PendingReview
2
Legal representative completes identification
Pending
PendingReview
3
Swan requests supporting documents
WaitingForInformation
WaitingForDocuments
→ Subscribe to the supportingDocumentCollection.updated webhook. You'll be notified when a request is sent to collect documents.
4
Partner uploads new documents
WaitingForInformation
WaitingForDocuments
→ If needed, get a list of required documents. Then, upload missing documents.
5
Partner requests a collection review
Pending
PendingReview
→ Partners (you) need to request a supporting document collection review after all supporting documents are uploaded. Request a review with the API or from your Dashboard.
6
Swan reviews supporting documents
Pending
PendingReview
7a
Swan approves the account holder
Verified
Approved
7b
Swan needs more documents to verify the account holder
WaitingForInformation
WaitingForDocuments
→ Get the list of required documents and review the rejection reason. Then, return to step 4.

Collection statuses​

Each collection runs through the following statuses. This process starts after an onboarding is created.

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​

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.

Each document added to a collection runs through the following 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.