# REST Endpoint Reference

Here you can find the description and guidance of how Actions can be validated by using AuthenticAction service Rest API. 

## Validate Session

<mark style="color:green;">`POST`</mark> `/v1/validate`

Validates the authenticated action. This request is usually made by the application backend to validate authenticity and correctness of the action requested by the client. A successful response specifies whether biometric and values were collected and matched and overall verification status of the Action.

This endpoing can also be used to enroll users to biometrics. Specify `enrollment: true` in the request body to use images captured during the session to create a biometric template assigned to the user.&#x20;

**Prerequisites:**

An organization has been set in the AuthenticAction Service and you have been provided with the `apiKey` (Organization API Key) to perform AuthenticAction validations.

A session for AuthenticAction was initiated by the client with the designated `ironvest-session-id`.&#x20;

{% code title="CURL Example:" overflow="wrap" %}

```xquery
curl 'https://<Validation Endpoint>/v1/validate'
-H 'Content-Type: application/json'
-H 'apikey: <apiKey>'
--data-raw $'{ "cid": "<Client ID>", "csid": "<User Session ID>", "uid": "<User ID>", "action": "<action name>", "additionalData": {"sessionData":[{"key": "amount", "value": 35, "synonyms": ["amount"]}, {"key": "payeeID", "value": 6, "synonyms": ["payeeList"]}, {"key": "accountNumber", "value": "66666666", "synonyms": ["account_number"]}, {"key": "notes", "value": "Wire transfer", "synonyms": ["notes"]}]}}'
--compressed
```

{% endcode %}

{% code title="CURL Example (Enrollment):" overflow="wrap" %}

```xquery
curl 'https://<Validation Endpoint>/v1/validate'
-H 'Content-Type: application/json'
-H 'apikey: <apiKey>'
--data-raw $'{ "cid": "<Client ID>", "csid": "<User Session ID>", "uid": "<User ID>", "action": "<action name>", enrollment: true, "additionalData": {}'
--compressed
```

{% endcode %}

{% code title="CURL Example (with mTLS enabled endpoint)" overflow="wrap" %}

```xquery
curl -X POST —cert <path_to_the_certificate> —key <path_to_the_certificate_private_key> 'https://<Validation Endpoint>/v1/validate'
-H 'Content-Type: application/json'
-H 'apikey: <apiKey>'
--data-raw $'{ "cid": "<Client ID>", "csid": "<User Session ID>", "uid": "<User ID>", "action": "<action name>", "additionalData": {"sessionData":[{"key": "amount", "value": 35, "synonyms": ["amount"]}, {"key": "payeeID", "value": 6, "synonyms": ["payeeList"]}, {"key": "accountNumber", "value": "66666666", "synonyms": ["account_number"]}, {"key": "notes", "value": "Wire transfer", "synonyms": ["notes"]}]}}'
--compressed
```

{% endcode %}

#### Headers

| Name                                     | Type   | Description           |
| ---------------------------------------- | ------ | --------------------- |
| apiKey<mark style="color:red;">\*</mark> | string | Authentication token. |

#### Request Body

<table><thead><tr><th width="270">Name</th><th width="104">Type</th><th>Description</th></tr></thead><tbody><tr><td>cid<mark style="color:red;">*</mark></td><td>String</td><td>Customer ID</td></tr><tr><td>csid<mark style="color:red;">*</mark></td><td>String</td><td>Customer Session ID</td></tr><tr><td>uid<mark style="color:red;">*</mark></td><td>String</td><td>User ID</td></tr><tr><td>action</td><td>String</td><td>Action name. Meaningful name for validation and presentation purposes.</td></tr><tr><td>additionalData<mark style="color:red;">*</mark></td><td>Json</td><td><p>Activity related data. Example:</p><p><code>{</code></p><p>  <code>"sessionData":[{</code></p><p>    <code>"key":"amount",</code></p><p>    <code>"value":50,</code></p><p>    <code>"synonyms":["total"]}]</code></p><p><code>}</code></p></td></tr><tr><td>additionalData:sessionData<mark style="color:red;">*</mark></td><td>Json list</td><td>List of form fields values, can be empty</td></tr><tr><td>enrollment</td><td>Bool</td><td>In case an active enrollment to biometrics is enforced, this flag indicates that the validate request is made in context of the enrollment and if the session is successful the user will be marked as enrolled.</td></tr></tbody></table>

{% hint style="info" %}
The value specified in sessionData can be either string or decimal number. The value matching is agnostic to the type of the value used.
{% endhint %}

#### Response

{% tabs %}
{% tab title="200 Success" %}
{% code title="The request was successfully processed.  The results details are specified in the response body." overflow="wrap" %}

```json
{
    "success": true,
    "verifiedAction": false,
    "indicators": {
        "iv_is_values_collected": true,
        "iv_is_values_match": true,
        "iv_values_match_details": {},
        "iv_is_biometrics_collected": false,
        "iv_is_biometrics_match": false,
        "iv_liveness": false,
        "iv_policy_violations": {
            "violations": [],
            "has_violations": false,
            "total_frames": 0,
            "verified_frames": 0
        },
        "iv_biometrics_info": [],
        "iv_user_enrolled": false,
        "idv_matching": false,
        "driverLicenseCollected": false,
        "idlive_liveness": false,
        "regular_liveness": false
    },
    "ivScore": 2000
}
```

{% endcode %}
{% endtab %}

{% tab title="200 Application level error" %}
{% code title="Error message in response indicates application level error" %}

```json
{
  "errorMessage": "string"
}
```

{% endcode %}
{% endtab %}

{% tab title="503: Service Unavailable" %}

```
{
    "success": false,
    "error": "relevant error message"
}
```

{% endtab %}

{% tab title="403: Forbidden CID and API Key mismatch" %}

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid format of the request body" %}

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Successful response contains the following details:

`verifiedAction` - boolean, designates the overall verification status

`indicators` - object containing detailed validation information:

* `iv_is_values_collected` - boolean, indicates if form field values were collected
* `iv_is_values_match` - boolean, indicates if collected form field values matched expected values
* `iv_values_match_details` - object, contains detailed information about value matching results
* `iv_is_biometrics_collected` - boolean, indicates if biometric data was collected
* `iv_is_biometrics_match` - boolean, indicates if collected biometric data matched
* `iv_liveness` - boolean, indicates if liveness detection passed
* `iv_policy_violations` - object containing policy violation details:
  * `violations` - array of specific violations detected
  * `has_violations` - boolean indicating if any violations were found
  * `total_frames` - number of total frames analyzed
  * `verified_frames` - number of frames that passed verification
* `iv_biometrics_info` - array containing biometric collection information
* `iv_user_enrolled` - boolean, indicates if user was actively enrolled in the system
* `idv_matching` - boolean, indicates if identity document verification matching occurred
* `driverLicenseCollected` - boolean, indicates if driver's license data was collected
* `idlive_liveness` - boolean, indicates if ID liveness check passed
* `regular_liveness` - boolean, indicates if standard liveness check passed

`ivScore` - numeric score representing the overall identity verification confidence level
{% endhint %}

{% hint style="info" %}
One of the possible values for errorMassgae is "processing", indicating that data received during the activity has not been fully processed yet. If an optional "retryAfterMS" period is specified, a subsequent request should be issued after waiting for the specified period of time for higher probability of a final response.

```json
{
  "errorMessage": "processing",
  "retryAfterMS": 50
}
```

{% endhint %}


---

# 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://docsjs.ironvest.com/ironvest-authenticaction-developer-documentation/service-components/rest-endpoint-reference.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.