> For the complete documentation index, see [llms.txt](https://docs.finqware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.finqware.com/api/sessions.md).

# Sessions

## Create session

<mark style="color:green;">`POST`</mark> `https://api.finqware.com/v1/sessions`

Initializes an on-boarding session for a specified skill.

The **tenant\_user\_id** may be any string that uniquely identifies an end-user using your tenant app (eg: uuid, opaque string, etc).

#### Request Body

| Name                                               | Type   | Description                            |
| -------------------------------------------------- | ------ | -------------------------------------- |
| tenant\_user\_id<mark style="color:red;">\*</mark> | string | A unique identifier for your end-user. |
| client\_id<mark style="color:red;">\*</mark>       | string | An identifier for your tenant app.     |
| client\_app\_key<mark style="color:red;">\*</mark> | string | Authorization key.                     |
| skill<mark style="color:red;">\*</mark>            | string | The skill you're implementing.         |

{% tabs %}
{% tab title="200: OK Session successfully started." %}

```javascript
{
    // The nonce is a temporary key that should be used when submitting data for the next step in this session.
    "nonce": "MDAxNmxvY2F0a...z0sBtsOyVdJ04kK",
    "session_id": "58f92378-...-20a052aca460",
    "status": "SESSION_CREATED"
}
```

{% endtab %}

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

```javascript
// check the errors docs page for details
{
  "id": "uuid",
  "type": "invalid_request",
  "http": 400,
  "code": "invalid_client_id",
  "message": "error message"
}
```

{% endtab %}
{% endtabs %}

## Submit step for session

<mark style="color:green;">`POST`</mark> `https://api.finqware.com/v1/sessions/:id/steps`

Submits data for a certain session step.

#### Path Parameters

| Name                                 | Type   | Description     |
| ------------------------------------ | ------ | --------------- |
| id<mark style="color:red;">\*</mark> | string | The session id. |

#### Request Body

| Name                                         | Type   | Description                                      |
| -------------------------------------------- | ------ | ------------------------------------------------ |
| client\_id<mark style="color:red;">\*</mark> | string | An identifier for your tenant app.               |
| nonce<mark style="color:red;">\*</mark>      | string | A temp key received from the previous step.      |
| skill<mark style="color:red;">\*</mark>      | string | The skill you're implementing.                   |
| step<mark style="color:red;">\*</mark>       | string | The name of the step you're submitting data for. |
| data<mark style="color:red;">\*</mark>       | object | The payload for this specific step.              |

{% tabs %}
{% tab title="200: OK Step successfully submitted." %}

```javascript
{
    // use the step_id if you require to submit more information to this particular step (eg: a file upload)
    "step_id": "58f92378-...-20a052aca460",
    // Use the newly generated nonce to submit data for the next step within the current session.
    "nonce": "MDAxNmxvY2F0a...z0sBtsOyVdJ04kK",
    "status": "SESSION_IN_PROGRESS",
    "data": {}
}
```

{% endtab %}

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

```javascript
{
    "message": "Error message"
}
```

{% endtab %}
{% endtabs %}