Skip to main content

Know Your Customer (KYC)

The documents API, given an end user's accountId, will enable you to upload or download necessary KYC documents. This will usually be a picture of a passport, picture of a driver's license, or a picture of a face with an Id.

Note, only accountId's that are created under your organization will be accessible.

Note, if you upload KYC documents to an account that has KYC documents already, you will overwrite any documents currently on the account.

  1. Getting KYC documents & user status
  2. Submit KYC personal information
  3. Uploading & submitting KYC documents

Getting KYC documents & user status #

URL : /v1/kyc/docs

Method : POST

Auth required : Yes (API key and secret are required)

Success Response#

Code : 200 OK

Sample response return:

{  "accountId": "12345",  "document_type": "DRIVERS_LICENSE",  "account_kyc_status": "UNDER_REVIEW",  "document_urls":     ["https://usewinter.com/afsf13141",     "https://usewinter.com/fakl3131",     "https://usewinter.com/lfmsr214"]}

- accountId - String. The accountId of the returned account

- document_type - Enum that represents which type of KYC document user has entered. Possible responses: PASSPORT, DRIVERS_LICENSE, STATE_LICENSE

- account_kyc_status - Enum that represents the status of withdrawal. Depends on KYC status. Possible responses: READY_TO_WITHDRAW, CANNOT_WITHDRAW_KYC_REQUIRED, CANNOT_WITHDRAW_KYC_FAILED, UNDER_REVIEW. If response is CANNOT_WITHDRAW_KYC_REQUIRED, that means user has not completed KYC yet.

- document_urls - Array of document URLs. Expect each URL to return an image (e.g. PNG/JPG)

Error Response#

Code : 400 BAD REQUEST

Condition : If accountId is invalid, if organization does not have access to this account(for security reasons), or if account does not have documents.

Submit KYC personal information#

Use this API to submit personal KYC information, such as address and SSN. We take security seriously at Winter and all data, including personal KYC information, will be encrypted

URL : /v1/kyc/info/<accountId>

Method : POST

Auth required : Yes (API key and secret are required)

Body payload#

Sample body payload:

{  "full_legal_name": "Michael Winter",  "full_address": "123 Main St, Chicago, IL 90874",  "social_security_number": "123-45-6789"}

- full_name - String. The full legal name of the owner of the returned account. This should match full_name of Account

- full_address - String. The full address of the owner of the account.

- social_security_number - String. The SSN of the user. This will encrypted.

Success Response#

Code : 200 OK

Error Response#

Code : 400 BAD REQUEST

Condition : If accountId is invalid, if organization does not have access to this account(for security reasons), or if base64 encoded document cannot be decoded

Uploading & submitting KYC documents#

URL : /v1/kyc_docs/<accountId>

Method : POST

Auth required : Yes (API key and secret are required)

Body payload#

Sample body payload:

{  "accountId": "12345",  "document_type": "DRIVERS_LICENSE",  "document_type": "FRONT",  "content":    "Ymxhcmdhc2Rma2xhanNkbGtmYWpzZGZhc2ZibGFyZ2FzZGZrbGFqc2Rsa2ZhanNkZmFzZmJsYXJnYXNkZmtsYWpzZGxrZmFqc2RmYXNmYmxhcmdhc2Rma2xhanNkbGtmYWpzZGZhc2ZibGFyZ2FzZGZrbGFqc2Rsa2ZhanNkZmFzZg=="}

- accountId - String. The accountId of the returned account

- document_type - Enum that represents which type of KYC document user has entered. Possible options: PASSPORT, DRIVERS_LICENSE, STATE_LICENSE

- document_side - Enum that represents which side of the document. Note this field is only valid for DRIVERS_LICENSE and STATE_LICENSE. Possible options: FRONT, BACK

- document - String. Base64 encoded image. Can only be jpg or png or the request will fail.

Success Response#

Code : 200 OK

Error Response#

Code : 400 BAD REQUEST

Condition : If accountId is invalid, if organization does not have access to this account(for security reasons), or if base64 encoded document cannot be decoded