LogoLogo
  • Welcome!
  • GETTING STARTED
    • Signing Up
    • Choose a Product
    • Choose an Integration Option
    • Run Your First Test Job
    • Complete Your KYC
    • Fund Your Wallet
    • Go Live!
    • Pricing
  • SUPPORTED ID TYPES & DOCUMENTS
    • For Individuals (KYC)
      • Using ID Number
        • Supported Countries
          • Côte d'Ivoire
            • National ID (without Photo)
            • Resident ID (without Photo)
          • Ghana
            • Ghana Card
            • Ghana Card (without Photo)
            • Passport
            • Voter's ID
          • Kenya
            • Alien Card
            • KRA Pin
            • National ID
            • National ID (without Photo)
            • Passport
            • Tax Information
          • Nigeria
            • Bank Account
            • BVN
            • NIN V2
            • NIN Slip Verification
            • V_NIN (Virtual NIN)
            • Phone Number
            • Voter's ID
          • South Africa
            • National ID
            • National ID (without Photo)
            • Phone Number
            • Refugee and Asylum ID
          • Uganda
            • National ID (without Photo)
            • Basic KYC in Uganda
          • Zambia
            • Bank Account
            • TPIN
          • Zimbabwe
            • National ID (without Photo)
        • Test Data
          • Customising Sandbox Test Data
        • ID Number Regex
        • Visual Samples of Supported ID Types
      • Using Document Image
        • Continents
          • Africa
          • Asia and the Middle East
          • Europe
          • North America
          • Oceania
          • South America
    • For Businesses (KYB)
      • Supported Countries
        • Nigeria
          • Business Registration
          • Tax Information
        • Kenya
          • Business Registration
        • South Africa
          • Business Registration
      • ID Number Regex
  • PRODUCTS
    • For Individuals (KYC)
      • AML Check
        • AML News Media
      • Basic KYC
      • Biometric KYC
      • Digital Address Verification
      • Document Verification
        • Document Verification
        • Enhanced Document Verification
      • Electronic Signature
      • Enhanced KYC
      • Phone Number Verification
      • SmartSelfie™ Authentication
      • SmartSelfie™ Compare
      • Smile Secure
    • For Businesses (KYB)
      • Business Verification
  • Integration Options
    • Mobile
      • Getting Started
      • Products
        • Biometric KYC
        • BVN Consent
        • Document Verification
        • Enhanced Document Verification
        • Enhanced KYC
        • SmartSelfie™ Enrollment and Authentication
        • Enhanced SmartSelfie™ Enrollment And Authentication
      • Customization
        • UI Components
      • Offline Mode
      • Release Notes
        • Android Release Notes
        • iOS Release Notes
        • Flutter Release Notes
        • React Native Release Notes
    • No-Code
      • Smile Links
        • Link FAQs
        • Rest API
    • Server to Server
      • Ruby
        • Installation
        • Signature
        • Products
          • Basic KYC
          • Enhanced KYC
          • Biometric KYC
          • Document Verification
          • SmartSelfie™ Authentication
          • KYB - Business Verification
          • AML Check
        • Generate Token for Web Integration
        • Utilities
      • Python
        • Installation
        • Signature
        • Products
          • Basic KYC
          • Enhanced KYC
          • Biometric KYC
          • Document Verification
          • SmartSelfie™ Authentication
          • Business Verification
        • Generate Token for Web Integration
        • Utilities
      • Java
        • Release Notes
        • Installation
        • Signature
        • Products
          • Basic KYC
          • Enhanced KYC
          • Biometric KYC
          • Document Verification
          • SmartSelfie™ Authentication
        • Generate Token for Web Integration
        • Utilities
      • Node.js
        • Installation
        • Signature
        • Products
          • Basic KYC
          • Enhanced KYC
          • Biometric KYC
          • Document Verification
          • Enhanced Document Verification
          • SmartSelfie™ Authentication
          • Business Verification
        • Generate Token for Web Integration
        • Utilities
      • PHP
        • Installation
        • Signature
        • Products
          • Basic KYC
          • Enhanced KYC
          • Biometric KYC
          • Document Verification
          • SmartSelfie™ Authentication
        • Generate Token for Web Integration
        • Utilities
    • Rest API
      • Signing your API Request
        • Using Signature
      • Products
      • Postman Collection
      • Utilities
    • Web / Mobile Web
      • Web Integration
        • Installation
        • Usage
        • End User Consent
        • Support
      • Javascript SDK
        • Installation
        • Usage
        • Migration
        • Deprecated Version
          • Installation
          • Usage
          • Notes
          • Support
  • FURTHER READING
    • FAQs
      • What are your support hours?
      • How do I set up a callback?
      • How to re-enroll, deactivate or delete a user?
      • Add or remove team members
      • What are top-level keys?
      • What are partner_params?
      • How do job types map to the new product names?
      • Is there an API I can use to monitor my wallet balance?
      • Is there an API I can query to check the availability status of an ID type?
      • How do I integrate Smile ID in other countries or query other ID types?
      • What are the image types I can upload to Smile ID?
      • Why aren't Kenyan IDs returning images for some IDs queried?
      • Why are some of my bank verification requests returning 'ID authority unavailable'?
      • How can I look up a specific user's data?
      • Selfie best-practices
      • Document capture best-practices
      • What happens under the hood?
      • Guide to the user consent screen
      • What is code 2302?
      • Using the Demo App and Scanning QR codes
    • Job status
    • KYC receipts
    • Result codes
      • Error codes
    • Securing your account with two-factor authentication (2FA)
    • Security Overview
    • Troubleshooting
      • Troubleshooting error 2204 & 2205 - "You're not authorized to do that"
      • Why is my Web API job taking so long?
      • Image capture issues on web client
Powered by GitBook
On this page
  • Using the Smile Links APIs
  • Endpoints
  • Create a Smile Link
  • Updating a Smile Link
  • Getting a specific Smile Link
  • Getting all your Smile Links

Was this helpful?

  1. Integration Options
  2. No-Code
  3. Smile Links

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.

PreviousLink FAQsNextServer to Server

Last updated 1 month ago

Was this helpful?

Using the Smile Links APIs

Available endpoints for creating, getting and updating links

  1. : for creating a new smile link (single/multi-use)

  2. : for updating or disabling a created link.

  3. : get all your Smile Links

  4. : 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 (). 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

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. 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. 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

  1. Disable a link

  2. update items in the ID types object

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

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

For supported countries and ID types, you can use the 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 Find the samples here in this

docs
postman collection
Postman Collection
Learn more here
Create Link
Update Link
Get All Links
Get specific Link
Page cover image