KYC/KYB Process Using /akepa

This endpoint is used to manage the KYC/KYB process for individual and business customers.

Endpoint or Section	Action
/akepa/identification	Initialize the KYC/KYB process for an individual or business customer
Possible KYC/KYB Statuses	Possible customer KYC/KYB statuses when using the Akepa KYC/KYB process
Testing KYC/KYB in the Sandbox	Describes specific property values that can be used to trigger desired KYC/KYB outcomes for testing
/akepa/status/:customerId	Get the KYC/KYB status and details for the specified customer
/akepa/document/generate	Generate a document ID (prerequisite to uploading a document file)
/akepa/document/upload/:documentId	Upload a document file (prerequisite to /akepa/update requests)
/akepa/update	Update the current KYC/KYB process with the required documents

KYC/KYB Initialization

Request method and URL

POST /akepa/identification

Description

This endpoint starts the KYC/KYB (Know Your Customer/Business) 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/KYB 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/KYB process initialization. If you specify a webhookURL in the /akepa/identification request, the system will perform a callback to your webhookURL every time the KYC status changes.	string	"http://sample.com/something?asd=123"

Request headers

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

Request body example

{
    "customerId" : "cstab_4oeFBBpTPk8rdy5oIhbTuW", //customer ID in connectFi
    "webhookURL": "http://sample.com/mywebhook?ref=123something" //optional URL which will be called after KYC/KYB status changes. 
}

Possible responses

200 (HTTP response status code) -- Success, KYC/KYB process has been initialized for an individual customer

{
    "code": "0", //Success
    "data": {
        "applicationId": "iapp_34rAt1UTohynboSN1hg2KS", //KYC/KYB application ID in connectFi
        "aggregatorId": "evolve",
        "customerId": "cstap_24fyE3mgTeGdy7hYlqC9j4", //customer ID in connectFi
        "status": "pending_step_up", //current KYC/KYB status
        "outcome": null, //no KYC result for this application yet
        "entityApplications": [
            {
                "entityId": "cstap_24fyE3mgTeGdy7hYlqC9j4",
                "isCustomer": true, //true because this entity is a customer (individual)
                "status": "pending_step_up",//waiting on required documents for the individual customer
                "outcome": null //no KYC result for the individual customer yet
            }
        ]
    },
    "requestId": "64e9e590b78f11ed877e9cb46042ed12"
}

200 (HTTP response status code) -- Success, KYC/KYB process has been initialized for a business customer

{
    "code": "0", //Success
    "data": {
        "applicationId": "iapp_5fGHGF3op27jUFOJ79owGS", //KYC/KYB application ID in connectFi
        "aggregatorId": "evolve",
        "customerId": "cstab_4oeFBBpTPk8rdy5oIhbTuW", //customer ID in connectFi
        "status": "pending_step_up", //current overall application status
        "outcome": null, //no final outcome yet for this customer. The business has been approved, but a final outcome is pending the approval of the associated business representative(s)
        "entityApplications": [
            {
                "entityId": "ExtBusRepId123", //unique business representative entity ID in your system (or generated by connectFi if none was provided)
                "isCustomer": false, //false because this individual is a business representative, not an individual customer
                "status": "pending_step_up", //waiting on required documents for the business representative entity
                "outcome": null //no outcome yet for the business representative entity
            },
            {
                "entityId": "cstab_4oeFBBpTPk8rdy5oIhbTuW", //customer ID in connectFi
                "isCustomer": true, //true because this entity is a customer (business)
                "status": "completed", //KYB status is completed for the business entity
                "outcome": "approved" //KYB result for the business entity is approved
            }
        ]
    },
    "requestId": "ac956940b79011ed877e9cb46042ed12"
}

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

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

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

400 (HTTP response status code) -- Duplicate entity IDs

In this example, the business customer was initialized with two business representatives possessing the same ID. The business representative IDs must be unique within the same business. This did not throw an error when making a request to /customer/init, but a business customer with multiple business representatives with the same ID will not be able to make a successful /akepa/identification request.

{
    "requestId": "cc623e30b78411ed877e9cb46042ed12",
    "code": "extAkepa",
    "subCode": 4091,
    "message": "Multiple entities cannot have the same external_entity_id."
}

Back to Top

Possible KYC/KYB Statuses

The following are potential status codes that may arise when the customer is verified using the Akepa KYC/KYB process.

The term "journey" in this section refers to the overall Akepa identification and verification process. The term "entity" in this section refers to a specific individual customer, business customer, or business representative. In order for the Akepa journey to resolve to an "Approved" status, each relevant entity must have an "approved" status.

