Skip to content

Init

Request URL

POST /customer/kyc/init (deprecated)

Description

This endpoint is deprecated. Instead of using /customer/kyc and /document endpoints, we recommend the use of the /akepa endpoints for KYC/KYB verification and document upload.

This endpoint starts the KYC (Know Your Customer) process. This process uses various databases to verify a customer's identity. Once the process is over, expect a callback at your webhookURL endpoint.

A customer may or may not pass the KYC right away. In response to this request, the system will indicate if additional data or document images are required.

Required Properties Description Schema Example Values
customerId Customer ID in connectFi string "csta_6clNH3W2pBehujY8mpTCU8"
Optional Properties Description Schema Example Values
syncMode true if asyncronous, nullable boolean true
webhookURL URL which will be called after the KYC process initialization. If you specify a webhookURL in the /kyc/init request, the system will perform a callback to your webhookURL every time the KYC status changes. string "http://sample.com/something?asd=123"

Request Body

HEADERS

{
    "Content-Type": "application/json",
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

REQUEST BODY

{
    "customerId" : "csta-6TqoA6HtSItCANO1KT0W7u", //customer ID in connectFi
    "webhookURL": "http://sample.com/mywebhook?ref=123something" //optional URL which will be called after KYC process is over. 
}

Successful Response Example

200 (HTTP response status code) -- Success, KYC process has initialized

{
    "code": "0", //Success
    "data": {
        "customer": {
            "reference": "22223", //unique external reference in your system
            "customerId": "csta-6TqoA6HtSItCANO1KT0W7u", //customer ID in connectFi
            "customerType": "individual",
            "customer": {
                "businessAddresses": [],
                "businessPhones": [],
                "firstName": "John",
                "lastName": "Testman",
                "gender": "M",
                "dateOfBirth": "1978-10-15",
                "email": "aa@aa.aa",
                "citizenshipCountryCodeA3": "USA",
                "addresses": [ //address objects for the customer (individual)
                ],
                "phones": [ //phone objects for the customer (individual) 
                ],
                "identificationDocuments": [ //identificationDocument objects for the customer (individual)
                ]
            },
            "kycStatus": "WAITING_DATA",
            "boises": [],
            "dtsCreatedAt": "2022-10-07T17:18:56.424Z"
        },
        "kyc": {
            "attributeCodes": [ //array of strings mentioning required attributes
                "cardAttributes"
            ],
            "system": "condor", //backend system name.
            "mode": "licenseUSACondor", //KYC process mode
            "status": "WAITING_DATA" //see below
        },
        "kycDocumentList": [ //array of documents expected
            {
                "id": "doc-1qfdwf5KV66EBv0vVVdmTW",
                "label": "LICENSE FRONT",
                "type": "LICENSE",
                "documentSide": "FRONT",
                "uploadStatus": false
            },
            {
                "id": "doc-1qfdwgKNnog8UUyrx390cY",
                "label": "LICENSE BACK",
                "type": "LICENSE",
                "documentSide": "BACK",
                "uploadStatus": false
            }
        ]
    },
    "requestId": "3eb38da0b79811ed877e9cb46042ed12"
}

Errors

400 (HTTP response status code) -- Incorrect input data

If any required fields are missing, connectFi will indicate the missing fields. (The webhookURL field is optional.)

{
    "requestId": "28f3c700b85111ed94b4966a132cde12",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "",
            "schemaPath": "#/required",
            "keyword": "required",
            "params": {
                "missingProperty": "customerId"
            },
            "message": "must have required property 'customerId'"
        }
    ]
}

Notes on KYC initialization

System may respond with a list (array) of additional attributes required. Those will be listed in kyc.attributeCodes. For example, connectFi may require additional attributes for a card if the card is intended to be opened as part of the KYC procedure. In such a case kyc.attributeCodes will include cardAttributes.

Note that kyc.status and kycStatus may have the following values:

  • WAITING_DATA - Additional attributes or document images are expected
  • PENDING - KYC process has started and requires no additional input on your end
  • REVIEW - Customer is under manual review
  • APPROVED - Customer was approved
  • DECLINED - Customer was declined

The system may list documents required for upload in kycDocumentList:

  • id - connectFi ID for the document to be uploaded
  • label - "LICENSE FRONT", "LICENSE BACK", etc.
  • type - see below
  • documentSide - "FRONT", "BACK"
  • uploadStatus - Upload status. True if document has been uploaded.

Document types:

  • "PASSPORT" -- a copy of the front page of customer's passport
  • "LICENSE" -- front and back images of customer's driver license
  • "CONTRACT" -- a full PDF copy of a tenancy contract
  • "UTILITY" -- a copy of a utility bill
  • "ID_CARD" -- a government-issued ID document