> For the complete documentation index, see [llms.txt](https://legacy-docs.usesmileid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://legacy-docs.usesmileid.com/integration-options/no-code/smile-links/rest-api.md).

# Rest API

### Using the Smile Links APIs

**Available endpoints for creating, getting and updating links**

1. [Create Link](#create-a-smile-link): for creating a new smile link (single/multi-use)
2. [Update Link](#updating-a-smile-link): for updating or disabling a created link.
3. [Get All Links](#getting-all-your-smile-links): get all your Smile Links
4. [Get specific Link](#getting-a-specific-smile-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](https://docs.usesmileid.com/integration-options/no-code/smile-links#types-of-links)). 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

```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](https://docs.usesmileid.com/supported-id-types/for-individuals-kyc) or the `valid_documents` api (for global *document verification*) or the v`v2/services` api (for supported ids for *biometric, enhanced document verification & enhanced\_kyc*). You can try these using the [postman collection](https://api.postman.com/collections/2581147-0dc4ac24-1074-4bc4-b305-35dbe2b45c96?access_key=PMAT-01GXTSBAZ3ECNW0RQ06KD0MGQK).

**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`

<table><thead><tr><th width="335">Environment</th><th>URL</th></tr></thead><tbody><tr><td>Sandbox</td><td>https://testapi.smileidentity.com/v1/smile_links</td></tr><tr><td>Production</td><td>https://api.smileidentity.com/v1/smile_links</td></tr><tr><td></td><td></td></tr></tbody></table>

**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_url`must lead to a valid png, svg image. Ensure this url is publicly accessible

**Sample JSON body**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
	"links": [
		{link_object},
		 {link_object},
		 ...
	],
	"meta": {
	"currentPage": 0,
	"limit": 0,
	"totalCount": 0,
	"totalPages": 0
	}
}
```

***

Postman Collection\
Find the samples here in this [Postman Collection](https://api.postman.com/collections/2581147-0dc4ac24-1074-4bc4-b305-35dbe2b45c96?access_key=PMAT-01GXTSBAZ3ECNW0RQ06KD0MGQK)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://legacy-docs.usesmileid.com/integration-options/no-code/smile-links/rest-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.