If the customer is an individual, then the customerId and entityId in connectFi are identical and refer to the same person.

If the customer is a business, then the customerId refers to the business entity itself. Multiple entityIds may be associated with the business customerId and would refer to business representative entities associated with the business customer.

Possible Journey Statuses

Journey Status (status)	Description
"pending_step_up" or "pending_documents"	Document images are expected. To upload document images, use /akepa/document/generate in conjunction with /akepa/document/upload/:documentId. Once the expected document images have been uploaded, use /akepa/update to link them to the Akepa KYC/KYB verification application.
"waiting_review" or "pending_journey_application_review"	The verification application is under review. No further action is required at this time.
"running"	KYC/KYB process has started and requires no additional input on your end.
"data_request"	Additional data has been requested.
"completed"	The KYC/KYB verification process has resolved to either "Approved" or "Denied"

Possible Journey Outcomes

Journey Outcome (outcome)	Description
"Approved"	Customer was approved.
"Denied"	Customer was declined.
null	The verification process is pending for this journey and has not yet resolved.

Possible Entity Application Statuses

Entity Application Status (entityApplications.status)	Description
"pending_step_up" or "pending_documents"	Document images are expected. To upload document images, use /akepa/document/generate in conjunction with /akepa/document/upload/:documentId. Once the expected document images have been uploaded, use /akepa/update to link them to the Akepa KYC/KYB verification application.
"waiting_review"	The verification application is under review. No further action is required at this time.
"running"	The KYC/KYB verification process is currently processing for this entity
"completed"	The KYC/KYB verification process has resolved to "approved" or "denied" for this entity

Possible Entity Application Outcomes

Entity Application Outcome (entityApplications.outcome)	Description
"approved"	Customer was approved.
"denied"	Customer was declined.
null	The verification process for this specific entity is pending and has not yet resolved.

Customer Statuses Cross-Referenced to KYC/KYB Statuses

Customer kycStatus (/customer/status/:customerId)	Description	Corresponding KYC/KYB Journey status (/akepa/status/:customerId)
`WAITING_DATA`	Additional attributes or document images are expected. To upload documents or images, use /akepa/document/generate in conjunction with /akepa/document/upload/:documentId. Once the expected documents or images have been uploaded, use /akepa/update to link them to the customer's Akepa KYC/KYB verification application.	"data_request", "pending_documents", or "pending_step_up"
`WAITING_REVIEW`	The verification application is under review. No further action is required at this time.	"waiting_review" or "pending_journey_application_review"
`APPROVED`	Customer was approved.	"Approved"
`DECLINED`	Customer was declined.	"Denied"
`PENDING`	KYC/KYB process has started and requires no additional input on your end.	Any other akepa status

Back to Top

Testing KYC/KYB in the Sandbox

There are specific customer property values in the sandbox that will trigger set KYC/KYB outcomes. These values must be used when initializing the test customer with a /customer/init request, before sending an /akepa/identification request. Follow the given request workflow order in order to trigger the desired outcome.

For example, to trigger a "waiting_review" outcome for an individual customer, take the following request workflow steps as outlined in the table below:

Initialize an individual customer with the lastName: "WaitReview" with a /customer/init request.
Use the customerId issued in the /customer/init response to create a KYC application with an /akepa/identification request. At this point, the KYC status will be "pending_step_up".
Generate a documentId for the front of the individual customer's Driver's License using an /akepa/document/generate request. Do the same for the back of the individual customer's Driver's License.
Use the front documentId generated from the /akepa/document/generate request to upload the front Driver's License image with an /akepa/document/upload/:documentId request. Do the same for the back Driver's License image using the back documentId.
Make an /akepa/update request to attach the uploaded documents to the customer's KYC application. This will result in the desired "waiting_review" KYC outcome status.

You can test these outcomes using the following values:

