Submit KYC

POST 
https://api.cleverhub.co/api/v2/contacts/submit_kyc

This API allows you to submit the necessary KYC documents for a specific contact. The KYC documents include the contact's identity proof (e.g., ID card, passport), a selfie, and relevant document images. You must provide the correct contact email.

Request

multipart/form-data

Body

emailstringrequired
The contact's email used for verification.
document_typestringrequired
The type of identification document (e.g., passport, id_card).
Possible values: [passport, id_card, driving_license]
document_numberstringrequired
The identification number on the document.
document_usernamestringrequired
The name as shown on the identification document.
issue_datestring
The issue date of the identification document in format 'yyyy-mm-dd'.
expiry_datestringrequired
The expiry date of the identification document in format 'yyyy-mm-dd'.
issue_countrystringrequired
The country that issued the identification document (ISO 3166-1 alpha-2).
nationalitystringrequired
The country of nationality of the contact (ISO 3166-1 alpha-2 code).
selfiebinaryrequired
A selfie image of the contact for identity verification should be in JPEG format.
id_doc_front_sidebinaryrequired
The front side image of the identification document should be in JPEG or PNG format.
id_doc_back_sidebinaryrequired
The back side image of the identification document should be in JPEG or PNG format.
webhook_notification object
Merchant Callback Details
endpoint_urlurl (endpoint_url)required
An internet accessible url which Hello Clever will invoke when the status of the transaction has changed. The call will be done using the HTTP POST method. The endpoint exposed by the client must be TLS 1.2 and the server certificate must be issued by a well known commercial certificate authority and that self-signed or internally signed certs are not acceptable.
Example: https://example.org
authorization_header(authorization_header)required
The string which Hello Clever will put into the Authorization request header when calling the Callback url.
Example: SECRET

Responses

200

KYC submission successful

application/json

Schema

Schema

statusstring

Example (auto)

{
  "status": "string"
}

Example

{
  "status": "Ok"
}

400

Bad Request

401

Unauthorized

application/json

Schema

Schema

errors object
codestring
messagestring

Example (auto)

{
  "errors": {
    "code": "string",
    "message": "string"
  }
}

Example

{
  "errors": {
    "code": "REQUIRE_LOGIN",
    "message": "Not Authorised"
  }
}

422

Unprocessable Entity

application/json

Schema

Schema

errors object
messagestring

Example (auto)

{
  "errors": {
    "message": "string"
  }
}

Example

{
  "errors": {
    "message": "Email can't be blank"
  }
}

Callbacks

POST KYCStatusChanged

POST 
{$request.body#/endpoint_url}

When the KYC status changes, Hello Clever will call the endpoint_url provided in the Submit KYC request. The call will be made using the HTTP POST method.

The notification will include detailed KYC information for the contact, including the updated status (pending, approved, failed), and other relevant details.

application/json

Bodyrequired

emailstring
Contact's email
first_namestring
Contact's first name
last_namestring
Contact's last name
typestring
The type of contact (e.g., individual or organization)
Possible values: [individual, organization]
Example: individual
dobstring
Contact date of birth format 'yyyy-mm-dd'
phonestring
Contact's phone
Example: +61-412345678
reg_nostring
Contact registration number.
genderstring
Contact's gender
Possible values: [male, female]
Example: male
streetstring
The primary name of an address's street.
citystring
Name of an address's city or town.
postal_codestring
The address's postcode
statestring
The address's state / province / county.
countrystring
ISO 3166-1 alpha-2 country code.
identity object
Contains the most recent KYC submission details for the contact.
issue_countrystring
ISO 3166-1 alpha-2 country code.
id_doc_typestring
Type of identification document
Possible values: [passport, id_card, driving_license]
document_numberstring
ID document number
issue_datestring
Format 'yyyy-mm-dd'
expiry_datestring
Format 'yyyy-mm-dd'
kyc_statuses object[]
An array of KYC statuses for the contact, containing multiple KYC instances with status and message.
Array [
kyc_statusstring
• pending: KYC process has been initiated for the contact, but the verification is not yet completed. The contact is still in the process of submitting the necessary documents.
• failed: contact was unable to verify the KYC documents due to invalid, incomplete, or unclear information. The contact may need to resubmit the documents.
• rejected: KYC has been rejected for future transactions due to failure in meeting the required verification criteria. The contact cannot proceed with any further transactions until the issue is resolved.
• manual_review: The KYC process is under review by the compliance team to approve or reject the documents. This status typically means that the submitted documents need further examination.
• blocked: Contact's KYC has been blocked, preventing future transactions until further resolution. The block may be due to suspicious activity or a need for additional verification.
• approved: Contact has successfully passed the KYC verification, and future transactions can proceed without issue. The contact's identity has been verified and is now compliant with the platform's standards.
Possible values: [pending, failed, rejected, manual_review, blocked, approved]
messagestring
Message related to the KYC status
]

Callbacks Responses

200

The merchant's server should return this code

Authorization: app-id

name: app-idtype: apiKeydescription: The app-id is registered and secured inside Hello Clever system and only required when client has initiated or in the middle of the transaction.in: header

name: secret-keytype: apiKeydescription: The secret-key is our client's secret of the source. Required if a publishable key is used to retrieve the source.in: header

• csharp
• curl
• dart
• go
• http
• java
• javascript
• kotlin
• c
• nodejs
• objective-c
• ocaml
• php
• powershell
• python
• r
• ruby
• rust
• shell
• swift

• HTTPCLIENT
• RESTSHARP

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.cleverhub.co/api/v2/contacts/submit_kyc");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("app-id", "<app-id>");
request.Headers.Add("secret-key", "<app-id>");
var content = new StringContent(string.Empty);
content.Headers.ContentType = new MediaTypeHeaderValue("multipart/form-data");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Request Collapse all

Base URL

https://api.cleverhub.co/api

Auth

app-id

secret-key

Body

emailrequired

document_typerequired

---passportid_carddriving_license

document_numberrequired

document_usernamerequired

issue_date

expiry_daterequired

issue_countryrequired

nationalityrequired

selfierequired

A selfie image of the contact for identity verification should be in `JPEG` format.

id_doc_front_siderequired

The front side image of the identification document should be in `JPEG` or `PNG` format.

id_doc_back_siderequired

The back side image of the identification document should be in `JPEG` or `PNG` format.

webhook_notificationrequired

ResponseClear

Click the Send API Request button above and see the response here!