Customer

This endpoint is used to manage individual and business customers.

Endpoint or Section	Action
/customer/init	Create an individual or business customer
/customer/status/:customerId	Get customer details
/customer/update	Update customer details
/customer/add-employee	Add an employee to a business customer
/customer/disable-employee	Disable an employee associated with a business customer
Common /customer Error Responses	Descriptions of possible error responses that are common to most /customer endpoints
Possible KYC/KYB Statuses	Possible customer KYC/KYB statuses when using the Akepa KYC/KYB process

The following endpoints are deprecated.

Endpoint or Section	Action
/customer/kyc/init	KYC (Know Your Customer) process initialization (deprecated)
/customer/kyc/add-attributes	Add additional attributes for the KYC process (deprecated)
/customer/kyc/upload/:customerId/:documentId	Upload documents for the KYC process (deprecated)
/customer/kyc/status/:customerId	Check on the KYC status (deprecated)
/customer/kyc/document-link	Link a document to a specific customer undergoing the KYC process (deprecated)
/card/list/:customerId	Get a list of cards for a specified customer
/account/list/:customerId	Get a list of accounts for a specified customer

Create Customer

Request method and URL

POST /customer/init

Description

This endpoint initializes the creation of an individual or business customer.

Creating a customer does not start a KYC/KYB (Know Your Customer/Business) process. It merely validates the data and registers a customer with connectFi.

The /customer/init endpoint supports idempotency and will not accept requests with duplicate reference IDs, SSN values (for individuals), or FEINs (for businesses). The SSN (for individuals)/FEIN (for businesses) included in the request body is how connectFi controls for duplicate customers. When initializing customers, do not reuse reference IDS, SSNs, or FEINs. Do not make more than one customer initialization request for a single individual or business. If customer details need to be updated after initialization, you must use the /customer/update endpoint.

There are two potential schema that will pass validation for the /customer/init endpoint. The first schema is for an individual customer and the second schema is for a business customer. The endpoint will check to make sure exactly one schema matches the given request. If neither schema passes validation, then the endpoint will return the issues that caused validation to fail (both for the individual customer schema and the business customer schema). Both schema are described below.

Individual Customer Schema

Required Properties for Individual Customers	Description	Schema	Example Values
customerReference	An external alphanumeric reference ID (1-32 characters) for the customer in your system	string, regex pattern "^[0-9a-zA-Z]+$"	"extIndCustId1234"
customerType	Type of customer	string	"individual"
customer	Details of the customer	object	See Customer Object - Customer Object for an Individual below

Business Customer Schema