Customer Type	Customer Property	Value	KYC Outcome	Request Workflow Order
individual	`lastName`	"Denied"	An individual customer last name of "Denied" will trigger a "Denied" KYC outcome	[`/customer/init`, `/akepa/identification`]
individual	`lastName`	"WaitReview"	An individual customer last name of "WaitReview" will trigger a "waiting_review" KYC outcome	[`/customer/init`, `/akepa/identification`, `/akepa/document/generate` for front of identification document, `/akepa/document/generate` for back of identification document, `/akepa/document/upload/:documentId` for front of identification document, `/akepa/document/upload/:documentId` for back of identification document, `/akepa/update`]
business	`businessRepresentative[#].lastName`	"Denied"	A business representative with a last name of "Denied" will trigger an overall "Denied" KYB outcome (even if the business entity itself passes KYB)	[`/customer/init`, `/akepa/identification`]
business	`businessRepresentative[#].lastName`	"WaitReview"	A business representative with a last name of "WaitReview" will trigger an overall "waiting_review" KYB outcome (even if the business entity itself passes KYB)	[`/customer/init`, `/akepa/identification`, `/akepa/document/generate` for front of business representative's identification document, `/akepa/document/generate` for back of business representative's identification document, `/akepa/document/upload/:documentId` for front of business representative's identification document, `/akepa/document/upload/:documentId` for back of business representative's identification document, `/akepa/update`]
business	`postalCode` for PRIMARY business address	"00000"	A business representative with a PRIMARY business address postalCode of "00000" will trigger an overall "waiting_review" KYB outcome (even if the business representative(s) pass KYB)	[`/customer/init`, `/akepa/identification`]

Back to Top

Get KYC/KYB Status

Request method and URL

GET /akepa/status/:customerId

Description

This endpoint will return the details of the KYC/KYB process for the requested customer. The connectFi customerId should be included as a path parameter.

Request headers

{
    "x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}

Request body None

Possible responses

200 (HTTP response status code) -- Success, the KYC/KYB process details are returned for the specified business customer

{
    "code": "0", //Success
    "data": {
        "applicationId": "iapp_16dsRlhQiylq1f4hktWqNc", //application ID in connectFi
        "aggregatorId": "amplifi",
        "customerId": "cstab_5UVqDyjl5n0XB4NZ3jBcHg", //customer ID in connectFi
        "status": "pending_step_up", //current overall application status
        "outcome": null, //final overall application outcome, null, "Approved", or "Denied"
        "entityApplications": [
            {
                "entityId": "ExtBusRepId123",
                "isCustomer": false,
                "status": "pending_step_up", //current entity KYC/KYB status
                "outcome": null //final overall entity outcome, null, "approved", or "denied"
            },
            {
                "entityId": "cstab_5UVqDyjl5n0XB4NZ3jBcHg",
                "isCustomer": true,
                "status": "completed", //current entity KYC/KYB status
                "outcome": "approved" //final overall entity outcome, null, "approved", or "denied"
            }
        ]
    },
    "requestId": "35c66360b84d11ed94b4966a132cde12"
}

200 (HTTP response status code) -- Success, the KYC/KYB process details are returned for the specified individual customer

{
    "code": "0",
    "data": {
        "applicationId": "iapp_5wdC2B35HnIm1We30x1cFI", //application ID in connectFi
        "aggregatorId": "amplifi",
        "customerId": "cstap_3KXMXZEsVcYkgF3ZNIBMxs", //customer ID in connectFi
        "status": "pending_step_up", //current overall application status
        "outcome": null, //final overall application outcome, null, "Approved", or "Denied"
        "entityApplications": [
            {
                "entityId": "cstap_3KXMXZEsVcYkgF3ZNIBMxs",
                "isCustomer": true,
                "status": "pending_step_up", //current entity KYC/KYB status
                "outcome": null //final overall entity outcome, null, "approved", or "denied"
            }
        ]
    },
    "requestId": "ba0fd3c0b84f11ed94b4966a132cde12"
}

400 (HTTP response status code) -- Identification not found

In this example, a KYC/KYB process has not been initialized for the specified customer. A request to /akepa/identification will need to be made in order to begin the KYC/KYB process.

{
    "requestId": "c10eeec0b84c11ed94b4966a132cde12",
    "code": "identificationNotFound",
    "context": {
        "customerId": "cstab_5UVqDyjl5n0XB4NZ3jBcHg"
    },
    "message": "Identification not found"
}

Back to Top

KYC/KYB Generate Document ID

Request method and URL

POST /akepa/document/generate

Description

This endpoint can be used to generate a document ID in preparation to upload a document file.

Required Properties	Description	Schema	Example Values
workflow	Is this document ID for a business document or for a personal document like a Driver's License?	string	"BUSINESS" or "PERSONAL"
name	Name for the document	string	"front"
extension	File extension	string	"jpg" or "png"
type	Type of document that will be associated with the generated document ID	string	"contract", "license", "passport", "utility", "other", "internal", "identification_card", "residence_permit", "canada_provincial_id", "indigenous_card", "paystub", "bank_statement", "w2", "1099", "1120", "1065", "t1", "t4"

Optional Properties	Description	Schema	Example Values
note	Description of the purpose of the document	string	"Front of DL for John Doe"
note_author_agent_email	Email address of the note author	string	"aa@aa.bb"

Request headers

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

Request body example

{
    "workflow": "BUSINESS", //or "PERSONAL"
    "name": "front", //name description for document
    "extension": "jpg", //file extension that will be associated with the returned document ID
    "type": "license" //type of document expected
}

Possible responses

200 (HTTP response status code) -- Success, the KYC/KYB process details are returned for the specified individual customer

{
    "code": "0", //Success
    "data": {
        "id": "doc_6ESuXsYo0J8cgjEWK5xFe2", //document ID in connectFi that was generated
        "aggregatorId": "amplifi",
        "uploadStatus": false, //initial value is false, will update to true once the document has been uploaded
        "workflow": "BUSINESS", //or "PERSONAL"
        "name": "front", //name description for document
        "extension": "jpg", //file extension that will be associated with the returned document ID
        "type": "license", //type of document expected
        "dtsCreatedAt": "2023-03-02T15:06:48.511Z"
    },
    "requestId": "dacadc60b90b11ed94b4966a132cde12"
}

400 (HTTP response status code) -- Extension not allowed

{
    "requestId": "777d2630b90c11ed94b4966a132cde12",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "/extension",
            "schemaPath": "#/properties/extension/enum",
            "keyword": "enum",
            "params": {
                "allowedValues": [
                    "jpg",
                    "png"
                ]
            },
            "message": "must be equal to one of the allowed values"
        }
    ]
}

