Verify API
MessageBird's Verify API enables you to verify a mobile phone number or email with two-factor authentication. Create a new Verify object through the API to start the verification process of a recipient. MessageBird will take care of creating a token and making sure that the message gets delivered to the recipient.
The Verify API uses HTTP verbs and a RESTful endpoint structure with an access key that is used as the API Authorization. Request and response payloads are formatted as JSON using UTF-8 encoding and URL encoded values.
The Verify object
This object represents a One-Time Password, or verification token, at MessageBird.com
Attributes
| Attribute | Type | Description |
|---|---|---|
| id | string | A unique random ID which is created on the MessageBird platform and is returned upon creation of the object |
| href | string | The URL of the created object. |
| recipient | string | The msisdn of the recipient or email. |
| originator | string | The msisdn of the originator or email. |
| reference | string | Your reference. Must be alphanumeric. |
| type | string | Your type of message. Values can be: sms, flash, tts, email |
| status | string | The status of the verification. Possible values: sent, expired, failed, verified, and deleted |
| messages | hash | A hash containing one id and href entry referring to the URL of the created object. The entry can either refer to either the messages, voicemessages or the verify/messages/email endpoints. To know the status of delivery of the respective message use one of those endpoints |
| createdDatetime | datetime | The date and time of the creation of the Verify object in RFC3339 format (Y-m-d\TH:i:sP) |
| validUntilDatetime | datetime | The date and time indicating the expiration time of the Verify object in RFC3339 format (Y-m-d\TH:i:sP) |
Object example
{"id": "4e213b01155d1e35a9d9571v00162985","href": "https://rest.messagebird.com/verify/4e213b01155d1e35a9d9571v00162985","recipient": 31612345678,"originator": 31612345678,"type": "sms","reference": null,"messages": {"id": "31bce2a1155d1f7c1db9df6b32167259","href": "https://rest.messagebird.com/messages/31bce2a1155d1f7c1db9df6b32167259"},"status": "sent","createdDatetime": "2016-05-03T14:26:57+00:00","validUntilDatetime": "2016-05-03T14:27:27+00:00"}
Request a verify
Creates a new Verify object and sends a verification token to a recipient. MessageBird returns the created Verify object with each request.
Required parameters
| Parameter | Type | Description |
|---|---|---|
| recipient | string | The telephone number or email that you want to verify. Required |
Optional parameters
| Parameter | Type | Description |
|---|---|---|
| originator | string | The sender of the message. This can be email (channel should be created for that domain name) or a telephone number (including country code) or an alphanumeric string. In case of an alphanumeric string, the maximum length is 11 characters. Default: Code |
| reference | string | A client reference. Must be alphanumeric. |
| type | string | The type of message. Values can be: sms, flash, tts, email Default: sms |
| template | string | The template of the message body. Needs to contain %token for the verification code to be included. Default: Your code is: %token |
| datacoding | string | The datacoding used by the template, can be plain (GSM 03.38 characters only), unicode (contains non-GSM 03.38 characters) or auto, we will then set unicode or plain depending on the body content. Default: plain |
| timeout | int | The time in seconds it takes the OTP code to expire. You could set that parameter to value that works better for you between 30 and 172801 seconds (2 days) Default: 30 |
| tokenLength | int | The number of characters in the verification code. Must be between 6 and 10. Default: 6 |
| maxAttempts | int | The maximum number of token input attempts a user can do before the Verify object is marked as failed. Must be between 1 and 10. Default: 1 |
| voice | string | The voice in which the messages needs to be read to the recipient. Possible values are: male, female. |
| language | string | The language in which the message needs to be read to the recipient. Possible values are: cy-gb,da-dk,de-de,el-gr,en-au,en-gb,en-gb-wls,en-in,en-us,es-es,es-mx,es-us,fr-ca,fr-fr,id-id,is-is,it-it,ja-jp,ko-kr,ms-my,nb-no,nl-nl,pl-pl,pt-br,pt-pt,ro-ro,ru-ru,sv-se,ta-in,th-th,tr-tr,vi-vn,zh-cn,zh-hk. |
| subject | string | The subject of the email. Default: Your OTP token |
Response
Returns a Verify object if the request was successful. If the request failed, an error object will be returned.
Definition
POST https://rest.messagebird.com/verify
Example request
curl -X POST https://rest.messagebird.com/verify \-H 'Authorization: AccessKey YOUR_ACCESS_KEY' \-d "recipient=31612345678" \-d "originator=YourName"
Example response
{"id": "4e213b01155d1e35a9d9571v00162985","href":"https://rest.messagebird.com/verify/4e213b01155d1e35a9d9571v00162985","recipient": 31612345678,"reference": null,"messages": {"href":"https://rest.messagebird.com/messages/31bce2a1155d1f7c1db9df6b32167259"},"status": "sent","createdDatetime": "2016-05-03T14:26:57+00:00","validUntilDatetime": "2016-05-03T14:27:27+00:00"}
Example request for email
curl -X POST https://rest.messagebird.com/verify \-H 'Authorization: AccessKey YOUR_ACCESS_KEY' \-d "type=email" \-d "recipient=client-email@example.com" \-d "originator=verify@company.com" \# The originator email domain needs to be set up as an email channel in your account at https://dashboard.messagebird.com/en/channels/
Verify a token
Verifies a sent verification token. Can only be done once for each token.
| Parameter | Type | Description | required |
|---|---|---|---|
| id | string | A unique random ID which is created on the MessageBird platform and is returned upon creation of the object. | Yes |
| token | string | An unique token which was sent to the recipient upon creation of the object. Required | Yes |
Response
Returns a Verify object if the request was successful. If the request failed, an error object will be returned.
Definition
GET https://rest.messagebird.com/verify/{verifyId}?token={token}
Example request
curl -X GET "https://rest.messagebird.com/verify/4e213b01155d1e35a9d9571v00162985?token=123456" \-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'
Example response
{"id": "4e213b01155d1e35a9d9571v00162985","href":"https://rest.messagebird.com/verify/4e213b01155d1e35a9d9571v00162985","recipient": 31612345678,"reference": null,"messages": {"href":"https://rest.messagebird.com/messages/31bce2a1155d1f7c1db9df6b32167259"},"status": "sent","createdDatetime": "2016-05-03T14:26:57+00:00","validUntilDatetime": "2016-05-03T14:27:27+00:00"}
View a Verify object
Retrieves the information of an existing Verify object. You only need to supply the unique id that was returned upon creation.
Required parameters
| Parameter | Type | Description | required |
|---|---|---|---|
| id | string | A unique random ID which is created on the MessageBird platform and is returned upon creation of the object. | Yes |
Response
Returns a Verify object if the request was successful. If the request failed, an error object will be returned.
Definition
GET https://rest.messagebird.com/verify/{verifyId}
Example request
curl -X GET https://rest.messagebird.com/verify/4e213b01155d1e35a9d9571v00162985 \-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'
Example response
{"id": "4e213b01155d1e35a9d9571v00162985","href":"https://rest.messagebird.com/verify/4e213b01155d1e35a9d9571v00162985","recipient": 31612345678,"reference": null,"messages": {"href":"https://rest.messagebird.com/messages/31bce2a1155d1f7c1db9df6b32167259"},"status": "sent","createdDatetime": "2016-05-03T14:26:57+00:00","validUntilDatetime": "2016-05-03T14:27:27+00:00"}
Delete a Verify object
Deletes an existing Verify object. You only need to supply the unique id that was returned upon creation.
| Parameter | Type | Description | required |
|---|---|---|---|
| id | string | A unique random ID which is created on the MessageBird platform and is returned upon creation of the object. | Yes |
Response
Returns an HTTP header of 204 No Content and an empty response if the request was successful. If the request failed, an error object will be returned.
Is this page useful?
Next upMms Messaging