Authenticate

number

mandatory

The destination telephone number

The destination telephone number can be in E164 format (with + sign or 00 prefix or without). In case the country code is not present then the API will check the “country” provided and format the number accordingly.

applicationId

optional

The applicationId of the application you would like to use

If you have provisioned a specific setup for an application, you can include the UUID in this parameter and the settings and language templates for this application will be used. If not specified the “default” application will be used.

Via

optional

Possible values AUTO SMS VOICE

You can force a delivery channel by using this parameter. The default is “AUTO” which will use SMS in case of mobile number and VOICE in case of landline.

language

optional

String

The local language should be in ISO 639-1 format https://en.wikipedia.org/wiki/ISO_639-1 In case you want a specific language template to be used instead of the automatic detection, you can specify it using this parameter. By default the API will check the national code of the destination number and will check if a language template exists for this country. If not it will default to the English template (“en” locale).

country

optional

The ISO 3166-1 alpha-2 code of the destination number.

This parameter can be used in case the country code is omitted in the destination number or because you want to be sure that the destination MSISDN number range belongs to the specific country. If it is not you will get a bad request response.

text

optional

The text template to be used for the specific OTP delivery.

In case you want to override the application template, you can specify the text to be delivered. Placeholder {{OTP}} must exist for auto generation of OTP, otherwise otpCode should be specified as parameter

otpCode

optional

The OTP code to be delivered instead of auto generated one.

In case you don’t want the API to auto generate the OTP for you, you can specify it in this parameter.

sender

optional

Sender name for OTP delivery via SMS

In case you want to override the sender set in the application’s configuration, you can specify a sender name for this OTP delivery

caller

optional

Caller id for OTP delivery via Voice

In case you want to override the caller set in the application’s configuration, you can specify a caller id for this OTP delivery

pinLength

optional

Length of the auto generated PIN

In case you want to override the pin length set in the application’s configuration, you can specify a length of the generated PIN for this OTP delivery

202 Accepted

The OTP code provided matched the one delivered.

401 Unauthorized

This verification attempt was not valid

403 Forbidden

The OTP code provided is not correct. This signals a final state for this OTP, either because the maximum attempts has been reached or because the OTP expired. You can check the otpStatus in the body response to determine the status.

404 Not Found

The OTP was not found.

410 Gone

This OTP has already being validated. Note once an OTP is validated, even if you request a check against it with the correct OTP or a wrong one you will already get this HTTP response code.

500 Internal Server Error

Unexpected error.

status

possible values: success/failed/null

statusText

The status reported by the deivery system

type

Refere to the next table regarding all event types

sipCode

In case of voice delivery the sip return code will be listed here

smsCode

In case of sms delivery the sms return code will be listed here

created

Epoch time

timestampCreated

Timestamp in string format UTC

INITIAL_OTP_REQ

Marks the initial OTP request made as API call

{ type: ‘INITIAL_OTP_REQ’, created: 1502699988995, timestampCreated: ‘2017-08-14T08:39:48.995Z’ }

DELIVER_OTP_RES_OK

Marks the successful result for delivery towards the channel

{ status: ‘success’, type: ‘DELIVER_OTP_RES_OK’, created: 1502699989105, timestampCreated: ‘2017-08-14T08:39:49.105Z’ }

DELIVER_OTP_RES_FAIL

Marks the failed result for delivery towards the channel

{ status: ‘failed’, type: ‘DELIVER_OTP_RES_FAIL’, created: 1502699989105, timestampCreated: ‘2017-08-14T08:39:49.105Z’ }

RESEND_OTP_RES_OK

Marks the successful result for delivery towards the channel for an OTP resend

{ status: ‘success’, type: ‘RESEND_OTP_RES_OK’, created: 1502699989105, timestampCreated: ‘2017-08-14T08:39:49.105Z’ }

RESEND_OTP_RES_FAIL

Marks the failed result for delivery towards the channel for an OTP resend

{ status: ‘failed’, type: ‘RESEND_OTP_RES_FAIL’, created: 1502699989105, timestampCreated: ‘2017-08-14T08:39:49.105Z’ }

OTP_SMS_RES

Marks the delivery report coming for a sms delivery

{ statusText: ‘delivered’, type: ‘OTP_SMS_RES’, smsCode: ‘0000’, created: 1502699992946, timestampCreated: ‘2017-08-14T08:39:52.946Z’ }

OTP_VOICE_RES

Marks the delivery report coming for a voice call delivery

{ statusText: ‘ok’, type: ‘OTP_VOICE_RES’, created: 1502700988376, timestampCreated: ‘2017-08-14T08:56:28.376Z’ }

OTP_VERIFY_FAIL

Marks the event when there was a failed attempt to verify an OTP code

{ type: ‘OTP_VERIFY_FAIL’, created: 1502700284084, timestampCreated: ‘2017-08-14T08:44:44.084Z’ }

OTP_VERIFY_OK

Marks the event when there was a successful attempt to verify an OTP code

{ type: ‘OTP_VERIFY_OK’, created: 1502700284084, timestampCreated: ‘2017-08-14T08:44:44.084Z’ }

Via

Optional

AUTO SMS VOICE

You can force a delivery channel by using this parameter. The default is “AUTO” which will use SMS in case of a mobile number and VOICE in case of a landline number.

sender

Optional

Sender name for OTP delivery via SMS

In case you want to override the sender set in the application’s configuration, you can specify a sender name for this OTP delivery

caller

Optional

Caller id for OTP delivery via Voice

In case you want to override the caller set in the application’s configuration, you can specify a caller id for this OTP delivery

AccountId

Type: “String” This is your accountId in the tyntec system. You cannot change this value.

Your 2FA accountId

ApplicationId

Type: “UUID” This is a UUID that identifies the specific application that was used to deliver this OTP.

otpId

Type: “UUID” The unique id that identified this OTP delivery request.

A random UUID created by tyntec

created

Type: “Integer” The time that this OTP request was created in milliseconds.

now()

expire

Type: “Integer” The time that this OTP will expire in milliseconds.

Now() + the “expire” attribute of the application

number

Type: “String” The telephone number that was used as destination for this OTP delivery request. In E164 format.

attemptCount

Type: “Integer” The number of attempts made for this OTP to be validated.

otpStatus

Type: “String” The OTP status. Possible values: “ACTIVE” – The OTP is still active VERIFIED – The OTP was verified successfully EXPIRED – The OTP expired TOO_MANY_ATTEMPTS – The OTP validation requests exceeded the maximum allowed by the application configuration.

timestampCreated

Type: “Timestamp” The string timestamp “created” representation in UTC Z format

timestampExpire

Type: “Timestamp” The string timestamp “expire” representation in UTC Z format