Sessions

An ordered sequence of steps that can be used to build conversational UIs (eg: product onboarding).

Create session

POST 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*	string	A unique identifier for your end-user.
client_id*	string	An identifier for your tenant app.
client_app_key*	string	Authorization key.
skill*	string	The skill you're implementing.

200: OK Session successfully started.

{
    // 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"
}

400: Bad Request

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

Submit step for session

POST https://api.finqware.com/v1/sessions/:id/steps

Submits data for a certain session step.

Path Parameters

Name	Type	Description
id*	string	The session id.

Request Body

Name	Type	Description
client_id*	string	An identifier for your tenant app.
nonce*	string	A temp key received from the previous step.
skill*	string	The skill you're implementing.
step*	string	The name of the step you're submitting data for.
data*	object	The payload for this specific step.

200: OK Step successfully submitted.

{
    // 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": {}
}

400: Bad Request

{
    "message": "Error message"
}