Introduction

Twizo’s API is a RESTful API and you can use any HTTP client in any programming language to communicate with our API. Request and response data are JSON formatted using UTF-8 encoding and URL encoded values. The only requirement to use our API is to create an account on our portal (https://register.twizo.com/ ).

API URL

We have located our servers at different locations around the globe. Which one for you is the best to use, depends on the location of your server. Each location has its own host. We have the following locations.

Location

Host

Callback host

Singapore *

api-asia-01.twizo.com

api-asia-01-out.twizo.com

Germany *

api-eu-01.twizo.com

api-eu-01-out.twizo.com

* = proposed based on your location

To ensure data privacy our API is only accessible via HTTPS so the traffic is encrypted. When our API performs a callback to deliver message results to you, it will come from the callback host listed above. Please make sure that you have white listed the callback hosts to ensure we can deliver the results to you.

Authentication

With each API call you will need to authenticate yourself via HTTP Basic Authentication. You can do this by setting the request headers. In the request headers you can set the username and password for the authentication. The user name and password must be base64 encoded. For the username you have to fill in 'twizo'. If you use one of our libraries or SDK's the username will be done for you, you just have to create an instance and set your API key and node you want to connect to. The base64 encoding of the username and password will be done by cURL and our libraries and SDK's automatically.

Versioning

Currently we have 1 version of our API but in the future we might have other versions as well. We try to keep updates of the API backwards compatible but sometimes this is not possible. When this is the case a new version will be available. In the URL of the API you can specify the version you want to use. If you do not specify the version you will use the latest version. All examples on this documentation page and in the tutorials use the latest version of our API.

Example without version:https://api-eu-01.twizo.com/verification/submit

Example with a version set:https://api-eu-01.twizo.com/v1/verification/submit

Currently we have the following versions:

Version

Release date

Available until

1

February 1, 2017

To be decided

Errors

The Twizo API uses standard HTTP status codes to indicate success or failure of your API calls. API calls, which are successful, have a HTTP status code in the range of 2xx. API calls, which have a failure, have a HTTP status code in the range of 4xx. The Twizo API can at least return HTTP status codes as shown in the table below. For some status codes an errorCode is added as well. Example response:

The Verification, SMS or Number Lookup with the specified messageId was not found.

406 Not Acceptable

Cannot honor Accept type specified, only Accept header 'application/json' is supported. See Authentication example how to set it.

409 Conflict

You have requested to create backup codes via a HTTP POST but the used identifier already exists. If you want to overwrite the existing entity use HTTP PUT instead.

415 Unsupported Media Type

Invalid content-type specified, only Content-type header 'application/json' is supported. See Authentication example how to set it.

422 Unprocessable Entity

103

Invalid token. The token entered by the user does not match with the token sent by our API to the user.

423 Locked

101

The token you tried to verify was already verified, you are only allowed to check a certain token once.

102

The token you tried to verify is expired. The token was not entered by the user within the required time (validity).

104

The token you tried to verify is failed. The reason why it is failed is for example because the Verification service of the account is disabled. In that case no token is sent and the user entered a random token.

429 Too Many Requests

You are sending too fast and your calls are throttled.

5xx

An internal system error occurred. When this happens you can retry submitting the message.

Integer, not null. The number of free verifications you have left for this month.

wallet

String, not null. The name of your wallet.

Balance alarm

In the Twizo portal you can configure balance alarms. When the balance of your wallet gets below a limit, you will be triggered. The trigger can be an email or a webhook.

When you configure a webhook our system will do a HTTP POST from one of our callback hosts to your URL. The balance alarm will be sent to you in JSON format. You will have to respond to the call with HTTP status code 200 OK. If you respond with another HTTP status code we will try to call the URL again after some time. We will try to call the URL maximum 10 times with an increasing time interval where the last attempt is 72 hours after the first attempt.

Verification

With our verification service you can easily integrate Two Factor Authentication (2FA) into your application. We will describe in a few simple steps how to do it. The below is for verifications via Twizo Authenticator - Push, Bio voice, SMS, Voice call, Telegram, LINE and Facebook Messenger. The flow for a Backup code or Twizo Authenticator - TOTP verification is slightly different, please check the Backup code and TOTP section.

For some verification types you first need to register. This is for Bio voice, Telegram, Line and Facebook Messenger. For Bio voice, check out the Bio voice section for more details on the registration. In our help section we explain how to register for Telegram, LINE and Facebook Messenger.

First you start with submitting a verification by doing a HTTP POST to our API with URL:https://api-asia-01.twizo.com/verification/submit

You will need to specify in JSON format the recipient number. An example on how to do to submit a verification:

The returned JSON response will contain a messageId field. This messageId must be used when you want to verify the token sent to the phone. See Verification status for more information about the other fields returned in the response.

Verification parameters

When you request a verification you can specify several parameters. Below you can find an overview of all parameters.

Parameter

Description

recipient

This is a mandatory string parameter. The recipient is a single phone number in international format. The phone number can be a mobile number or a fixed phone number.

type

This is an optional string parameter. The type defines how the token will be send to the phone. Possible values are: 'biovoice', ‘sms', ‘call’, 'push', 'telegram', 'line' or 'facebook_messenger'. The default value is ‘sms’.

issuer

This is a mandatory string parameter when the type is set to 'push', 'telegram', 'line' or 'facebook_messenger'. The maximum length is 64 characters. The issuer is the name of the site the user wants to login to. When the user receives the request to confirm he wants to login, the user will get a message like "Please confirm to verify your login of '<issuer>'".

tokenLength

This is an optional integer parameter. The tokenLength defines the length of the token. The minimum value is 4 and the maximum value 10. The default value is 6. When you set the tokenLength, you have to set the tokenType as well.

tokenType

This is an optional string parameter. Possible values are ‘numeric’ and ‘alphanumeric’. Numeric token will only contain the digits 0-9. For alphanumeric the token contains the digits 0-9 and characters a-z (lowercase). The default value of the tokenType is ‘numeric’. When you set the tokenType, you have to set the tokenLength as well.

tag

This is an optional string parameter. The tag is a free text parameter you can use for your own reference. The maximum length of the tag is 30 characters. The tag parameter is returned in the result and you can use it for reporting purposes on your side.

sessionId

This is an optional string parameter. If it is not set the API will automatically generate the value. See ‘Verification session’ for more information. The maximum length of the sessionId is 54 characters.

validity

This is an optional integer parameter. The validity specifies how long the token is valid. The validity is in seconds. If the token is not verified within this time, the token is expired. The minimum value of the validity is 5 seconds and the maximum value is 3600 seconds (= 1 hour). The default value is 60 seconds.

The Type parameter specifies if an SMS will be send or a call will be made. For SMS there are some additional parameters, which can be set.

bodyTemplate

This is an optional string parameter. The body template in case an SMS needs to be send. The body template must contain the tag ‘%token%’ which will be used by the system to replace it with the actual token to be send to the end user. The maximum length on the body template is for GSM-7 alphabet 160 characters and for Unicode maximum 70 characters. This is including the token which will be inserted by the system. So if you set a tokenLength of 8, the max length of the bodyTemplate is 160-8=152 characters excluding the text '%token%'. If you do not set the tokenLength, the API will need to consider the maximum length of the token (10) for the maximum bodyTemplate length, so in that case the bodyTemplate can have a maximum length of 150 characters for GSM-7 and 60 for Unicode. Concatenated messages are not possible for these SMS messages. See our tutorial ‘Unicode’ for more information on the maximum length of the body. Default value for the bodyTemplate is: Your verification token is: %token%

sender

This is an optional string parameter. The sender is what the receiver of the SMS see as the submitter of the SMS. See our tutorial ‘Sender’ for more information. The default value for the sender is ‘Twizo’.

senderTon

This is an optional integer parameter. If it is not set the API will automatically detect the value. See our tutorial ‘Sender’ for more information.

senderNpi

This is an optional integer parameter. If it is not set the API will automatically detect the value. See our tutorial ‘Sender’ for more information.

dcs

This is an optional integer parameter. With the DCS parameter you can specify the character set of the bodyTemplate. For GSM-7 the value should be 0 and for Unicode the value should be 8. The default value is 0. See our tutorial ‘Unicode’ for more information.

Verify token

When the user received the token and entered it in your website, the API will verify the token with the token we have sent. You will have to do a GET to the URL:https://api-asia-01.twizo.com/verification/submit/<messageId>?token=<token>

You will have to put the following parameters in the URL:

<messageId>

The messageId returned with the verification submit.

<token>

The token entered by the user and you want to verify with the token we sent to the user.

Please note: you can verify the token for a session ID only once! This is to prevent users will try to guess a token.

When the verification is successful you get a HTTP status 200 OK and a response where the 'statusCode' field has the value 1 and the 'status' field has the value 'success' like below example in JSON format:

Integer, can be null. The length of the token as specified when sending the verification or the default value (6).

tokenType

String, can be null. The type of the token as specified when sending the verification or the default value (numeric).

createdDateTime

String, not null. The datetime the verification was received by the API. The datetime is in ISO-8601 format.

dcs

Integer, can be null. The DCS value as specified when sending the verification.

issuer

String, can be null. The issuer name as specified when sending the verification.

language

String, can be null. Currently not used yet.

messageId

String, not null. The unique identifier, generated by the API, of the verification.

reasonCode

Integer, can be null. When the verification is rejected or failed a reasonCode can be given explaining the cause of the rejection. See further down below for an overview of possible reasonCodes

recipient

String, not null. The phone number as specified when sending the verification, the token must be send to.

salesPrice

Float, can be null. The sales price of the verification. When the verification was a free monthly verification the sales price is 0.

salesPriceCurrencyCode

String, can be null. The currency code of the salesPrice field. The value can be 'eur', 'usd' or 'sgd'. The currency code is defined by the currency of your wallet.

sender

String, can be null. The sender of the token in case of an SMS as specified when sending the verification or the default value (Twizo).

senderNpi

Integer, can be null. The senderNpi of the token in case of an SMS as specified when sending the verification or the automatically detected value by the API. See our tutorial ‘Sender’ for more information.

senderTon

Integer, can be null. The senderTon of the token in case of an SMS as specified when sending the verification or the automatically detected value by the API. See our tutorial ‘Sender’ for more information.

sessionId

String, not null. The sessionId generated by the API when it was left out with the verification request or the sessionId you specified at the verification request. See 'Verification session' for more information.

status

String, not null. The status of the verification. The status and statusCode fields are bound together and can have the following values:

0

no status

The token is generated and sent to the phone.

1

success

The token is successfully verified. The entered token matches with the token sent to the phone.

2

rejected

The verification is rejected by the system and no token is sent to the phone. The reasonCode field indicates the reason why it is rejected. See further down below for an overview of possible reasonCodes.

3

expired

The verification is expired as the token was not verified within the specified validity time.

4

failed

The verification is failed as the entered token didn’t match with the token sent to the phone. The reasonCode field indicates the reason why it is rejected. See further down below for an overview of possible reasonCodes.

statusCode

Integer, not null. See 'status' field for more information.

tag

String, can be null. The tag as specified when sending the verification.

bodyTemplate

String, can be null. The tag value as specified when sending the verification or the default value (Your verification token is: %token%)

type

String, not null. The type as specified when sending the verification or the default value (sms)

validity

Integer, not null. The validity in seconds as specified when sending the verification or the default value (60)

validUntilDateTime

String, not null. The datetime until when the verification is valid. This is calculated by the API based on the validity field.

_links

HATEOAS (Hypermedia as the Engine of Application State) is a constraint of the REST application architecture. A hypermedia-driven site provides information to navigate the site's REST interfaces dynamically by including hypermedia links with the responses. See HATEOAS for more information.

The status of a verification can be checked up to 24 hours after the validity. After that the verification is removed from the API and you will receive a HTTP status code 404 Not Found. You can however still check the verification in the portal via Message details .

Verification session

When a user logs in to your website you request a verification and the API will send a token to the user. If for some reason the user does not receive the token or enters the token incorrect, you have to do a new verification request. This will continue until the user entered the correct token. All these verifications for this user login are part of the same session.

When you submit the first verification request and leave the sessionId parameter of the request empty, the API generates a unique sessionId which is returned in the result. If you set this sessionId in the next verification request for the user login, we store that sessionId with both verifications. That way we keep track of the sessions and you can do analysis of how often a verification fails in a session. This way you can improve the success rate of your verifications.

Reason codes

When a verification has status '2 - rejected' or '4 - failed' a reasonCode can be returned. The following reason codes can be returned:

Reason code

Description

1

Insufficient credits

2

Verification service not enabled for account

3

Unsupported destination country or operator

4

Account not allowed to send verifications

5

Verification failed due to system error

6

Verification expired

7

Token not delivered to phone as phone is busy, hang up, did not answer, could not receive message, etc.

8

Token not delivered to phone due to network problems

10

Content of the bodyTemplate is not allowed by the network

Verification types

For an account you can set the verification types you want to offer your users via the Verification Widget. Via the API you can retrieve the verification types you have set. You can use this for example to show a list where the user can set their own preferred verification type. If you retrieve the verification types via the API you show in the list, the list will automatically be updated when we add new types or when you enable/disable a verification type.

To set the verification types you want to allow your users, go to the Account settings, select the Verification tab and enable/disable the verification types you want to allow. You can also set the preferred verification type. The preferred verification type is the default type used when the user did not set any.

You can retrieve the allowed verification types of your account with a HTTP GET to the URL:https://api-asia-01.twizo.com/application/verification_types

Example how to retrieve the allowed verification types of your account:

The first verification type of the returned list is the preferred verification type you have set. So this verification type will be used first when the widget opens.

Verification widget

With the verification widget you can easily integrate our verification service without the need of implementing forms to handle the verification. For more information how to integrate the widget, checkout our widget guide. When you create a widget verification session and start the widget, the widget will create one or more verifications. Those verifications will have as as sessionId the session token of the widget verification session.

You start a widget verification session by doing a HTTP POST to our API with URL:https://api-asia-01.twizo.com/widget/session

You will need to specify in JSON format the recipient you want the token to be send to. An example on how to do it:

The returned JSON response will contain a sessionToken field. This sessionToken you will need to open the widget. See the widget guide for more information. See status for more information about the other fields returned in the response.

Verification widget parameters

When you request a widget verification session you can specify several parameters. Below you can find an overview of all parameters.

Parameter

Description

allowedTypes

This is a optional array parameter. The allowedTypes defines which verification types can be used with the widget. Possible values are: ‘sms’, ‘call’, 'biovoice', 'push', 'totp', 'telegram', 'line' or 'backupcode'. When you do not set the parameter, the widget will use as default the types you have set for your account (Open the settings of the account and on the Verification tab select the types you want to allow your users to use). The first type you set as allowed type will be the first verification the widget will perform. The API will filter out certain types when that option is not available for the user. For example when you set 'backupcode' but for the backupCodeIdentifier you specified the API cannot find backup codes, the type will be removed. See 'requestedTypes' and 'allowedTypes' in the status result for more information.

recipient

This is a mandatory string parameter when for the allowedTypes 'sms' or 'call' is included. The recipient is a single phone number in international format. The phone number can be a mobile number or a fixed phone number.

backupCodeIdentifier

This is a mandatory string parameter when for the allowedTypes 'backupcode' is included. The backupCodeIdentifier is the identifier you used for creating the backup codes for the user.

totpIdentifier

This is a mandatory string parameter when for the allowedTypes 'totp' is included. The totpIdentifier is the identifier you used for creating the TOTP for the user.

tokenLength

This is an optional integer parameter. The tokenLength defines the length of the token. The minimum value is 4 and the maximum value 10. The default value is 6. When you set the tokenLength, you have to set the tokenType as well.

tokenType

This is an optional string parameter. Possible values are ‘numeric’ and ‘alphanumeric’. Numeric token will only contain the digits 0-9. For alphanumeric the token contains the digits 0-9 and characters a-z (lowercase). The default value of the tokenType is ‘numeric’. When you set the tokenType, you have to set the tokenLength as well.

tag

This is an optional string parameter. The tag is a free text parameter you can use for your own reference. The maximum length of the tag is 30 characters. The tag parameter is returned in the result and you can use it for reporting purposes on your side.

issuer

This is a mandatory string parameter when you want to use a verification of type 'push', 'telegram' or 'line'. The issuer is the name of the site the user wants to login to. When the user receives the request to confirm he wants to login, the user will get a message like "Please confirm to verify your login of '<issuer>'".

The Type parameter specifies if an SMS will be send or a call will be made. For SMS there are some additional parameters, which can be set.

bodyTemplate

This is an optional string parameter. The body template in case an SMS needs to be send. The body template must contain the tag ‘%token%’ which will be used by the system to replace it with the actual token to be send to the end user. The maximum length on the body template is for GSM-7 alphabet 160 characters and for Unicode maximum 70 characters. This is including the token which will be inserted by the system. So if you set a tokenLength of 8, the max length of the bodyTemplate is 160-8=152 characters excluding the text '%token%'. Concatenated messages are not possible for these SMS messages. See our tutorial ‘Unicode’ for more information on the maximum length of the body.
Default value for the bodyTemplate is: Your verification token is: %token%

sender

This is an optional string parameter. The sender is what the receiver of the SMS see as the submitter of the SMS. See our tutorial ‘Sender’ for more information. The default value for the sender is ‘Twizo’.

senderTon

This is an optional integer parameter. If it is not set the API will automatically detect the value. See our tutorial ‘Sender’ for more information.

senderNpi

This is an optional integer parameter. If it is not set the API will automatically detect the value. See our tutorial ‘Sender’ for more information.

dcs

This is an optional integer parameter. With the DCS parameter you can specify the character set of the bodyTemplate. For GSM-7 the value should be 0 and for Unicode the value should be 8. The default value is 0. See our tutorial ‘Unicode’ for more information.

Verification widget status

You can check the status of a widget verification session with a simple GET and specifying the sessionToken and recipient and/or backupCodeIdentifier. If you have to set recipient, backupCodeIdentifier or both depends on how the verification session is created. The values you have set when the verification session was created is also needed when you check the status. Check the status of a verification session:

Integer, can be null. The length of the token as specified when sending the verification or the default value (6).

tokenType

String, can be null. The type of the token as specified when sending the verification or the default value (numeric).

createdDateTime

String, not null. The datetime the verification was received by the API. The datetime is in ISO-8601 format.

dcs

Integer, can be null. The DCS value as specified when sending the verification.

issuer

String, can be null. The issuer name as specified when sending the verification.

language

String, can be null. Currently not used yet.

recipient

String, not null. The phone number as specified when sending the verification, the token must be send to.

sender

String, can be null. The sender of the token in case of an SMS as specified when sending the verification or the default value (Twizo).

senderNpi

Integer, can be null. The senderNpi of the token in case of an SMS as specified when sending the verification or the automatically detected value by the API. See our tutorial ‘Sender’ for more information.

senderTon

Integer, can be null. The senderTon of the token in case of an SMS as specified when sending the verification or the automatically detected value by the API. See our tutorial ‘Sender’ for more information.

status

String, not null. The status of the widget verification session. The status and statusCode fields are bound together and can have the following values:

0

no status

The widget verification session is created and waiting for the widget to get started and performing verifications.

1

success

The widget verification session is successfully verified. The entered token matches with the token sent to the phone.

2

expired

The widget verification session is expired as the token was not verified within the specified validity time of the widget verification session.

3

max_attempts

The verification is failed the maximum number of attempts of sending verification has reached.

statusCode

Integer, not null. See 'status' field for more information.

tag

String, can be null. The tag as specified when sending the verification.

bodyTemplate

String, can be null. The tag value as specified when sending the verification or the default value (Your verification token is: %token%)

requestedTypes

Array, not null. The allowed types as specified when creating the widget verification session.

allowedTypes

Array, not null. The allowed types as specified when creating the widget verification session minus types not available for the user. For example when you set 'backupcode' but for the backupCodeIdentifier you specified the API cannot find backup codes, the type will be removed.

validity

Integer, not null. The validity in seconds as specified when sending the verification or the default value (60).

backupCodeIdentifier

String, can be null. The backupCodeIdentifier if set when creating the session.

totpIdentifier

String, can be null. The totpIdentifier if set when creating the session.

verificationIds

Array, not null. An array with verification ID's performed during the session.

verification

Verification object, can be null. When the session is successfull, this parameter contains the successful verification object.

_links

HATEOAS (Hypermedia as the Engine of Application State) is a constraint of the REST application architecture. A hypermedia-driven site provides information to navigate the site's REST interfaces dynamically by including hypermedia links with the responses. See HATEOAS for more information.

The status of a widget verification session can be checked up to 24 hours after the validity. After that the widget verification session is removed from the API and you will receive a HTTP status code 404 Not Found. The verifications performed by the widget, you can find in the portal via Message details by filling in the session token in the session Id field in the search form.

Registration widget

With the registration widget you can easily integrate our verification service without the need of implementing forms to register a user for the different verification types. For more information how to integrate the widget, checkout our widget guide.

You start a registration widget session by doing a HTTP POST to our API with URL:https://api-asia-01.twizo.com/widget-register-verification/session

You will need to specify in JSON format the recipient you want the token to be send to. An example on how to do it:

The returned JSON response will contain a sessionToken field. This sessionToken you will need to open the registration widget. See the widget guide for more information.

Registration widget parameters

When you request a registration widget session you can specify several parameters. Below you can find an overview of all parameters.

Parameter

Description

allowedTypes

This is a optional array parameter. The allowedTypes defines which verification types the user can register for in the widget. Possible values are: ‘sms’, ‘call’, 'biovoice', 'push', 'totp', 'telegram', 'line' or 'backupcode'. When you do not set the parameter, the widget will use as default the types you have set for your account (Open the settings of the account and on the Verification tab select the types you want to allow your users to use).

recipient

This is a mandatory string parameter when for the allowedTypes 'sms' or 'call' is included. The recipient is a single phone number in international format. The phone number can be a mobile number or a fixed phone number.

backupCodeIdentifier

This is a mandatory string parameter when for the allowedTypes 'backupcode' is included. The backupCodeIdentifier is the identifier you used for creating the backup codes for the user.

totpIdentifier

This is a mandatory string parameter when for the allowedTypes 'totp' is included. The totpIdentifier is the identifier you used for creating the TOTP for the user.

issuer

This is a mandatory string parameter when you want to use a verification of type 'push', 'telegram' or 'line'. The issuer is the name of the site the user wants to login to. When the user receives the request to confirm he wants to login, the user will get a message like "Please confirm to verify your login of '<issuer>'".

Backup codes

If you lose your phone(s) or otherwise can't receive codes via SMS, voice call, or Google Authenticator, you can use backup codes to sign in.
With our backup code feature you can generate 10 backup codes for a user. When the user loses his phone or can't receive the verification token via SMS or a voice all, he can use a backup code to verify.

To start you first need to create backup codes for a user. When the backup codes are generated by the API you can show them to the user and the user can store them in a safe location. We advise you not to store the backup codes on your server, only the user should store them. Once the backup codes are generated the user can use them when needed. The backup codes will be stored on our servers. Each time the user uses a backup code, the number of remaining backup codes left will be returned by the API. Inform the user in time when he is almost out of backup codes, as when he is out of backup codes he can't verify anymore. To generate new backup codes the user doesn't have to wait until he used the last one, he can generate new backup codes at any time. When generating new backup codes the old ones will be removed and cannot be used anymore.

Backup codes you have generated for a user will be available on all our API nodes. So when you generated backup codes on one of our Asia nodes, you can verify a backup code also on one of our Europe nodes.

Create backup codes

You can create backup codes by doing a HTTP POST to the API with URL:https://api-asia-01.twizo.com/backupcode

You will need to specify in JSON format the identifier you want the backup codes to be created. The parameters you can set are:

identifier

This is a mandatory string parameter. The identifier must be a unique identifier of the user, e.g. an email address.

Verify backup code

When the user uses a backup code and entered it in your website, the API will verify the backup code with the backup codes generated for the user. You will have to do a GET to the URL:https://api-asia-01.twizo.com/backupcode/<identifier>?token=<backupCode>

You will have to put the following parameters in the URL:

<identifier>

The identifier you used to generate the backup codes for the user.

<backupCode>

The backup code entered by the user and you want to verify with the generated backup codes for the user.

Update backup codes

When you have generated backup codes for a user before, you can update the backup codes. When you update the backup codes of a user, new backup codes will be generated and the old remaining backup codes will be invalid. You can update backup codes by doing a HTTP PUT to the API with URL:https://api-asia-01.twizo.com/backupcode/<IDENTIFIER>

You will have to put the following parameters in the URL:

<IDENTIFIER>

The unique identifier for your user. The identifier parameter is a string with a maximum length of 64 characters.

Also you will need to specify in JSON format the identifier you want the backup codes to be updated. An example on how to do it:

Delete backup codes

You can delete the backup codes of a user. The user will then not be able to use any of backup codes generated before. To delete the backup codes of a user you have to do a DELETE to our API with the ‘identifier’. When the API has deleted the backup code you will get a HTTP status 204 'No content' returned from the API.

TOTP

TOTP, or Time-Based One-Time Password, can be used with our Twizo Authenticator. When you have added an application (website) to the app, every 60 seconds a new token will be generated. This token you can use for verification.

To start you first need to create a TOTP for a user. When the TOTP is generated by the API you can show a QR code (check out our help topic 'How to generate a QR code ') to the user which can be scanned by the Twizo Authenticator. When generating a new TOTP, the old one is removed and cannot be used anymore.

A TOTP you have generated for a user will be available on all our API nodes. So when you generated a TOTP on one of our Asia nodes, you can verify a TOTP also on one of our Europe nodes.

Create TOTP

You can create a TOTP by doing a HTTP POST to the API with URL:https://api-asia-01.twizo.com/totp

You will need to specify in JSON format the identifier and issuer you want to create a TOTP for. The parameters you can set are:

identifier

This is a mandatory string parameter. The identifier must be a unique identifier of the user, e.g. an email address. The identifier will be visible in the Twizo Authenticator app as the application name.

issuer

This is a mandatory string parameter. The issuer is the name of the site the user wants to login to. The issuer will be visible to the user when he scans the TOTP with the Twizo Authenticator app and shows for which website the TOTP is.

When the TOTP is generated successfully a HTTP status 201 is returned. The response will contain the generated URI which can be converted to a QR code (check out our help topic 'How to generate a QR code ') and scanned by the Twizo Authenticator. Below an example in JSON format:

When you want to generate a new TOTP for a user, please delete the existing TOTP first.

Verify TOTP

When the user uses a TOTP token and entered it in your website, the API will verify the token with the TOTP generated for the user. You will have to do a GET to the URL:https://api-asia-01.twizo.com/totp/<identifier>?token=<TOKEN>

You will have to put the following parameters in the URL:

<identifier>

The identifier you used to generate the TOTP for the user.

<token>

The TOTP token entered by the user and you want to verify with the generated TOTP for the user.

{
"identifier": "<IDENTIFIER>",
"issuer": "Twizo",
"uri": null,
"verification": null,
"_links": {
"self": {
"href": "https:\/\/api-asia-01.twizo.com\/v1\/totp\/<IDENTIFIER>"
}
}
}
The URI will only be returned when you create a TOTP. If it is needed afterwards, the user needs to create a new TOTP.

Delete TOTP

You can delete a TOTP of a user. The user will then not be able to use the TOTP anymore. To delete a TOTP of a user you have to do a DELETE to our API with the ‘identifier’. When the API has deleted the TOTP you will get a HTTP status 204 'No content' returned from the API.

Bio voice

Bio voice verification is a verification based on your voice. In order to be able to do such verification, you first have to register a user for it. This is done via a phone call where the user needs to say a sentence 3 times. Based on this a voice print of the user is created.

So first start a registration, once the registration is completed, a subscription is created. The sentence the user has to say is by default 'Verify me with my voicepin'. If you want a different sentence, please contact our support.

Create registration

You can create a registration by doing a HTTP POST to the API with URL:https://api-asia-01.twizo.com/biovoice/registration

You will need to specify in JSON format the identifier you want the bio voice registration to be created for. An example on how to do it:

Check status registration

While a registration is in progress, you cannot perform a bio voice verification yet. To check the status of the registration you will have to do a GET to the URL:https://api-asia-01.twizo.com/biovoice/registration/<RECIPIENT>

You will have to put the following parameters in the URL:

<recipient>

The recipient number you used for creating the bio voice registration for the user.

Delete subscription

You can delete a bio voice subscription of a user. The user will then not be able to use the bio voice verification anymore. To delete the bio voice subscription of a user you have to do a DELETE to our API with the recipient number. When the API has deleted the bio voice subscription you will get a HTTP status 204 'No content' returned from the API.

Most important field in the response is the messageId. See SMS status for more information about the other fields returned in the response. You will need this to check the status of the SMS or to get the delivery report. How to get the status or delivery reports is described further below.

The above example is using our simple SMS function. With this function can send long SMS and the API will automatically split up the messages into parts as an SMS has a maximum length. Check our tutorial ‘Concatenated/long SMS’ for more information on concatenated SMS.

Apart from the simple SMS function we also have an advanced SMS function where you have full control on the properties of an SMS. The parameters of both functions are described in the next paragraphs.

Simple SMS parameters

To submit a simple SMS you have to do a POST with the data in JSON format to our API with URL:https://api-asia-01.twizo.com/sms/submitsimple

Parameters you can set when submitting SMS are:

Parameter

Description

recipients

This is a mandatory array with strings parameter. It should be an array of numbers (in string format), in international format, for the SMS. At least 1 number must be set and maximum 1000.

body

This is a mandatory string parameter. The body of the SMS. The API will automatically determine if the body is Unicode or not and when the body is too long for a single SMS the API will automatically split up the body into multiple parts. The maximum number of concatenated parts is 9. See our tutorials ‘Unicode’ and ‘Concatenated/long SMS’ for more information.

sender

This is a mandatory string parameter. The sender is what the receiver of the SMS see as the submitter of the SMS. See our tutorial ‘Sender’ for more information. When it is numeric the maximum length is 17 digits, when it is alphanumeric the maximum length is 11.

senderTon

This is an optional integer parameter. If it is not set the API will automatically detect the value. See our tutorial ‘Sender’ for more information.

senderNpi

This is an optional integer parameter. If it is not set the API will automatically detect the value. See our tutorial ‘Sender’ for more information.

pid

This is an optional integer parameter. Can be used to send hidden SMS. Allowed values: 0-255. See also GSM specification .

scheduledDelivery

This is an optional string parameter. Datetime of scheduled delivery. Must be in ISO-8601 format, example: 2016-10-31T12:34:56Z

tag

This is an optional string parameter. The tag is a free text parameter you can use for your own reference. The maximum length of the tag is 30 characters. The tag parameter is returned in the result and you can use it for reporting purposes on your side

validity

This is an optional integer parameter. The validity specifies how long the message is valid. The validity is in seconds. If the message could not be delivered within this time, the message will expire and no more attempts will be made to deliver it. The minimum value of the validity is 5 seconds and the maximum value is 259200 seconds (= 72 hours). The default value is 259200 seconds.

resultType

This is an optional integer parameter. If you want to receive or poll for final results of your verifications, you can set the resultType. You can use the results for your own reporting purposes. Possible values of the resultType are:

0

No results (default)

1

Callback (you have to specify the callbackUrl)

2

Polling

3

Callback & polling (you have to specify the callbackUrl)

callbackUrl

This string parameter is only mandatory when resultType is set to 1 or 3. When the callbackUrl is set, this URL will be used by our system to submit status updates to you. This parameter is only allowed when the resultType parameter is set to 1 or 3.

Advanced SMS parameters

To submit an advanced SMS you have to do a POST with the data in JSON format to our API with URL:https://api-asia-01.twizo.com/sms/submit

For the advanced SMS you can set the same parameters as for the simple SMS except that the body parameter is different and there are 2 additional possible parameters:

body

This is a mandatory string parameter. The body of the SMS. The body shall be send in GSM-7 alphabet and the maximum length is 160 characters. When you want to send characters not in the GSM-7 alphabet you have to send it as Unicode. In that case you have to set the DCS to 8. The maximum length is in that case 70 characters. When you send a concatenated message, you have to set a UDH as well and the maximum length for GSM-7 is then 153 characters and for Unicode 67 characters. See our tutorials 'Unicode' and 'Concatenated/long SMS' for more information.

dcs

Optional integer parameter for advanced, can be used to mark body as Unicode (8). Allowed values: 0-255. See also GSM specification .

udh

Optional string parameter for advanced; sets concat message. Can only consist of hexadecimal characters. Length in this parameter divided by 2 is subtracted from the maximum body length. See also GSM specification .

SMS status

You can check the status of an SMS with a simple GET and specifying the ‘messageId’ returned in the submit of the SMS:

String, can be null. The callback URL specified when sending the SMS. Our system will call this URL to return the delivery report of the SMS.

createdDateTime

String, not null. The datetime the SMS was received by the API. The datetime is in ISO-8601 format.

dcs

Integer, can be null. The DCS value as specified when sending the SMS.

messageId

String, not null. The unique identifier, generated by the API, of the SMS.

networkCode

String, can be null. The network code of the operator the mobile number is subscribed to. The network code is the MCC (Mobile Country Code) and MNC (Mobile Network Code) concatenated.

pid

Integer, can be null. The PID value as specified when sending the SMS.

reasonCode

Integer, can be null. When the SMS is rejected or could not be delivered a reasonCode is given explaining the cause of the rejection. See further down below for an overview of possible reasonCodes

recipient

String, not null. The phone number as specified when sending the SMS.

resultType

Integer, not null. The result type specified when sending the SMS. Possible values are:

0

No results (default)

1

Callback (you have to specify the callbackUrl)

2

Polling

3

Callback & polling (you have to specify the callbackUrl)

salesPrice

Float, can be null. The sales price of the SMS.

salesPriceCurrencyCode

String, can be null. The currency code of the salesPrice field. The value can be 'eur', 'usd' or 'sgd'. The currency code is defined by the currency of your wallet.

scheduledDelivery

String, can be null. The scheduled delivery time as specified when sending the SMS.

sender

String, not null. The sender of the SMS as specified when sending the SMS.

senderNpi

Integer, can be null. The senderNpi of the SMS as specified when sending the SMS or the automatically detected value by the API. See our tutorial ‘Sender’ for more information.

senderTon

Integer, can be null. The senderTon of the SMS as specified when sending the SMS or the automatically detected value by the API. See our tutorial ‘Sender’ for more information.

status

String, not null. The status of the SMS. The status and statusCode fields are bound together and can have the following values:

0

no status

The SMS is received by our system. This is a temporary status, a final status will follow later.

1

delivered

The SMS is successfully delivered to the mobile phone.

2

rejected

The SMS is rejected by the system and is not sent to the phone. The reasonCode field indicates the reason why it is rejected. See further down below for an overview of possible reasonCodes.

3

expired

The SMS is expired as it could not be delivered within the specified validity time.

4

enroute

The SMS is on it's way in the mobile network and will be tried to deliver at a later moment. This is a temporary status, a final status will follow later.

5

buffered

The SMS is buffered in a queue in the mobile network and will be tried to deliver at a later moment. This is a temporary status, a final status will follow later.

6

accepted

The SMS is accepted by the mobile network and will be tried to deliver at a later moment. This is a temporary status, a final status will follow later.

7

undelivered

The SMS could not be delivered.

8

deleted

The SMS is deleted and will not be delivered.

9

unknown

The SMS could not be delivered due to an unknown reason.

statusCode

Integer, not null. See 'status' field for more information.

tag

String, can be null. The tag as specified when sending the SMS.

resultTimestamp

String, can be null. The timestamp when the message is delivered to the mobile phone.

udh

String, can be null. The UDH as specified when sending the SMS.

validity

Integer, not null. The validity in seconds as specified when sending the SMS or the default value (60)

validUntilDateTime

String, can be null. The datetime until when the SMS is valid. This is calculated by the API based on the validity field.

_links

HATEOAS (Hypermedia as the Engine of Application State) is a constraint of the REST application architecture. A hypermedia-driven site provides information to navigate the site's REST interfaces dynamically by including hypermedia links with the responses. See HATEOAS for more information.

The status of an SMS can be checked 24 hours after the validity. After that the SMS is removed from the API and you will receive a HTTP status code 404 Not Found. You can however still check the SMS in the portal via Message details .

SMS delivery reports

Apart from checking the status of an SMS, you can also retrieve delivery reports. Each time you check for delivery reports you will receive up to maximum 10 delivery reports at a time. When you received the delivery reports you will need to confirm them so that our system knows you received them correctly. If you do not confirm them, after a timeout of 5 minutes, the same delivery reports will be available again. If you do not retrieve/confirm delivery reports, they will automatically be removed after 24 hours. When you are using one of our libraries or SDK's you do not have to confirm the delivery reports, it will be done for you, so you don't have to confirm.

You can confirm the delivery reports by doing a DELETE to our API with the ‘batchId’ returned from the GET call. When you are using one of our libraries or SDK's you do not have to confirm the delivery reports, it will be done for you, so you don't have to confirm.

Callback URL

When you have specified a callback URL, our system will HTTP POST that URL with the delivery report. The result will be sent in JSON format, similar like when you check the status of an SMS. You will have to respond to the call with HTTP status code 200 OK. If you respond with another HTTP status code we will try to call the URL again after some time. We will try to call the URL maximum 10 times with an increasing time interval where the last attempt is 72 hours after the first attempt.

Reason codes

When our API accepted an SMS but for example the number could not be found, a reason code is returned. The following reason codes can be returned:

Incoming SMS

Incoming SMS, or sometimes called Mobile Originated SMS (MO), are SMS messages sent by a phone to our platform. Those messages are sent to so called Virtual Mobile Numbers (VMN) and handled by our platform. You can use this Incoming SMS service for e.g. 2-way SMS. In order to use this service you need to register a VMN, you can do this by contacting us at support@twizo.com.

When you register a VMN, you will receive all incoming messages on that number. You can also register keywords for the VMN and per keyword you can set a different callback URL. A keyword is the first word of the incoming message.

When you register a VMN you will be asked to provide us a URL which our platform will call to deliver the incoming SMS to you. The system will do a HTTP POST from one of our callback hosts to your URL. The incoming SMS will be sent to you in JSON format. You will have to respond to the call with HTTP status code 200 OK. If you respond with another HTTP status code we will try to call the URL again after some time. We will try to call the URL maximum 10 times with an increasing time interval where the last attempt is 72 hours after the first attempt.

String, not null. The datetime the incoming SMS was received by our platform. The datetime is in ISO-8601 format.

keyword

String, can be null. If you have configured keyword for your VMN and the message begins with the keyword, the keyword will be set in this field.

networkCode

String, can be null. The network code of the operator of the mobile number who sent the SMS. The network code is the MCC (Mobile Country Code) and MNC (Mobile Network Code) concatenated.

recipient

String, not null. The recipient is the mobile number when the MO is sent to, so the VMN configured for you.

sender

String, not null. The mobile number who sent the SMS.

udh

Strong, can be null. When the mobile number who sent the SMS sent a long SMS, it will be split up by the network into parts. Each part will have a UDH which you can use to combine it to one text again. See our tutorial on Concatenated/long SMS for more details.

Number Lookup

With Number Lookup you can get information specific to a mobile phone number. You can get the following information:

If the mobile number is still active or not (the number might be out of use because the subscription has ended).

If the mobile number is ported to another operator (the current operator is different then the operator who issues the number).

If the mobile number is roaming (connected to a network other then his home network, e.g. in another country).

You can perform a Number Lookup by doing a HTTP POST to API with URL:https://api-asia-01.twizo.com/numberlookup/submit

You will need to specify in JSON format the numbers you want to perform the Number Lookup for. An example how to do it:

Most important field in the response is the messageId. See Number Lookup status for more information about the other fields returned in the response. You will need this to check the status of the Number Lookup or to get the result. How to get the status or results is described further below.

Number Lookup parameters

When you perform a Number Lookup you can specify several parameters. Below you can find an overview of all parameters.

Parameter

Description

numbers

This is a mandatory array with string parameter. It should be an array of numbers (in string format), in international format, for the number lookup. At least 1 number must be set and maximum 1000 numbers can be set.

tag

This is an optional string parameter. The tag is a free text parameter you can use for your own reference. The maximum length of the tag is 30 characters. The tag parameter is returned in the result and you can use it for reporting purposes on your side.

validity

This is an optional integer parameter. The validity specifies how long the Number Lookup is valid. The validity is in seconds. If the Number Lookup could not be performed within this time, the Number Lookup is expired. The minimum value of the validity is 5 seconds and the maximum value is 259200 seconds (= 72 hours). The default value is 259200 seconds.

resultType

This is an optional integer parameter. If you want to receive or poll for final results of your verifications, you can set the resultType. You can use the results for your own reporting purposes. Possible values of the resultType are:

0

No results (default)

1

Callback (you have to specify the callbackUrl)

2

Polling

3

Callback & polling (you have to specify the callbackUrl)

callbackUrl

This string parameter is only mandatory when resultType is set to 1 or 3. When the callbackUrl is set, this URL will be used by our system to submit status updates to you. This parameter is only allowed when the resultType parameter is set to 1 or 3.

Number Lookup status

You can check the status of a Number Lookup with a simple GET and specifying the ‘messageId’ returned in the submit of the Number Lookup:

String, not null. The datetime the Number Lookup was received by the API. The datetime is in ISO-8601 format.

imsi

String, can be null. The IMSI (International Mobile Subscriber Identity) of the SIM card the mobile number is linked to.

messageId

String, not null. The unique identifier, generated by the API, of the Number Lookup.

msc

String, can be null. The MSC (Mobile Switching Center) of the operator the mobile phone is currently registered to. This can be used to identify if a mobile phone is currently roaming or not.

networkCode

Integer, can be null. The network code of the operator the mobile number is subscribed to. The network code is the MCC (Mobile Country Code) and MNC (Mobile Network Code) concatenated.

number

String, not null. The phone number as specified when sending the Number Lookup.

operator

String, can be null. The name of the operator the mobile number is subscribed to.

reasonCode

Integer, can be null. When the Number Lookup is rejected or could not be performed a reasonCode is given explaining the cause of the rejection. See further down below for an overview of possible reasonCodes

resultType

The result type specified when sending the Number Lookup. Possible values are:

0

No results (default)

1

Callback (you have to specify the callbackUrl)

2

Polling

3

Callback & polling (you have to specify the callbackUrl)

salesPrice

Float, can be null. The sales price of the Number Lookup.

salesPriceCurrencyCode

String, can be null. The currency code of the salesPrice field. The value can be 'eur', 'usd' or 'sgd'. The currency code is defined by the currency of your wallet.

status

String, not null. The status of the Number Lookup. The status and statusCode fields are bound together and can have the following values:

0

no status

The Number Lookup is received by our system. This is a temporary status, a final status will follow later.

1

delivered

The Number Lookup is successfully performed.

2

rejected

The Number Lookup is rejected by the system and is not performed. The reasonCode field indicates the reason why it is rejected. See further down below for an overview of possible reasonCodes.

3

expired

The Number Lookup is expired as it could not be performed within the specified validity time.

4

enroute

The Number Lookup is on it's way in the mobile network and will be tried to perform at a later moment. This is a temporary status, a final status will follow later.

5

buffered

The Number Lookup is buffered in a queue in the mobile network and will be tried to perform at a later moment. This is a temporary status, a final status will follow later.

6

accepted

The Number Lookup is accepted by the mobile network and will be tried to perform at a later moment. This is a temporary status, a final status will follow later.

7

undelivered

The Number Lookup could not be performed.

8

deleted

The Number Lookup is deleted and will not be performed.

9

unknown

The Number Lookup could not be performed due to an unknown reason.

statusCode

Integer, not null. See 'status' field for more information.

tag

String, can be null. The tag as specified when sending the Number Lookup.

resultTimestamp

String, can be null. The timestamp when the Number Lookup was performed.

validity

Integer, not null. The validity in seconds as specified when sending the Number Lookup or the default value (60)

validUntilDateTime

String, can be null. The datetime until when the Number Lookup is valid. This is calculated by the API based on the validity field.

_links

HATEOAS (Hypermedia as the Engine of Application State) is a constraint of the REST application architecture. A hypermedia-driven site provides information to navigate the site's REST interfaces dynamically by including hypermedia links with the responses. See HATEOAS for more information.

The status of a Number Lookup can be checked 24 hours after the validity. After that the Number Lookup is removed from the API and you will receive a HTTP status code 404 Not Found. You can however still check the Number Lookup in the portal via Message details .

Number Lookup results

Apart from checking the status of a Number Lookup, you can also retrieve the results. Each time you check for results you will receive up to maximum 10 results at a time. When you received the results you will need to confirm them so that our system knows you receive them correctly. If you do not confirm them, after a timeout of 5 minutes, the same results will be available again. If you do not retrieve/confirm results, they will automatically be removed after 24 hours. When you are using one of our libraries or SDK's you do not have to confirm the delivery reports, it will be done for you, so you don't have to confirm.

You can confirm the delivery reports by doing a DELETE to our API with the ‘batchId’ returned from the GET call. When you are using one of our libraries or SDK's you do not have to confirm the delivery reports, it will be done for you, so you don't have to confirm.

Callback URL

When you have specified a callback URL, our system will HTTP POST that URL with the result. The result will be sent in JSON format, similar like when you check the status of a Number Lookup. You will have to respond to the call with HTTP status code 200 OK. If you respond with another HTTP status code we will try to call the URL again after some time. We will try to call the URL maximum 10 times with an increasing time interval where the last attempt is 72 hours after the first attempt.

Reason codes

When our API accepted a Number lookup but for example the number could not be found, a reason code is returned. The following reason codes can be returned: