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 (more information in next section)
DeletedSwan or the partner deleted the document
Not uploadedURL was generated but collection was closed before a document was uploaded

Refused document reason codes​

When any type of supporting document is Refused, the reason is displayed on your Dashboard. Navigate to the supporting document area for the relevant onboarding, transaction, or account holder verification. You can also query the API.

Reason codeExplanation
CompanyNameMismatchThe company name in the document submitted doesn't match Swan's records.
DeclaredAmountMismatchThe declared amount in the document submitted doesn't match Swan's records.
ExpiredDocumentDocuments must have been issued within the last three months.
InvalidAddressThe address in the document submitted doesn't match Swan's records.
InvalidDocumentThe document submitted isn't valid or in an accepted format.
InvalidOrMissingDataThe shareholder's name in the document submitted is invalid, missing, or not clearly visible.
MissingAccommodationProviderIdAn identity document for the accommodation provider is required.
MissingAccommodationProviderIdLetterThe accommodation provider's ID and letter providing proof of accommodation are required.
MissingAccommodationProviderLetterA letter providing proof of accommodation from the provider is required.
UnacceptableDocumentThe document submitted doesn't match the requested document type.
ProviderColorIdDocumentRequiredThe document must be submitted in color.
MissingSignatureThe document submitted must be signed or dated.
BadDocumentQualityThe quality of the document submitted is too low. All document content must be clear and legible.
FullDocumentRequiredThe entire document must be sumbitted, not just a portion of the document.
MissingProviderProofOfAddressThe accommodation provider's proof of address is required.
MissingProviderProof
OfAddressAndIdDocument		The accommodation provider's ID and proof of address are required.
PowerOfAttorneyToSwanRequiredA signed and dated Power of Attorney must be provided to Swan.
MissingCompanyDomiciliationStatementA document stating the company's registered address is required. This document can be referred to as a domiciliation statement.
HandwrittenOrCertified
ElectronicSignatureRequired		The signature must be handwritten or electronically certified.
MissingDescriptionMore information is needed to understand the nature of this transaction.
InvalidTransactionThe information in the document submitted doesn't match this specific transaction.
TransactionNameMismatchThe issuer or beneficiary name in the document submitted doesn't match the transaction details.
TransactionDateMismatchThe date in the document submitted doesn't match the transaction details.
TransactionAmountMismatchThe transaction amount in the document submitted doesn't match the transaction details.
IbanMismatchThe beneficiary IBAN in the document submitted doesn't match the transaction details.

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.