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.

Using the Smile Links APIs

Available endpoints for creating, getting and updating links

Create Link: for creating a new smile link (single/multi-use)
Update Link: for updating or disabling a created link.
Get All Links: get all your Smile Links
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:

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.
Track individual user: you can pass a new user id to track a specific user. ensure this is unique to each new user.\

Endpoints

Create a Smile Link

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.
company_name (string, required):: Your partner name.
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.
partner_params (object): A JSON object containing the partner parameters (user_id, job_id) as well as any additional key value pairs you wish to include for tracking which will be returned in the response. Note that all details sent in partner params should be wrapped as strings.
redirect_url (string): The URL you wish to redirect to after submission. After redirect, the user_id and the status will be available as query parameters. status returned will be one of successful, fail or cancelled.

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",
  "company_name": "My Company Name",
  "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": "",
  "partner_params": {
    "is_paying": "true",
    "customer branch": "country x"
  },
  "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>"
}

Redirecting Smile Links to your Application

This allows you to provide a link to your application where Smile Links redirects after a user submits or cancels a verification.

Sample Request for redirect

{
  "partner_id": "",
  "signature": "",
  "timestamp": "",
  "name": "My Link",
  "company_name": "My Company Name",
  "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",
  "redirect_url": "https://example.com/redirect",
  "is_single_use": false,
  "partner_params": {
    "user_id": "user-1",
    "is_paying": "true"
  },
  "expires_at": "2024-02-29T16:13:40.813Z"
}

Sample Redirects

Status

Redirect params

Successful submission

https://example.com/redirect?status=success&user_id=user-1

Cancelled submission

https://example.com/redirect?status=cancelled&user_id=user-1

Failed submission

https://example.com/redirect?status=fail&user_id=user-1

Updating a Smile Link

This endpoint allows updating a specific smile link identified by the linkId.

With this PUT endpoint, you can

Disable a link
update items in the ID types object
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...."
}

Getting a specific Smile Link

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.
redirect_url (string): The redirect url associated with the link.
partner_params (object): The partner parameters provided.

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>",
  "redirect_url": "<string>",
  "partner_params": "<object>"
}

Getting all your Smile Links

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

PreviousLink FAQs NextServer to Server

Last updated 17 days ago

Was this helpful?