Ask or search…
K

Rest API

The Smile Links API provides REST access to the no-code tool smile links on the portal. There are four endpoints to help you manage your Links programattically.
Available endpoints for creating, getting and updating links
  1. 1.
    Create Link: for creating a new smile link (single/multi-use)
  2. 2.
    Update Link: for updating or disabling a created link.
  3. 3.
    Get All Links: get all your Smile Links
  4. 4.
    Get specific Link: get a specific link using its ref-id/link-id
Getting Started
To get started with creating a Link, all you need is to specify a link type , ID object, and app customisatons. Read more about these concepts below:
Link Types
There are two types of Smile Links: Single Use and Multi-use (Learn more here). The boolean parameter for creating a single use link is 'is_single_use'.
The ID Object
A single Smile Link can support IDs. You can enable numerous ID types from different countries on a single link. For each ID type, only one verification method is supported.
JSON
"id_types": [ {
"country": "NG",
"id_type": "PASSPORT",
"verification_method":
"biometric_kyc"
}],
country: two letter country ISO country code eg 'US' of a supported country.
id_type: the specific ID you want to verify eg. Drivers License
verification_method: These are the products you want to support for each ID type. The 4 available products are:
biometric_kyc doc_verification enhanced_document_verification enhanced_kyc
Note: Only one verification method (Product) is supported per ID type.
Supported ID types and countries
For supported countries and ID types, you can use the docs or the valid_documents api (for global document verification) or the vv2/services api (for supported ids for biometric, enhanced document verification & enhanced_kyc). You can try these using the postman collection.
App / Link customisations
These are the details that appear on the hosted web application that your user will see.
Company Logo: The company or product logo you want the users to see on the verification interface. Data Privacy Policy Link: Adding your privacy policy to your user interface guarantees compliance with data and privacy regulations. The URL should link to your privacy or data policy webpage. Callback URL: add a callback URL where the JSON results will be posted. By default, we will post the results to the default callback URL you have set up in your Smile Dev Settings.
User ID: This is auto-generated. For single use links, you can use user id's in two ways:
  1. 1.
    Track existing user: Add an existing user ID to the request for single use link if you want to track the same user on Smile.
  2. 2.
    Track individual user: you can pass a new user id to track a specific user. ensure this is unique to each new user.

Endpoints

This endpoint allows you to create a smile link with the provided details.
Request Type: POST
Environment
URL
Sandbox
https://testapi.smileidentity.com/v1/smile_links
Production
https://api.smileidentity.com/v1/smile_links
Request Body
  • partner_id (string): The partner ID.
  • signature (string): The signature for authentication.
  • timestamp (string): The timestamp for the request.
  • name (string): The name associated with the smile link.
  • id_types (array): An array of objects containing the country, ID type, and verification method.
    • country (string): The country for the ID type.
    • id_type (string): The type of ID.
    • verification_method (string): The method used for verification.
  • callback_url (string, required):: The URL to which the callback response will be sent.
  • data_privacy_policy_url (string, required): The URL for the data privacy policy.
  • logo_url (string): The URL for the company logo. This must be a link to a valid png/image.
  • is_single_use (boolean): Indicates if the smile link is for single use.
  • user_id (string): the user id to track a user.
  • expires_at (<datetime>): The expiration date and time for the smile link.
Notes:
You must provide a valid CALLBACK callback_url (especially for enhanced KYC) to ensure your jobs don't fail.
Your LOGO logo_urlmust lead to a valid png, svg image. Ensure this url is publicly accessible
Sample JSON body
{
"partner_id": "",
"signature": "",
"timestamp": "",
"name": "My Link",
"id_types": [
{
"country": "NG",
"id_type": "PASSPORT",
"verification_method": "doc_verification"
},
],
"callback_url": "https://example.webhook.com",
"data_privacy_policy_url": "https://mywebsite.com/privacy_policy",
"logo_url": "https://mywebsite.com/logo.png",
"is_single_use": false,
"user_id": "",
"expires_at": "2024-02-29T16:13:40.813Z"
}
Response
  • link (string): The generated smile link.
  • ref_id (string): The reference ID associated with the smile link.
Sample response
{
"link": "<string>",
"ref_id": "<string>"
}

This endpoint allows updating a specific smile link identified by the linkId.
With this PUT endpoint, you can
  1. 1.
    Disable a link
  2. 2.
    update items in the ID types object
  3. 3.
    Add new ID types
Request Type: PUT
Environment
URL
Sandbox
https://testapi.smileidentity.com/v1/smile_links/:linkId
Production
https://api.smileidentity.com/v1/smile_links/:linkId
Request Path Variables
  • linkId (string, required): The ref_ID of the link you want to update
Request Body
  • partner_id (string, required): The ID of the partner.
  • signature (string, required): The signature for the request.
  • timestamp (string, required)): The timestamp of the request.
  • is_disabled (boolean): Indicates if the smile link is to be disabled. Set to true to disable the link
  • id_types (array): An array of objects containing country, ID type, and verification method.
