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


---

# Agent Instructions: 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:

```
GET https://dev.vulos.io/reference/kyc-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.