400 (HTTP response status code) -- Required property missing

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

Back to Top

KYC/KYB Upload Document

Request method and URL

POST /akepa/document/upload/:documentId

Description

This endpoint can be used to upload a document file to be stored within the specified document entity. The documentId should be included as a path parameter and is obtained by first making a request to the /akepa/document/generate endpoint.

Use multipart/form-data mode to upload the file.

The system will respond with HTTP status 200 if the file was successfully accepted.

The system will respond with HTTP status 400 if the given documentId was not found.

Request headers

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

Request body File data will be passed using multipart/form-data mode.

Possible responses

200 (HTTP response status code) -- Success, document was uploaded

{
    "code": "0", //Success
    "data": {
        "id": "doc_6nUpgZJJXI0WAWhT1etoaK", //document ID in connectFi
        "aggregatorId": "amplifi",
        "uploadStatus": true, //successfully uploaded
        "workflow": "BUSINESS", //or "PERSONAL"
        "name": "front", //name description for document
        "extension": "jpg", //file extension that will be associated with the returned document ID
        "type": "license", //type of document
        "dtsCreatedAt": "2023-03-02T15:20:52.415Z"
    },
    "requestId": "d9ceb730b90d11ed94b4966a132cde12"
}

400 (HTTP response status code) -- Document already uploaded

{
    "requestId": "b13ef500b90d11ed94b4966a132cde12",
    "code": "extAkepa",
    "subCode": 4091,
    "message": "The specified document has already been uploaded."
}

400 (HTTP response status code) -- Document not found

{
    "requestId": "0f7b6860b90e11ed94b4966a132cde12",
    "code": "documentNotFound",
    "message": "Document doc_6nUpgZJJXI0WAWhT1etoaK1 not found"
}

Back to Top

KYC/KYB Update Document

Request method and URL

POST /akepa/update

Description

This endpoint can be used to update documents for entities (either individual customers or business representatives associated with a business customer) who are undergoing the KYC/KYB (Know Your Customer/Business) process.

Before making an /akepa/update request, you must first make a /akepa/document/generate request to generate a document ID for each document. Then, complete an /akepa/document/upload/:documentId request to upload the document file. Finally, make an /akepa/update request to join the uploaded document to the desired entity.

Required Properties	Description	Schema	Example Values
customerId	Customer ID in connectFi	string	"csta_6clNH3W2pBehujY8mpTCU8"

Optional Properties	Description	Schema	Example Values
documents	An array of document objects	array	See Document Object below

Document Object

Required Properties	Description	Schema	Example Values
entityId	The entity ID. This could be an individual customer ID in connectFi or a business representative ID	string	"ExtBusRepId123" or "cstab_2hKNfiDbjg28YbJzYS21sS"
documentId	The document ID in connectFi. This ID will be generated by making a request to /akepa/document/generate	string	"doc_7fdqI9X17TFQFxI33ZNiO6"
view	The document view	string	"front", "back", or "selfie"

Request headers

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

Request body examples

Update documents for an individual customer.