Notes:
This is a PUT endpoint, the existing id_types object will be replaced with the new ID type you pass with this endpoint
Status Code: 200 Content Type: application/json
Sample JSON body
{
"partner_id": "",
"signature": "",
"timestamp": "",
"is_disabled": false,
"id_types": [
{
"country": "NG",
"id_type": "PASSPORT",
"verification_method": "doc_verification"
}
]
}
Response
  • disabled_at (string): The timestamp when the link was disabled.
  • id_types (array): An array of objects containing country, ID type, and verification method.
  • link_url (string): The URL of the smile link.
  • ref_id (string): The reference ID associated with the smile link.
Sample response
{
"disabled_at": null,
"id_types": [
{
"country": "NG",
"id_type": "PASSPORT",
"verification_method": "doc_verification"
}
],
"link_url": "https://links.usesmileid.com/...",
"ref_id": "c13...."
}

This API endpoint allows you to get a smile link with the provided linkId. (ref_id). It is similar to update endpoint but the request type this time is a POST.
Request Type: POST
Environment
URL
Sandbox
https://testapi.smileidentity.com/v1/smile_links/:linkId
Production
https://api.smileidentity.com/v1/smile_links/:linkId
Request Path Variables
  • linkId (string, required): The ref_ID of the link you want to update
Request Body
  • partner_id (string, required): The ID of the partner.
  • signature (string, required): The signature for the request.
  • timestamp (datetime, required)): The timestamp of the request.
Status Code: 200 Content Type: application/json
Sample JSON body
{
"partner_id": "",
"signature": "",
"timestamp": "",
}
Response
Upon successful execution, the API returns a JSON object with the following fields:
  • link_url (uri): The URL for the created smile link.
  • link_id (string): The ID of the smile link.
  • name (string): The name of the smile link.
  • id_types (array): An array of objects containing country, ID type, and verification method.
  • is_single_use (boolean): Indicates if the smile link is single-use.
  • callback_url (uri): The callback URL associated with the smile link.
  • data_privacy_policy_url (uri): The URL for the data privacy policy.
  • logo_url (string): The URL for the logo associated with the smile link.
  • user_id: The user id of the user for single user links.
  • total_jobs (float): The total number of jobs associated with the smile link.
  • failed_jobs (float): The number of failed jobs associated with the smile link.
  • successful_jobs (float): The number of successful jobs associated with the smile link.
  • company_name (string): The name of the company associated with the smile link.
  • partner_id (string): The partner ID associated with the smile link.
  • created_at (dateTime): The date and time of creation.
  • disabled_at (dateTime): The date and time when the smile link was disabled.
  • expires_at (dateTime): The expiration date and time of the smile link.
  • updated_at (dateTime): The date and time of the last update.
  • disabled_at (string): The timestamp when the link was disabled.
  • id_types (array): An array of objects containing country, ID type, and verification method.
  • link_url (string): The URL of the smile link.
  • ref_id (string): The reference ID associated with the smile link.
Sample response
{
"link_url": "<uri>",
"link_id": "<string>",
"name": "<string>",
"id_types": [
{
"country": "<string>",
"id_type": "<string>",
"verification_method": "biometric_kyc"
},
{
"country": "<string>",
"id_type": "<string>",
"verification_method": "doc_verification"
}
],
"is_single_use": "<boolean>",
"callback_url": "<uri>",
"data_privacy_policy_url": "<uri>",
"logo_url": "<string>",
"user_ids": [
"<uuid>",
"<uuid>"
],
"total_jobs": "<float>",
"failed_jobs": "<float>",
"successful_jobs": "<float>",
"company_name": "<string>",
"partner_id": "<string>",
"created_at": "<dateTime>",
"disabled_at": "<dateTime>",
"expires_at": "<dateTime>",
"updated_at": "<dateTime>"
}

This endpoint allows you to retrieve a list of smile links.
Request Type: POST
Environment
URL
Sandbox
https://testapi.smileidentity.com/v1/smile_links/:list
Production
https://api.smileidentity.com/v1/smile_links/:list

Request Path Variables

  • linkId (string, required): The reference of the link you want to update
Request Body
  • partner_id (string, required): The ID of the partner.
  • signature (string, required): The signature for the request.
  • timestamp (datetime, required)): The timestamp of the request.
  • page (number): the specific page number you want to visit. If you dont enter any number, you get the first page. For total pages, see the meta tag meta: {"totalPages":}
Status Code: 200 Content Type: application/json
Sample JSON body
{
"partner_id": "",
"signature": "",
"timestamp": "",
"page": 2
}
Response
Upon a successful execution, the server will respond with a status code of 200 and a JSON object containing an array of links, along with metadata including current page, limit, total count, and total pages.
Sample response
{
"links": [
{link_object},
{link_object},
...
],
"meta": {
"currentPage": 0,
"limit": 0,
"totalCount": 0,
"totalPages": 0
}
}

Postman Collection Find the samples here in this Postman Collection