OTP Functionality

Sending the Code

Handshake

POST /otp/handshake

Request:

Field	Required	Type	Description
type	✅	string	OTP type specified in challenge_type
mobilePhone	If email is not specified	string	Phone number
email	If mobilePhone is not specified	string	Email
entities	❌	array	Array of related entities. For example: client: 123, lead: 5
entities.*.type	✅	string	Entity type: client, lead, loanApp etc
entities.*.id	✅	string	Entity identifier

Response:

{
  "status": "ok",
  "timestamp": 1657524075000,
  "data": {
    "type": "", // OTP type name
    "channel": "sms", // Channel that will be used to send the code
    "availableIn": 120 // OTP process lifetime
  }
}

Initialization

POST otp/init

Request:

Field	Required	Type	Description
type	✅	string	OTP type specified in challenge_type
mobilePhone	If email is not specified	string	Phone number
email	If mobilePhone is not specified	string	Email
entities	❌	array	Array of related entities. For example: client: 123, lead: 5
entities.*.type	✅	string	Entity type: client, lead, loanApp etc
entities.*.id	✅	string	Entity identifier

Response:

{
  "status": "ok",
  "timestamp": 1657524169000,
  "data": {
    "uuid": "", // OTP process identifier
    "channel": "sms" // Code delivery channel
  }
}

Code Confirmation

API

PUT otp/{uuid}/attempt

• uuid → OTP process identifier received during initialization

Request:

Field	Required	Type	Description
code	✅	string	Code for verification

Response:

{
  "status": "ok",
  "timestamp": 1657524358000,
  "data": {
    "accepted": true
  }
}

Search

GET|POST otp/{type}, where type - OTP Type

Request:

Field	Required	Type	Description
type	✅	string	OTP type specified in challenge_type
mobilePhone	❌	string	Phone number
email	❌	string	Email
entities	❌	array	Array of related entities. For example: client: 123, lead: 5
entities.*.type	✅	string	Entity type: client, lead, loanApp etc
entities.*.id	✅	string	Entity identifier

Response:

{
  "status": "ok",
  "timestamp": 1686816422000,
  "data": [
    {
      "id": 50,
      "uuid": "98df8e4e-7240-4291-9322-282a8d97542a",
      "type": "email-verification",
      "status": "accepted",
      "phone": null,
      "email": "email@example.com",
      "ip": null,
      "entities": [
        {
          "type": "client",
          "id": "338"
        },
        {
          "type": "process",
          "id": "13513451345-sdnfsfgnsfgn-13135"
        }
      ],
      "attempts": 0,
      "createdAt": "2023-04-07T08:22:06+00:00",
      "updatedAt": "2023-04-07T08:22:06+00:00",
      "currentRoute": {
        "status": "sent",
        "channel": "email",
        "templateId": "34",
        "attempts": 0
      }
    }
  ]
}

OTP Type Settings

Multiple OTP types can be configured for a tenant

Challenge Types

Available parameters:

• Name
• Code type:
  • numeric - digits only
  • alphanumeric - digits and uppercase Latin letters
  • alphabetic - uppercase Latin letters
• Code length
• OTP process lifetime
• Maximum number of code entry attempts, regardless of delivery method

CRUD

Endpoint api/otp/crud/challenge-types

Request:

Field	Required	Type	Description
name	✅	string	Name
code_type	❌	string	Generated code type. (numeric, alphanumeric, alphabetic). Default: numeric
code_length	❌	int	Code length. Default: 6
ttl	❌	int	OTP code lifetime. Specified in seconds. Default: 3600
max_attempts	❌	int	Maximum number of attempts. Default: 5

Challenge Type Routes

Different code delivery methods can be configured for each OTP type:

Available parameters:

• Delivery channel - (sms, email)
• Template ID - Code in template can be obtained via variable ${answer}
• Delivery method order
• Number of code entry attempts for this delivery type

CRUD

Endpoint api/otp/crud/challenge-types-routes

Request:

Field	Required	Type	Description
challenge_type_id	✅	int	Challenge ID
order	❌	int	Channel sending order
channel	✅	string	Delivery channel. (sms, email)
template_id	✅	int	Template ID for the selected channel
attempts	❌	int	Maximum number of attempts. Default: 1

Request Rate Limits

Rule	Per Minute	Per Hour	Per Day
OTP Type + contact (email or phone)	6	18	24