{
    "customerId" : "cstap_3KXMXZEsVcYkgF3ZNIBMxs", //customer ID in connectFi
    "documents": [
        {
            "entityId": "cstap_3KXMXZEsVcYkgF3ZNIBMxs", //entity ID in connectFi (same as customer since this is an individual customer)
            "documentId" : "doc_7fdqI9X17TFQFxI33ZNiO6", //document ID in connectFi, generated by an /akepa/document/generate request
            "view" : "front" //front side of the document (Driver's License in this example)
        },
        {
            "entityId": "cstap_3KXMXZEsVcYkgF3ZNIBMxs", //entity ID in connectFi (same as customer since this is an individual customer)
            "documentId" : "doc_7Jl5kNLvfvClB7BVogm5Vw", //document ID in connectFi, generated by an /akepa/document/generate request
            "view" : "back" //back side of the document (Driver's License in this example)
        }
    ]
}

Update documents for a business representative associated with a business customer.

{
    "customerId" : "cstab_6iaNRLqanalYZ18PUQmvu2", //customer ID in connectFi
    "documents": [
        {
            "entityId": "ExtBusRepId123", //entity ID in connectFi (this is the business representative since the customer is a business)
            "documentId" : "doc_7fdqI9X17TFQFxI33ZNiO6", //document ID in connectFi, generated by an /akepa/document/generate request
            "view" : "front" //front side of the document (Driver's License in this example)
        },
        {
            "entityId": "ExtBusRepId123", //entity ID in connectFi (this is the business representative since the customer is a business)
            "documentId" : "doc_7Jl5kNLvfvClB7BVogm5Vw", //document ID in connectFi, generated by an /akepa/document/generate request
            "view" : "back" //back side of the document (Driver's License in this example)
        }
    ]
}

Possible responses

200 (HTTP response status code) -- Success, the documents were updated for the individual customer

{
    "code": "0", //Success
    "data": {
        "applicationId": "iapp_5wdC2B35HnIm1We30x1cFI", //application ID in connectFi
        "aggregatorId": "amplifi",
        "customerId": "cstap_3KXMXZEsVcYkgF3ZNIBMxs", //customer ID in connectFi
        "status": "completed", //current overall application status
        "outcome": "Approved", //final overall application outcome, null, "Approved", or "Denied"
        "entityApplications": [
            {
                "entityId": "cstap_3KXMXZEsVcYkgF3ZNIBMxs", //entity ID in connectFi (also the customer in this case)
                "isCustomer": true,
                "status": "completed", //current entity KYC/KYB status
                "outcome": "approved" //final overall entity outcome, null, "approved", or "denied"
            }
        ]
    },
    "requestId": "f4352f40b86411ed94b4966a132cde12"
}

200 (HTTP response status code) -- Success, the documents were updated for the business representative

{
    "code": "0", //Success
    "data": {
        "applicationId": "iapp_6DRSElqm73K3Lcj1GfzAhc", //application ID in connectFi
        "aggregatorId": "amplifi",
        "customerId": "cstab_6iaNRLqanalYZ18PUQmvu2", //customer ID in connectFi
        "status": "completed", //current overall application status
        "outcome": "Approved", //final overall application outcome, null, "Approved", or "Denied"
        "entityApplications": [
            {
                "entityId": "cstab_6iaNRLqanalYZ18PUQmvu2", //customer ID in connectFi (the business customer in this case)
                "isCustomer": true,
                "status": "completed", //current entity KYC/KYB status
                "outcome": "approved" //final overall entity outcome, null, "approved", or "denied"
            },
            {
                "entityId": "ExtBusRepId123", //entity ID (a business representative in this case)
                "isCustomer": false,
                "status": "completed", //current entity KYC/KYB status
                "outcome": "approved" //final overall entity outcome, null, "approved", or "denied"
            }
        ]
    },
    "requestId": "59900570b86211ed94b4966a132cde12"
}

400 (HTTP response status code) -- Entity has status completed

In this example, a request was made to update the documents of an entity that already has a KYC/KYB status of completed.

{
    "requestId": "f951f770b8ea11ed94b4966a132cde12",
    "code": "statusApplicationEntity",
    "message": "Entity ExtBusRepId123 has status completed"
}

400 (HTTP response status code) -- Identification not found

In this example, a request was made to update the documents of an entity that has not yet begun the KYC/KYB process. A request to /akepa/identification must be made first to initialize the KYC/KYB process. Next, requests to /akepa/document/generate and /akepa/document/upload/:documentId must be made to first generate a document ID and then upload the document. Once these prerequisites have taken place, a request to /akepa/update may be made to update the specified entity with the uploaded documents.

{
    "requestId": "45256f60b8eb11ed94b4966a132cde12",
    "code": "identificationNotFound",
    "context": {
        "customerId": "cstab_1B2tsPiOvaqwmoLFvtY8cW"
    },
    "message": "Identification not found"
}

Back to Top