Submit KYC With Token

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

This API enables merchants to verify a contact’s identity seamlessly using Sumsub KYC solution. Instead of requiring contacts to upload identification documents and selfies directly, this API leverages a token-based approach. When a contact completes their KYC process through Sumsub interface, a unique verification token is generated. This token represents the validated identity data, eliminating the need for manual document handling. The merchant submits this token along with the contact’s email to finalize the verification process on the server. Additionally, this API allows for automated KYC status tracking through webhook notifications. Merchants can provide a callback URL and an authorization header to receive real-time updates whenever the KYC status changes, ensuring a smooth verification experience without requiring periodic checks. With this approach, merchants can enhance security, streamline identity verification, and provide contacts with a frictionless onboarding experience.

Request

application/json

Body

emailstringrequired
The contact's email used for verification.
tokenstringrequired
Usage Notes:
• You must call the Generate share token using Sumsub API first to obtain this token.
• This token is a unique identifier linking the contact to their KYC verification process.
• It is a required field and must be a valid token provided by Sumsub.
• The token is time-sensitive and may expire after a certain period if the KYC process is not completed.
• If the token is invalid or expired, the API will return an error.
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/share_token");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("app-id", "<app-id>");
request.Headers.Add("secret-key", "<app-id>");
var content = new StringContent("{\n  \"email\": \"string\",\n  \"token\": \"string\",\n  \"webhook_notification\": {\n    \"endpoint_url\": \"https://example.org\",\n    \"authorization_header\": \"SECRET\"\n  }\n}", null, "application/json");
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

• Example (from schema)
• Example

{
  "email": "string",
  "token": "string",
  "webhook_notification": {
    "endpoint_url": "https://example.org",
    "authorization_header": "SECRET"
  }
}

ResponseClear

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