Required Properties for Business Customers	Description	Schema	Example Values
customerReference	An external alphanumeric reference ID (1-32 characters) for the customer in your system	string, regex pattern "^[0-9a-zA-Z]+$"	"extBusCustId1234"
customerType	Type of customer	string	"business"
customer	Details of the customer	object	See Customer Object - Customer Object for a Business below
businessRepresentatives	Details of the businessRepresentative(s) will be included in an array of businessRepresentative objects. (See businessRepresentative Object below)	array	[ { //businessRepresentative 1 }, { //businessRepresentatives 2 }, ...]

Customer Object

The connectFi API represents customers by a JSON object. The object properties vary depending on whether the customer is individual or business as shown below.

Customer Object for an Individual

Required Properties	Description	Schema	Example Values
firstName	First (given) name of customer (1-50 characters, not to include <> symbols)	string	"John"
lastName	Last (family) name of customer (1-50 characters, not to include <> symbols)	string	"Doe"
gender	Customer's gender	string	"M" or "F"
dateOfBirth	Customer's date of birth in YYYY-MM-DD format	string, regex pattern "^\d{4}-\d{2}-\d{2}$"	"1978-10-15"
email	Customer email	string, regex pattern "^(.+)@(.+)$"	"aaaaa@someemail.aa"
addresses	Array of address objects, at least one required. (See Address Object below)	array	[{ //address object 1 }, { //address object 2 }, ...]
phones	Array of phone objects, at least one is required. (See Phone Object below)	array	[{ //phone object 1 }, { //phone object 2 }, ...]
citizenshipCountryCodeA3	Country in which customer has citizenship as a 3-letter country code, ISO 3166-1 alpha-3 format	string, regex pattern "^[A-Z]{3}$"	"USA"

Optional Properties	Description	Schema	Example Values
identificationDocuments	Array of identification document objects (see identificationDocument Object below)	array	[{//identification object 1}, {//identification object 2}, ...]

Customer Object for a Business

Required Properties	Description	Schema	Example Values
businessName	The name of the business (1-50 characters, not to include <> symbols)	string	"ABC123 Business Example Incorporated"
businessFederalEin	The federal EIN of the business, replace the #s with the appropriate string of digits (1-80 characters)	string	"#########"
businessAddresses	An array of address objects representing the business's addresses (See Address Object below)	array	[ { //businessAddress 1 }, { //businessAddress 2 }, ... ]
businessPhones	An array of phone objects representing the business's phone numbers (See Phone Object below)	array	[ { //businessPhone 1 }, { //businessPhone 2 }, ... ]

businessRepresentative Object

Required Properties	Description	Schema	Example Values
firstName	First (given) name of the business representative (1-50 characters, not to include <> symbols)	string	"John"
lastName	Last (family) name of the business representative (1-50 characters, not to include <> symbols)	string	"Doe"
gender	Business representative's gender	string	"M" or "F"
dateOfBirth	Business representative's date of birth in YYYY-MM-DD format	string, regex pattern "^\d{4}-\d{2}-\d{2}$"	"1978-10-15"
email	Business representative's email	string, regex pattern "^(.+)@(.+)$"	"aaaaa@someemail.aa"
addresses	Array of address objects, at least one required. (See Address Object below)	array	[{ //address object 1 }, { //address object 2 }, ...]
phones	Array of phone objects, at least one is required. (See Phone Object below)	array	[{ //phone object 1 }, { //phone object 2 }, ...]
citizenshipCountryCodeA3	Country in which the business representative has citizenship as a 3-letter country code, ISO 3166-1 alpha-3 format	string, regex pattern "^[A-Z]{3}$"	"USA"

Optional Properties	Description	Schema	Example Values
id	A unique entity ID (1-32 characters) for the business representative. If a unique ID is not provided for the business representative, then connectFi will generate a unique ID for the business representative entity.	string, regex pattern "^[0-9a-zA-Z_]+$"	"cstab_2hKNfiDbjg28YbJzYS21sS"
identificationDocuments	Array of identification document objects (see identificationDocument Object below)	array	[{//identification object 1}, {//identification object 2}, ...]
businessRepresentativeType	The type of business representative	string	"principal_owner" or "authorized_signer"

Address Object

Required Properties	Description	Schema	Example Values
type	Type of address	string	"PRIMARY" or "SECONDARY"
addressLine1	Address line 1 (1-50 characters, not to include <> symbols)	string	"123 Some Str."
city	Name of the address city (1-50 characters, not to include <> symbols)	string	"Mycityname"
stateCode	Two character state abbreviation code	string	"PA"
postalCode	Postal code, each # in the example should be replaced with a digit 0-9 (5-10 characters)	string, regex pattern ^[0-9a-zA-Z-]+$	"#####"
countryCodeA3	3-letter country code, ISO 3166-1 alpha-3 format	string	"USA"

Optional Properties	Description	Schema	Example Values
addressLine2	Address line 2 (0-50 characters, not to include <> symbols, nullable)	string	"Apt A123"

Phone Object

Required Properties	Description	Schema	Example Values
type	Type of phone number	string	"MOBILE", "LANDLINE", or "PRIMARY"
phoneNumber	Customer's 6 to 12 digit phone number, each # in the example should be replaced with a digit 0-9	string, regex pattern "^\d+$"	"##########"

Optional Properties	Description	Schema	Example Values
countryDialingCode	Customer's 1 to 4 digit country dialing code prefix	string, regex pattern "^\d+$"	"01"

identificationDocument Object

The format for this object depends on the type of document.

Optional Properties	Description	Schema	Example Values
type	The type of identification document	string	"SSN", "SIN", "NIN", "TIN", "PASSPORT", "DRIVING LICENSE", "CONSULAR", "VOTER", "MILITARY ID", or "GOVERNMENT ISSUED ID"
value	The identification number or value, each # in the example should be replaced with a digit or character. For a US SSN, this would be a 9 character string of digits, 0-9	string	"#########"
issuanceCountryCodeA3	3-letter country code, ISO 3166-1 alpha-3 format, nullable	string, regex pattern "^[A-Z]{3}$"	"USA"
issuanceRegion	The region in which the identification document was issued (0-50 characters, not to include <> symbols, nullable)	string	"PA"
expiryDate	The expiration date of the identification document, nullable	string, regex pattern "^\d{4}-\d{2}-\d{2}$"	"2029-12-28"

Key for identificationDocument Abbreviations

• 'SSN' - US SSN
• 'SIN' - Canada SIN
• 'NIN' - Other national ID
• 'TIN' - Taxpayer identification
• 'PASSPORT' - Any country, assume foreign
• 'DRIVING LICENSE' - For US only
• 'CONSULAR' - For foreign, consular ID
• 'VOTER' - US only, voter ID
• 'MILITARY ID' - Military ID, US only
• 'GOVERNMENT ISSUED ID' - Other Government-issued ID

Some examples of identificationDocument objects are:

"identificationDocuments": [

    {
        "type": "SSN",
        "value": "123456789",
        "issuanceCountryCodeA3": "USA"
    },
    {
        "type": "DRIVING LICENSE",
        "value": "PA1234567890123456", //driver license #
        "issuanceCountryCodeA3": "USA",
        "issuanceRegion": "PA",  
        "expiryDate": "2029-12-28"
    },
    {
        "type": "PASSPORT",
        "value": "123456789", //passport #
        "issuanceCountryCodeA3": "ARE",
        "issuanceRegion": "Dubai",  
        "expiryDate": "2029-12-28"
    }
]

Request headers

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

Request body example

The following is an example of customer initialization for an individual.

{
    "customerReference": "22223", //unique external reference ID in your system
    "customerType": "individual",
    "customer": { //customer object (example shown)
        "firstName": "John", 
        "lastName": "Testman",
        "gender": "M",  //"M" for male and "F" for female.
        "email": "aa@aa.aa",   
        "phones": [ //at least one phone number is required
            {
                "type": "MOBILE",   //"MOBILE", "LANDLINE"
                "countryDialingCode": "01",
                "phoneNumber": "4345156001"
            }
        ],
        "dateOfBirth": "1978-10-15",
        "citizenshipCountryCodeA3": "USA",  //ISO 3166-1 alpha-3 
        "addresses": [
            {
                "type": "PRIMARY", //"PRIMARY", "SECONDARY"
                "addressLine1": "123 Main Str.", 
                "addressLine2": "apt 7",  //optional
                "city": "Harrisburg",
                "stateCode": "PA", 
                "postalCode": "12345", //zip code
                "countryCodeA3": "USA" //ISO 3166-1 alpha-3
            }
        ],
        "identificationDocuments": [
            {
                "type": "SSN",
                "value": "123456789",
                "issuanceCountryCodeA3": "USA" //ISO 3166-1 alpha-3
            },
            {
                "type": "DRIVING LICENSE",
                "value": "PA1234567890123456", //driver license #
                "issuanceCountryCodeA3": "USA", //ISO 3166-1 alpha-3
                "issuanceRegion": "PA",  
                "expiryDate": "2029-12-28"
            }
        ]
    }
}

The following is an example of customer initialization for a business.

{
    "customerReference": "222232331756", //unique external reference ID in your system
    "customerType": "business",
    "customer": {
        "businessName": "ABC123 Inc.",
        "businessFederalEin": "123456789", //federal EIN for the business
        "businessPhones": [
            {
                "type": "PRIMARY",
                "countryDialingCode": "01",
                "phoneNumber": "1234567890"
            }
        ],
        "businessAddresses": [
            {
                "type": "PRIMARY",
                "addressLine1": "123 Main Str.",
                "addressLine2": "apt 7",
                "city": "Harrisburg",
                "stateCode": "PA",
                "postalCode": "12345",
                "countryCodeA3": "USA"
            }
        ]
    },
    "businessRepresentatives" : [
        {
            "firstName": "John",
            "lastName": "Testman",
            "gender": "M",
            "businessRepresentativeType" : "principal_owner",
            "email": "aa@aa.aa",
            "phones": [ //phone number objects where this business representative can be reached
                {
                    "type": "MOBILE",
                    "countryDialingCode": "01",
                    "phoneNumber": "1234567890"
                }
            ],
            "dateOfBirth": "1978-10-15",
            "citizenshipCountryCodeA3": "USA",
            "addresses": [ //addresses of the business representative
                {
                    "type": "PRIMARY",
                    "addressLine1": "123 Main Str.",
                    "addressLine2": "apt 7",
                    "city": "Harrisburg",
                    "stateCode": "PA",
                    "postalCode": "12345",
                    "countryCodeA3": "USA"
                }
            ],
            "identificationDocuments": [
                {
                    "type": "SSN",
                    "value": "123456789",
                    "issuanceCountryCodeA3": "USA"
                }
            ]
        }
    ]
}

Possible responses

200 (HTTP response status code) -- Success, individual customer was registered and a unique customerId was generated for the customer.

{
    "code": "0", //Success
    "data": {
        "reference": "22223233173922", //unique external reference in your system
        "customerId": "cstap_24fyE3mgTeGdy7hYlqC9j4", //customer ID in connectFi
        "customerType": "individual",
        "customer": {
            "firstName": "John",
            "lastName": "Testman",
            "gender": "M",
            "dateOfBirth": "1978-10-15",
            "email": "aa@aa.aa",
            "citizenshipCountryCodeA3": "USA",
            "addresses": [ //address objects for the individual customer
            ],
            "phones": [ //phone objects for the individual customer
            ],
            "identificationDocuments": [
                {
                    "type": "SSN",
                    "value": "123456789",
                    "issuanceCountryCodeA3": "USA"
                },
                {
                    "type": "DRIVING LICENSE",
                    "value": "PA1234567890123456",
                    "issuanceCountryCodeA3": "USA",
                    "issuanceRegion": "PA",
                    "expiryDate": "2029-12-28"
                }
            ]
        },
        "boises": [],
        "dtsCreatedAt": "2023-02-28T16:45:10.718Z"
    },
    "requestId": "43ef0800b78711ed877e9cb46042ed12"
}

200 (HTTP response status code) -- Success, business customer was registered and a unique customerId was generated for the customer.

{
    "code": "0", //Success
    "data": {
        "reference": "222232331756", //unique external reference in your system
        "customerId": "cstab_4oeFBBpTPk8rdy5oIhbTuW", //customer ID in connectFi
        "customerType": "business",
        "customer": {
            "businessName": "ABC123 Inc.",
            "businessFederalEin": "123456789",
            "businessAddresses": [ //address objects for the business
            ],
            "businessPhones": [ //phone objects for the business
            ]
        },
        "boises": [],
        "dtsCreatedAt": "2023-02-28T16:40:09.238Z",
        "businessRepresentatives": [
            {
                "id": "cstab_2hKNfiDbjg28YbJzYS21sS",
                "firstName": "John",
                "lastName": "Testman",
                "gender": "M",
                "dateOfBirth": "1978-10-15T00:00:00.000Z",
                "businessRepresentativeType": "principal_owner",
                "email": "aa@aa.aa",
                "citizenshipCountryCodeA3": "USA",
                "addresses": [ //address objects for the individual (business representative)
                ],
                "phones": [ //phone objects for the individual (business representative)
                ],
                "identificationDocuments": [ //identification document objects for the individual (business representative)
                ]
            }
        ],
        "employees": []
    },
    "requestId": "904030e0b78611ed877e9cb46042ed12"
}

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

The following is an example of a schema validation error. The "customerReference" field is a required property for both the individual customer schema and the business customer schema. The request used in this example was missing this field, so it failed both individual and business schema validation.

{
    "requestId": "e14e6cd03df111eeb9061ef221e933b0",
    "code": "requestValidateError", //data validation error
    "context": [
        { //This object explains why the request did not pass an individual customer schema
            "instancePath": "",
            "schemaPath": "#/oneOf/0/required", //the schema path for an individual customer
            "keyword": "required",
            "params": {
                "missingProperty": "customerReference" //the individual schema failed because it requires a customerReference field
            },
            "message": "must have required property 'customerReference'"
        },
        { //This object explains why the request did not pass a business customer schema
            "instancePath": "",
            "schemaPath": "#/oneOf/1/required", //the schema path for a business customer
            "keyword": "required",
            "params": {
                "missingProperty": "customerReference" //the business schema failed because it requires a customerReference field
            },
            "message": "must have required property 'customerReference'"
        },
        {
            "instancePath": "",
            "schemaPath": "#/oneOf",
            "keyword": "oneOf",
            "params": {
                "passingSchemas": null
            },
            "message": "must match exactly one schema in oneOf" //The request must match one of two available schemas (individual or business) and it failed each of these for the reasons listed above
        }
    ]
}

400 (HTTP response status code) -- Current Reference is already registered in the system

In this example, a request to register a customer was made using a customerReference ID (external reference from your system) that has already been registered (either to the same customer or a different customer).

{
    "requestId": "c0df0cc03df111eeb9061ef221e933b0",
    "code": "referenceExists", //duplicate reference error
    "context": {
        "reference": "222232331757",
        "entityId": "cstab_4oeFBBpTPk8rdy5oIhbTuW" //customer ID in connectFi
    },
    "message": "Reference already exists."
}

400 (HTTP response status code) -- Current customer already exists in the system

If a customer with the information referenced in the request body (same SSN for an individual customer or the same businessFederalEin for a business customer) already exists in the system and a request is made for the same customer with a different customerReference, connectFi will return:

{
    "requestId": "7d6030e03df211eeb9061ef221e933b0",
    "code": "customerExists", //An attempt was made to associate a new customerReference with an existing customer (duplicate)
    "context": {
        "cFiAggregatorId": "evolve",
        "customerId": "cstap_rcEofplVddLQntC58ouxq" //The customerId already associated with the existing customer
    },
    "message": "Customer exists."
}

Back to Top

Get Customer Information

Request method and URL

GET /customer/status/:customerId

Description

This API returns the data for a customer. The connectFi customerId is given as a path parameter in the request URL.

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, individual customer data was returned

{
    "code": "0", //Success
    "data": {
        "reference": "22223233173922", //unique external reference in your system
        "customerId": "cstap_24fyE3mgTeGdy7hYlqC9j4", //customer ID in connectFi
        "customerType": "individual",
        "customer": {
            "firstName": "John",
            "lastName": "Testman",
            "gender": "M",
            "dateOfBirth": "1978-10-15",
            "email": "aa@aa.aa",
            "citizenshipCountryCodeA3": "USA",
            "addresses": [ //address objects for the individual
            ],
            "phones": [ //phone objects for the individual
            ],
            "identificationDocuments": [ //identificationDocument objects for the individual
            ]
        },
        //"kycStatus": "WAITING_DATA", //kycStatus is present if the KYC/KYB process has been initialized through an /akepa/identification request
        "boises": [],
        "dtsCreatedAt": "2023-02-28T16:45:10.718Z"
    },
    "requestId": "cda9dc90b78811ed877e9cb46042ed12"
}

200 (HTTP response status code) -- Success, business customer data was returned

{
    "code": "0", //Success
    "data": {
        "reference": "222232331756", //unique external reference in your system
        "customerId": "cstab_4oeFBBpTPk8rdy5oIhbTuW", //customer ID in connectFi
        "customerType": "business",
        "customer": {
            "businessName": "ABC123 Inc.",
            "businessFederalEin": "123456789",
            "businessAddresses": [ //address objects for the business
            ],
            "businessPhones": [ //phone objects for the business
            ]
        },
        //"kycStatus": "WAITING_DATA", //kycStatus is present if the KYC/KYB process has been initialized through an /akepa/identification request, possible values are "WAITING_DATA", "PENDING", "REVIEW", "APPROVED", "DECLINED"
        "boises": [],
        "dtsCreatedAt": "2023-02-28T16:40:09.238Z",
        "businessRepresentatives": [
            {
                "id": "cstab_2hKNfiDbjg28YbJzYS21sS", //unique external ID for each business representative within the business customer
                "firstName": "John",
                "lastName": "Testman",
                "gender": "M",
                "dateOfBirth": "1978-10-15T00:00:00.000Z",
                "businessRepresentativeType": "principal_owner",
                "email": "aa@aa.aa",
                "citizenshipCountryCodeA3": "USA",
                "addresses": [ //address objects for the individual (business representative)
                ],
                "phones": [ //phone objects for the individual (business representative)
                ],
                "identificationDocuments": [] //identificationDocument objects for the individual (business representative)
            }
        ],
        "employees": [
            {
                "id": "cstap_76hNvfievGPIe2sch18whK", //unique external ID for each employee that has been added to the business customer
                "position": "Sales Representative"
            }
        ]
    },
    "requestId": "79376730b78911ed877e9cb46042ed12"
}

Back to Top

Update Customer Details

Request method and URL

POST /customer/update

Description

This endpoint can be used to update the following customer properties: email, addresses, phones, businessAddresses, and/or businessPhones.

The email, addresses, and phones properties are specific to individual customers, while the businessAddresses and businessPhones properties are specific to business customers. If the customer type is "individual", then fields other than email, addresses, and/or phones will cause an error indicating that an invalid field is present for the current customer type.

Similarly, if an individual customer property (email, addresses, or phones) is present in an update request for a business customer, it will likewise cause an invalid field error for the current customer type.

Required Properties	Description	Schema	Example Values
customerId	Customer ID in connectFi	string	"cstap_7qosrXEws9cpedzPs7df4m"
customer	Customer object	object	See customerUpdate Object below

customerUpdate Object

Individual Customers

Optional Properties	Description	Schema	Example Values
email	Individual customer email	string, regex pattern "^(.+)@(.+)$"	"aaaaa@someemail.aa"
addresses	Array of address objects for individual customers, at least one required. (See Address Object in the Create Customer section here)	array	[{ //address object 1 }, { //address object 2 }, ...]
phones	Array of phone objects for individual customers, at least one is required. (See Phone Object in the Create Customer section here)	array	[{ //phone object 1 }, { //phone object 2 }, ...]

Business Customers

Optional Properties	Description	Schema	Example Values
businessAddresses	An array of address objects representing a business customer's addresses (See Address Object in the Create Customer section here)	array	[ { //businessAddress 1 }, { //businessAddress 2 }, ... ]
businessPhones	An array of phone objects representing a business customer's phone numbers (See Phone Object in the Create Customer section here)	array	[ { //businessPhone 1 }, { //businessPhone 2 }, ... ]

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 an individual customer's details

{
    "customerId": "cstap_3KXMXZEsVcYkgF3ZNIBMxs", //customer ID in connectFi
    "customer": {
        "email": "aa@aa.bb", //Updated email address
        "addresses": [ //Updated array of address objects
            {
                "type": "PRIMARY",
                "addressLine1": "123 Main Str.", 
                "addressLine2": "apt 8",
                "city": "Harrisburg",
                "stateCode": "PA", 
                "postalCode": "12345",
                "countryCodeA3": "USA"
            }
        ],
        "phones": [ //Updated array of phone objects
            {
                "type": "MOBILE",
                "countryDialingCode": "01",
                "phoneNumber": "1234567890"
            },
            {
                "type": "PRIMARY",
                "countryDialingCode": "01",
                "phoneNumber": "1234567891"
            }
        ]
    }
}

Update a business customer's details

{
    "customerId": "cstab_P5TdmwzTruXiiXfYYzwBQ", //customer ID in connectFi
    "customer": {
        "businessAddresses": [ //Updated array of business address objects
            {
                "type": "PRIMARY",
                "addressLine1": "123 Main Str.", 
                "addressLine2": "apt 8",
                "city": "Harrisburg",
                "stateCode": "PA", 
                "postalCode": "12345",
                "countryCodeA3": "USA"
            }
        ],
        "businessPhones": [ //Updated array of business phone objects
            {
                "type": "MOBILE",
                "countryDialingCode": "01",
                "phoneNumber": "1234567890"
            },
            {
                "type": "PRIMARY",
                "countryDialingCode": "01",
                "phoneNumber": "1234567891"
            }
        ]
    }
}

Possible responses

200 (HTTP response status code) -- Success, the individual customer was updated

{
    "code": "0", //Success
    "data": {
        "reference": "22223233173923", //external reference ID
        "customerId": "cstap_3KXMXZEsVcYkgF3ZNIBMxs", //customer ID in connectFi
        "customerType": "individual",
        "customer": {
            "firstName": "John",
            "lastName": "Testman",
            "gender": "M",
            "dateOfBirth": "1978-10-15",
            "email": "aa@aa.bb",
            "citizenshipCountryCodeA3": "USA",
            "addresses": [
                {
                    "type": "PRIMARY",
                    "addressLine1": "123 Main Str.",
                    "addressLine2": "apt 8",
                    "city": "Harrisburg",
                    "countryCodeA3": "USA",
                    "postalCode": "12345",
                    "stateCode": "PA"
                }
            ],
            "phones": [
                {
                    "type": "MOBILE",
                    "phoneNumber": "1234567890",
                    "countryDialingCode": "01"
                },
                {
                    "type": "PRIMARY",
                    "countryDialingCode": "01",
                    "phoneNumber": "1234567891"
                }
            ],
            "identificationDocuments": [ //array of identificationDocument objects
            ]
        },
        "boises": [],
        "dtsCreatedAt": "2023-03-01T15:55:26.188Z"
    },
    "requestId": "aa904b60b84911ed94b4966a132cde12"
}

200 (HTTP response status code) -- Success, the business customer was updated

{
    "code": "0", //Success
    "data": {
        "reference": "222232331752", //external reference ID 
        "customerId": "cstab_5W37iGE1CUiw2l4XGSJENs", //customer ID in connectFi
        "customerType": "business",
        "customer": {
            "businessName": "ABC123 Inc.",
            "businessFederalEin": "823366413",
            "businessAddresses": [ //business address objects array after update
                {
                    "type": "PRIMARY",
                    "addressLine1": "123 Main Str.",
                    "addressLine2": "apt 8",
                    "city": "Harrisburg",
                    "countryCodeA3": "USA",
                    "postalCode": "12345",
                    "stateCode": "PA"
                }
            ],
            "businessPhones": [ //business phone objects array after update
                {
                    "type": "MOBILE",
                    "phoneNumber": "1234567890",
                    "countryDialingCode": "01"
                },
                {
                    "type": "PRIMARY",
                    "countryDialingCode": "01",
                    "phoneNumber": "1234567891"
                }
            ]
        },
        "boises": [],
        "dtsCreatedAt": "2023-02-28T21:49:22.787Z",
        "businessRepresentatives": [ //list of businessRepresentative objects
        ],
        "employees": [
            {
                "id": "cstap_76hNvfievGPIe2sch18whK",
                "position": "Sales Representative"
            }
        ]
    },
    "requestId": "e5b4f710b7b111ed94b4966a132cde12"
}

400 (HTTP response status code) -- Must not have additional properties

In this example, an attempt to update a property other than email, addresses, phones, businessAddresses, and/or businessPhones was made.

{
    "requestId": "28412790b84b11ed94b4966a132cde12",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "/customer",
            "schemaPath": "#/additionalProperties",
            "keyword": "additionalProperties",
            "params": {
                "additionalProperty": "reference"
            },
            "message": "must NOT have additional properties"
        }
    ]
}

400 (HTTP response status code) -- Must not have fewer than 1 item

In this example, an attempt was made to update an individual customer using an empty addresses array. If arrays for phones, addresses, businessPhones, or businessAddresses are included in the request, then they may not be empty.

{
    "requestId": "5e4c7380b84b11ed94b4966a132cde12",
    "code": "requestValidateError",
    "context": [
        {
            "instancePath": "/customer/addresses",
            "schemaPath": "#/minItems",
            "keyword": "minItems",
            "params": {
                "limit": 1
            },
            "message": "must NOT have fewer than 1 items"
        }
    ]
}

400 (HTTP response status code) -- KYC status must be empty or APPROVED

In this example, an attempt was made to update a customer who has an initialized KYC application, but does not yet have an "APPROVED" KYC status.

{
    "requestId": "f803041041b411ee9eac1ef221e8eb04",
    "code": "customerUpdateStatus",
    "context": {
        "customerId": "cstab_72RXXuohJrFw0oXw5nrktS",
        "kycStatus": "WAITING_DATA"
    },
    "message": "Customers can only be updated if KYC status is empty or APPROVED."
}

Back to Top

Add Business Customer Employee

Request method and URL

POST /customer/add-employee

Description

This endpoint can be used to add an employee to a business customer. The term "employee" refers to an individual entity who is employed by the business customer. The term "business representative" refers to an entity that is specifically designated as a principal owner or authorized signer for the business.

Before an individual can be added to a business as an employee, the potential employee must first exist in the connectFi system as an individual customer entity. Therefore, a /customer/init request with "customerType": "individual" and the potential employee's details in the Customer Object is a pre-requisite to making a /customer/add-employee request.

After adding the potential employee to the connectFi system using /customer/init, the individual customerId that is returned will be included as the "employeeId" in the /customer/add-employee request. The business customerId will be included as the "companyId" in the /customer/add-employee request.

Required Properties	Description	Schema	Example Values
companyId	Business customer ID in connectFi	string	"cstab_123abc456def0GPs7dhIj"
employeeId	Individual customer ID in connectFi	string	"cstap_7qosrXEws9cpedzPs7df4m"
position	The employee's position within the company (1-50 characters, not to include <> symbols)	string	"Sales representative"

Request headers

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

Request body example

{
    "companyId": "cstab_6DwNo4XuvUYb33vFyAklGE", //Business customer ID in connectFi
    "position": "Sales Representative", //The employee's position within the company
    "employeeId": "cstap_76hNvfievGPIe2sch18whK" //Individual customer ID of the employee in connectFi
}

Possible responses

200 (HTTP response status code) -- Success, the employee was added

{
    "code": "0", //Success
    "data": {
        "reference": "222232331833",
        "customerId": "cstab_6DwNo4XuvUYb33vFyAklGE", //Business customer ID in connectFi
        "customerType": "business",
        "employees": [
            {
                "id": "cstap_76hNvfievGPIe2sch18whK", //Individual customer ID of the employee in connectFi
                "position": "Sales Representative" //The employee's position within the company
            }
        ]
    },
    "requestId": "90e64460741111ee895756da8a865bf4"
}

400 (HTTP response status code) -- Customer type is not supported for this action

In this example, a request was made to add an employee to an individual customer. Employees can only be added to business customers.

{
    "requestId": "2b1b258074eb11ee809756da8a86797c",
    "code": "customerType",
    "context": {
        "customerId": "cstap_76hNvfievGPIe2sch18whK",
        "customerType": "individual"
    },
    "message": "Customer type is not supported for this action."
}

Back to Top

Disable Business Customer Employee

Request method and URL

POST /customer/disable-employee

Description

This endpoint can be used to disable an employee for a business customer. The term "employee" refers to an individual entity who is employed by the business customer. The term "business representative" refers to an entity that is specifically designated as a principal owner or authorized signer for the business. Business representatives cannot be disabled.

To check a business's employees, a request to /customer/status/:customerId may be made using the business customer ID as a path parameter. Any employees associated with a business customer are included in the "employees" array.

The individual customerId of the employee will be included as the "employeeId" in the /customer/disable-employee request. The business customerId will be included as the "companyId" in the /customer/disable-employee request.

New business cards and/or business accounts cannot be created for disabled employees. However, a disabled employee can still open new individual cards and/or accounts that are not associated with the business in which they have been disabled.

Required Properties	Description	Schema	Example Values
companyId	Business customer ID in connectFi	string	"cstab_123abc456def0GPs7dhIj"
employeeId	Individual customer ID in connectFi	string	"cstap_7qosrXEws9cpedzPs7df4m"

Request headers

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

Request body example

{
    "companyId": "cstab_6DwNo4XuvUYb33vFyAklGE", //Business customer ID in connectFi
    "employeeId": "cstap_76hNvfievGPIe2sch18whK" //Individual customer ID of the employee in connectFi
}

Possible responses

200 (HTTP response status code) -- Success, the employee was disabled

{
    "code": "0", //Success
    "data": {
        "reference": "222232331833",
        "customerId": "cstab_6DwNo4XuvUYb33vFyAklGE", //Business customer ID in connectFi
        "customerType": "business",
        "employees": [
            {
                "id": "cstap_76hNvfievGPIe2sch18whK", //Individual customer ID of the employee in connectFi
                "position": "Sales Representative", //The employee's position within the company
                "isDisabled": true
            }
        ]
    },
    "requestId": "90e64460741111ee895756da8a865bf4"
}

400 (HTTP response status code) -- Employee with customerId _____ not found for this business customer

In this example, a request was made to disable an employee. However, the employeId included in the request does not match any employee of the specified company.

{
    "requestId": "d7d1233074ee11ee809756da8a86797c",
    "code": "customerNotFound",
    "context": {
        "customerId": "cstap_76hNvfievGPIe2sch18whK2"
    },
    "message": "Employee with customerId: (cstap_76hNvfievGPIe2sch18whK2) was not found for this business customer."
}

Back to Top

Common /customer Error Responses

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

In this example, an invalid customerId was requested. No such connectFi customer exists. This is an error message common to endpoints that require a customerId either as a request body property or a path parameter.

{
    "requestId": "cc94d400b79111ed877e9cb46042ed12",
    "code": "customerNotFound",
    "context": {
        "customerId": "cstab_4oeFBBpTPk8rdy5oIhbTuW1"
    },
    "message": "Customer not found"
}

Back to Top

KYC Init (deprecated)

Request method and URL

POST /customer/kyc/init (deprecated)

Description

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 headers

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

Request body example

{
    "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. 
}

Possible responses

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"
}

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

Back to Top

KYC Add Attributes (deprecated)

Request method and URL

POST /customer/kyc/add-attributes (deprecated)

Description

This endpoint can be used if additional attributes were requested in the previous step.

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

Optional Properties	Description	Schema	Example Values
additionalAttributes	An object containing optional cardAttributes (if the customer intends to open a card)	object	{ cardAttributes: {//see cardAttributes Object below}}

cardAttributes Object

Required Properties	Description	Schema	Example Values
productID	Product ID of card which will specify what type of debit card is being issued (this could be a physical debit card or a virtual debit card.) The productID (also referred to as program_id) will be specific to your products that are offered through this endpoint.	string	"Virtual_Debit_Card"
nameOnCard	Full customer name that will appear on the card	string	"JESSIE U TESTMAN"
designId	An ID representing the design chosen for the card	string	"1"
addressType	Type of address	string	"PRIMARY" or "SECONDARY"
issueType	Description identifying issue category of card	string	"NEW", "REGISTRATION", "RE-ISSUE", "EXPIRED", or "DAMAGED"
additionalData	An object containing any additional properties that should be included	object	{ //additional properties }

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": "csta-6TqoA6HtSItCANO1KT0W7u", //customer ID in connectFi
    "additionalAttributes": {
        "cardAttributes": {
            "productID": "AWSM_API_Evolve_Test",
            "nameOnCard": "JOHN TESTMAN",
            "designId": "1",
            "addressType": "PRIMARY",
            "issueType": "NEW",
            "additionalData": {
                "designId": "1"
            }
        }
    }
}

Possible responses

200 (HTTP response status code) -- Success, additional attributes have been added

{
    "code": "0", //Success
    "data": {
        "customer": {
            "reference": "22223", //unique external reference in your system
            "customerId": "csta-6TqoA6HtSItCANO1KT0W7u", //customer ID in connectFi
            "customerType": "individual",
            "customer": { //customer object
            },
            "kycStatus": "WAITING_DATA",
            "boises": [],
            "dtsCreatedAt": "2022-10-07T17:18:56.424Z"
        },
        "kyc": {
            "attributeCodes": [
                "cardAttributes"
            ],
            "system": "condor",
            "mode": "licenseUSACondor",
            "status": "WAITING_DATA"  
        },
        "kycDocumentList": [ //a list of expected documents that the process is waiting on
            {
                "id": "doc-2WQXvO8xWi4lVgwbWVjo0w",
                "label": "LICENSE FRONT",
                "type": "LICENSE",
                "documentSide": "FRONT",
                "uploadStatus": false
            },
            {
                "id": "doc-2WQXvPNAoAdQeG47y3f1jy",
                "label": "LICENSE BACK",
                "type": "LICENSE",
                "documentSide": "BACK",
                "uploadStatus": false
            }
        ]
    },
    "kycAttributes" : { //confirmation that attributes were accepted
        "cardAttributes": {
            "productID": "AWSM_API_Evolve_Test",
            "nameOnCard": "JOHN TESTMAN",
            "designId": "1",
            "addressType": "PRIMARY",
            "issueType": "NEW",
            "additionalData": {
                "designId": "1"
            }
        }
    },
    "requestId": "5df80330b85111ed94b4966a132cde12"
}

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

If the "additionalAttributes" field is missing, an exception will be thrown.

{
    "code": "exception",
    "requestId": "10cbbc90b85211ed94b4966a132cde12"
}

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

If any required fields are missing, connectFi will indicate the missing fields.

{
    "requestId": "25e0ec40b85211ed94b4966a132cde12",
    "code": "requestValidateError", //data validation error
    "context": [  //may contain several items each mentioning a field missing
        {
            "instancePath": "",
            "schemaPath": "#/required",
            "keyword": "required",
            "params": {
                "missingProperty": "customerId"
            },
            "message": "must have required property 'customerId'"
        }
    ]
}

400 (HTTP response status code) -- KYC status is not "WAITING DATA"

In this example, a request to add additional attributes was made for a customer who already has an "APPROVED" KYC status, resulting in an error.

{
    "requestId": "6fae9720b91811ed94b4966a132cde12",
    "code": "statusNotWAITING_DATA",
    "message": "Need WAITING_DATA status"
}

Back to Top

KYC Upload Document (deprecated)

Request method and URL

POST /customer/kyc/upload/:customerId/:documentId (deprecated)

Description

This API can be used to upload documents to complete the KYC process, if required. There are two path parameters:

• customerId - Customer ID in connectFi
• documentId - Document ID in connectFi, can be found in data.kycDocumentList of the previous step

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

The system will respond with HTTP status 200 if the file was successfully accepted. Any consecutive uploads overwrite previous ones as long as the KYC process has not been completed.

The system will respond with HTTP status 400 if the given customerId or documentId were 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": {
        "customer": {
            "reference": "2222369478", //unique external reference in your system
            "customerId": "csta-YbQeg60v7orvQFIYA7gKU", //customer ID in connectFi
            "customerType": "individual",
            "customer": { //customer object
            },
            "kycStatus": "WAITING_DATA",
            "boises": [],
            "dtsCreatedAt": "2022-10-07T17:18:56.424Z"
        },
        "kyc": {
            "attributeCodes": [
                "cardAttributes"
            ],
            "system": "condor",
            "mode": "licenseUSACondor",
            "status": "WAITING_DATA"
        },
        "kycDocumentList": [
            {
                "id": "doc-45SKHDbSp1Imxr1hjGOmfW", //document ID in connectFi
                "label": "LICENSE FRONT",
                "type": "LICENSE",
                "documentSide": "FRONT",
                "uploadStatus": true, //uploadStatus changed to true to indicate successful upload of this document
                "extension": "png"
            },
            {
                "id": "doc-45SKHEQURjRQQQzcUOJZyY", //document ID in connectFi
                "label": "LICENSE BACK",
                "type": "LICENSE",
                "documentSide": "BACK",
                "uploadStatus": false
            }
        ],
        "kycAttributes": {
            "cardAttributes": {
                "productID": "AWSM_API_Evolve_Test",
                "nameOnCard": "JOHN TESTMAN UWUR",
                "designId": "1",
                "addressType": "PRIMARY",
                "issueType": "NEW",
                "additionalData": {
                    "designId": "1"
                }
            }
        }
    }
    "requestId": "82a158d0b91411ed94b4966a132cde12"
}

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

In this example, an invalid documentId was requested for a valid customer.

{
    "requestId": "86af86c0b85311ed94b4966a132cde12",
    "code": "documentNotFound",
    "message": "Document Not Found"
}

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

In this example, the file requested for upload was not found.

{
    "requestId": "74e51540b85311ed94b4966a132cde12",
    "code": "badRequest",
    "message": "Bad request. File not found"
}

Back to Top

Get KYC Status (deprecated)

Request method and URL

GET /customer/kyc/status/:customerId (deprecated)

Description

KYC (Know Your Customer) is an asynchronous process which takes time. Therefore you are expected to await for callbacks via webhook. However, you can query KYC process status using the following request. The connectFi customer ID is required 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, customer information (including KYC status, KYC document list, and KYC attributes) is returned

{
    "code": "0", //Success
    "data": {
        "customer": {
            "reference": "22223", //unique external reference in your system
            "customerId": "csta-6TqoA6HtSItCANO1KT0W7u", //customer ID in connectFi
            "customerType": "individual",
            "customer": { //customer object
            },
            "kycStatus": "WAITING_DATA",
            "boises": [],
            "dtsCreatedAt": "2022-10-07T17:18:56.424Z"
        },
        "kyc": {
            "attributeCodes": [
                "cardAttributes"
            ],
            "system": "condor",
            "mode": "licenseUSACondor",
            "status": "WAITING_DATA" //Status of the KYC process, see above. 
        },
        "kycDocumentList": [
            {
                "id": "doc-45SKHDbSp1Imxr1hjGOmfW", //document ID in connectFi
                "label": "LICENSE FRONT",
                "type": "LICENSE",
                "documentSide": "FRONT",
                "uploadStatus": true,
                "extension": "png"
            },
            {
                "id": "doc-45SKHEQURjRQQQzcUOJZyY", //document ID in connectFi
                "label": "LICENSE BACK",
                "type": "LICENSE",
                "documentSide": "BACK",
                "uploadStatus": false //Still waiting on the back of the driver's license to be uploaded so the KYC status is "WAITING DATA"
            }
        ]
    },
    "kycAttributes" : {
        "cardAttributes": {
            "productID": "AWSM_API_Evolve_Test",
            "nameOnCard": "JOHN TESTMAN UWUR",
            "designId": "1",
            "addressType": "PRIMARY",
            "issueType": "NEW",
            "additionalData": {
                "designId": "1"
            }
        }
    },
    "requestId": "b654cac0b85311ed94b4966a132cde12"
}

Back to Top

Link Document to Customer (deprecated)

Request method and URL

POST /customer/kyc/document-link (deprecated)

Description

This request can be used if a document file has been uploaded separately and needs to be associated with an existing customer document id. The /document/generate and /document/upload/:documentId requests are pre-requisites. After the separate document ID has been generated and a file has been uploaded for that document ID using these pre-requisite requests, then a request may be made to /customer/kyc/document-link to associate the newly generated and uploaded document with the existing customer document id.

If the existing customer document ID references a document that has already been uploaded, then making a document-link request will overwrite the existing file associated with that ID using the new, separately uploaded document. A document-link request can be successfully made, even if the customer's KYC status is already "APPROVED".

Required Properties	Description	Schema	Example Values
customerId	Customer ID in connectFi	string	"csta_2DrPdoqtfvsfLdBBvHDla"
documentId	Document ID linked to customer in connectFi (from the kycDocumentList returned from the /customer/kyc/init request)	string	"doc-LwKISlnb04sviMV1x82MM"
separateDocumentId	Separate document ID in connectFi (from the /document/generate request made when initializing a document not associated with a customer)	string	"sdoc-2M5GA6wYiyTXsQQPPMBaGY"

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" : "csta-YbQeg60v7orvQFIYA7gKU", //customer ID in connectFi
    "documentId" : "doc-45SKHDbSp1Imxr1hjGOmfW", //existing customer document ID (can be obtained using a /customer/kyc/status request)
    "separateDocumentId" : "sdoc_lnj0CHjHqUms6VgpFwU2Q" //separate document ID obtained using a /document/generate request
}

Possible responses

200 (HTTP response status code) -- Separate document was successfully linked to existing customer document id

{
    "code": "0", //Success
    "data": {
        "customer": {
            "reference": "2222369478", //unique external reference in your system
            "customerId": "csta-YbQeg60v7orvQFIYA7gKU", //customer ID in connectFi
            "customerType": "individual",
            "customer": { //customer object
            },
            "kycStatus": "WAITING_DATA",
            "boises": [],
            "dtsCreatedAt": "2022-10-07T17:18:56.424Z"
        },
        "kyc": {
            "attributeCodes": [
                "cardAttributes"
            ],
            "system": "condor",
            "mode": "licenseUSACondor",
            "status": "WAITING_DATA"
        },
        "kycDocumentList": [
            {
                "id": "doc-45SKHDbSp1Imxr1hjGOmfW", //existing customer document ID that was used in the request body
                "label": "LICENSE FRONT",
                "type": "LICENSE",
                "documentSide": "FRONT",
                "uploadStatus": true,
                "extension": "png"
            },
            {
                "id": "doc-45SKHEQURjRQQQzcUOJZyY",
                "label": "LICENSE BACK",
                "type": "LICENSE",
                "documentSide": "BACK",
                "uploadStatus": false
            }
        ],
        "kycAttributes": {
            "cardAttributes": {
                "productID": "AWSM_API_Evolve_Test",
                "nameOnCard": "JOHN TESTMAN UWUR",
                "designId": "1",
                "addressType": "PRIMARY",
                "issueType": "NEW",
                "additionalData": {
                    "designId": "1"
                }
            }
        }
    }
    "requestId": "5e687b70b85511ed94b4966a132cde12"
}

400 (HTTP response status code) -- Document not found (existing customer document)

In this example, a separate document ID has been generated using a /document/generate API request and the document file has been uploaded using a /document/upload/:documentId request. The customerId given was also valid. However, the existing customer document ID given was invalid. The existing customer document ID can be located by making a /customer/kyc/status request (it will be in data.kycDocumentList[document index].id in the KYC status response body).

{
    "requestId": "a3adca00b85511ed94b4966a132cde12",
    "code": "documentNotFound",
    "message": "Document sdoc_2ztSzf9y8Gc77tEA7f8UCK not found"
}

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

In this example, a separate document ID has not yet been generated using a /document/generate API request.

Note: This error will also be produced if a separate document ID has been generated, but has already been linked to an existing customer document. You cannot reuse the same separate document ID to make more than one document-link request if it has already been successfully linked.

{
    "requestId": "aea19770b85511ed94b4966a132cde12",
    "code": "documentNotFound",
    "message": "Document sdoc_2ztSzf9y8Gc77tEA7f8UCK1 not found"
}

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

In this example, a separate document ID was generated using a /document/generate API request, but the document file was not yet uploaded using a /document/upload/:documentId request.

{
    "requestId": "d51e0a00b85511ed94b4966a132cde12",
    "code": "documentNotUploaded",
    "message": "Document sdoc_6llmzUqpMNmIMM0fRUDmKK do not uploaded"
}

Back to Top

Get List of Cards (deprecated)

Request method and URL

GET /card/list/:customerId

Description

This endpoint returns a list of cards issued for the given customer.

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, array of cards returned

{
    "code": "0", //Success
    "data": {
        "cards": [ //array includes all cards issued for the customer
            {
                "id": "crda-cGlZwbpxTx6P3v39kZPqU", //id of the card in connectFi
                "cFiBoisId": "condor", //backend system which keeps the card information
                "customerId": "csta-3gVU1HabOU7phfGj6jWOvu", //customer ID in connectFi
                "cFiAccountIds": [ //array of ids of accounts linked to the card
                    "acca-6HZVIVmmKm4KQjd7XZdAF2"
                ]
            },
            {
                "id": "crda-7hVIUPmJSXYBCQC5Q0NSMo", //id of the card in connectFi
                "cFiBoisId": "condor", //backend system which keeps the card information
                "customerId": "csta-3gVU1HabOU7phfGj6jWOvu", //customer ID in connectFi
                "cFiAccountIds": [ //array of ids of accounts linked to the card
                    "acca-7j92ec6vyEMDTBRTRKSNlu"
                ]
            }
        ]
    },
    "requestId": "37b05e70b86011ed94b4966a132cde12"
}

200 (HTTP response status code) -- Success, customer has no cards

If the customer does not possess any cards, an empty array is returned for data.cards. An empty array with status code 200 is returned if no cards are possessed, regardless of whether the customer exists or not. If you receive an empty array for a customer who is expected to possess at least one card, check the requested customer ID to make sure the customer ID is correctly entered.

{
    "code": "0",
    "data": {
        "cards": []
    },
    "requestId": "37b05e70b86011ed94b4966a132cde12"
}

Back to Top

Get List of Accounts (deprecated)

Request method and URL

GET /account/list/:customerId

Description

This endpoint returns a list of accounts opened for the given customer.

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, customer accounts are returned

{
    "code": "0", //Success
    "data": {
        "accounts": [ //all accounts of the customer in connectFi
            {
                "id": "acca-6HZVIVmmKm4KQjd7XZdAF2", //id of the account in connectFi
                "cFiBoisId": "condor", //backend system which keeps the account
                "accountNumber": "12345678901234", //account number
                "customerId": "csta-3gVU1HabOU7phfGj6jWOvu", //customer ID in connectFi
                "cFiCardIds": [ //list of ids of cards linked to the account
                    "crda-cGlZwbpxTx6P3v39kZPqU"
                ],
                "routingParams": { //additional account parameters
                    "routingNumber": "123456789" //US ABA account routing number
                }
            },
            {
                "id": "acca-7j92ec6vyEMDTBRTRKSNlu", //id of the account in connectFi
                "cFiBoisId": "condor", //backend system which keeps the account
                "accountNumber": "12345678901234", //account number
                "customerId": "csta-3gVU1HabOU7phfGj6jWOvu", //customer ID in connectFi
                "cFiCardIds": [ //list of IDs of cards linked to the account
                    "crda-7hVIUPmJSXYBCQC5Q0NSMo"
                ],
                "routingParams": { //additional account parameters
                    "routingNumber": "123456789" //US ABA account routing number
                }
            }
        ]
    }
    "requestId": "dc411f60b86011ed94b4966a132cde12"
}

US accounts get routingParams.routingNumber attribute. Accounts opened in other jurisdictions may have other attributes.

200 (HTTP response status code) -- Success, customer has no accounts

If the customer does not possess any accounts, an empty array is returned for data.accounts. An empty array with status code 200 is returned if no accounts are possessed, regardless of whether the customer exists or not. If you receive an empty array for a customer who is expected to possess at least one account, check the requested customer ID to make sure the customer ID is correctly entered.

{
    "code": "0", //Success
    "data": {
        "accounts": []
    },
    "requestId": "dc411f60b86011ed94b4966a132cde12"
}

Back to Top