> For the complete documentation index, see [llms.txt](https://dev.vulos.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev.vulos.io/reference/kyc-api.md).

# KYC API

{% hint style="success" %}
If you use the [JavaScript SDK](/reference/identity-javascript-sdk.md) you could use the [`KycApi`](/reference/identity-javascript-sdk/the-base-package/kyc/kycapi.md) abstraction instead.
{% endhint %}

{% hint style="warning" %}
You need the [`kyc:read`](/identity/scopes-and-claims.md#kyc) scope to access this endpoints.
{% endhint %}

## KYC Instance Status

<mark style="color:blue;">`GET`</mark> `https://identity.vulos.io/api/v1/kyc/:id`

Get the status of a KYC verification instance.

#### Path Parameters

| Name                                 | Type   | Description                              |
| ------------------------------------ | ------ | ---------------------------------------- |
| id<mark style="color:red;">\*</mark> | String | The ID of the KYC verification instance. |

#### Headers

| Name                                            | Type   | Description                                                                                                         |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Basic authentication with the application client ID as the username and the client secret (if any) as the password. |

{% tabs %}
{% tab title="400: Bad Request Empty body" %}

```javascript
```

{% endtab %}

{% tab title="404: Not Found Empty body" %}

```javascript
```

{% endtab %}

{% tab title="200: OK The status of the KYC instance" %}

```javascript
{
    "complete": true,
    "success": false,
    "distance": 0.90,
    "createdAt": "Date string that can be parsed by the JS Date constructor",
    "completedAt": "Date string that can be parsed by the JS Date constructor",
    "webhook": null // or URL string
}
```

{% endtab %}
{% endtabs %}

## KYC Instance List

<mark style="color:blue;">`GET`</mark> `https://identity.vulos.io/api/v1/kyc/list`

List the KYC verification instances that were created by the application's owner.

#### Query Parameters

| Name     | Type   | Description                                        |
| -------- | ------ | -------------------------------------------------- |
| page     | Number | The page number (defaults to 0).                   |
| pageSize | Number | The number of instances per page (defaults to 10). |

#### Headers

| Name                                            | Type   | Description                                                                                                         |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Basic authentication with the application client ID as the username and the client secret (if any) as the password. |

{% tabs %}
{% tab title="400: Bad Request Empty body" %}

```javascript
```

{% endtab %}

{% tab title="200: OK The IDs of the KYC instances" %}

```javascript
["19208495-11e2-41b4-a80d-ba69cc3e1d50"]
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
You need the [`kyc:write`](/identity/scopes-and-claims.md#kyc) scope to access this endpoints.
{% endhint %}

## KYC File Upload

<mark style="color:green;">`POST`</mark> `https://identity.vulos.io/api/v1/kyc/upload`

Upload KYC verification files for future use.

#### Headers

| Name                                            | Type   | Description                                                                                                         |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | String | `multipart/form-data`                                                                                               |
| Authorization<mark style="color:red;">\*</mark> | String | Basic authentication with the application client ID as the username and the client secret (if any) as the password. |

#### Request Body

| Name                                            | Type | Description                      |
| ----------------------------------------------- | ---- | -------------------------------- |
| selfiePicture<mark style="color:red;">\*</mark> | File | The selfie picture of the user.  |
| idCardPicture<mark style="color:red;">\*</mark> | File | The id card picture of the user. |

{% tabs %}
{% tab title="400: Bad Request Empty body" %}

```javascript
```

{% endtab %}

{% tab title="200: OK The reference URIs" %}

```javascript
{
    "idCardPictureUrl": "URL",
    "selfiePictureUrl": "URL"
}
```

{% endtab %}
{% endtabs %}

## KYC Instance Create

<mark style="color:green;">`POST`</mark> `https://identity.vulos.io/api/v1/kyc/create`

Create a KYC verification instance.

#### Headers

| Name                                            | Type   | Description                                                                                                         |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | String | `multipart/form-data`                                                                                               |
| Authorization<mark style="color:red;">\*</mark> | String | Basic authentication with the application client ID as the username and the client secret (if any) as the password. |

#### Request Body

| Name             | Type   | Description                                                                                                                                                                       |
| ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| selfiePicture    | File   | The selfie picture of the user (required if no URL is specified).                                                                                                                 |
| idCardPicture    | File   | The id card picture of the user (required if no URL is specified).                                                                                                                |
| selfiePictureUrl | String | An URI returned by the upload endpoint.                                                                                                                                           |
| idCardPictureUrl | String | An URI returned by the upload endpoint.                                                                                                                                           |
| webhook          | String | A webhook that gets called when the KYC verification completes (the same data is sent that the status endpoint returns, minus the webhook field and with an additional id field). |

{% tabs %}
{% tab title="200: OK The ID of the KYC verification instance" %}

```javascript
"19208495-11e2-41b4-a80d-ba69cc3e1d50"
```

{% endtab %}

{% tab title="400: Bad Request No body" %}

```javascript
```

{% endtab %}
{% endtabs %}