Verify API

MessageBird's Verify API enables you to verify a mobile phone number 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 provided number.

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.

URI

https://rest.messagebird.com/verify

Available HTTP Methods

POST /verify
GET /verify/{verifyId}
DELETE /verify/{verifyId}

The Verify object

This object represents a One-Time Password, or verification token, at MessageBird.com

Attributes

AttributeTypeDescription
idstringA unique random ID which is created on the MessageBird platform and is returned upon creation of the object
hrefstringThe URL of the created object.
recipientintegerThe msisdn of the recipient
referencestringA client reference
messageshashA hash containing one href entry referring to the URL of the created object. The entry can either refer to either the messages or the voicemessages endpoint
statusstringThe status of the verification. Possible values: sent, expired, failed, verified, and deleted
createdDatetimedatetimeThe date and time of the creation of the Verify object in RFC3339 format (Y-m-d\TH:i:sP)
validUntilDatetimedatetimeThe 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,
"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"
}

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

ParameterTypeDescription
recipientintThe telephone number that you want to verify. Required

Optional parameters

ParameterTypeDescription
originatorstringThe sender of the message. This can be a telephone number (including country code) or an alphanumeric string. In case of an alphanumeric string, the maximum length is 11 characters.
Default: Code
referencestringA client reference
typestringThe type of message. Values can be: sms, flash, tts
Default: sms
templatestringThe template of the message body. Needs to contain %token for the verification code to be included.
Default: Your code is: %token
datacodingstringThe 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
timeoutintThe verification code expiry time in seconds. Default: 30
tokenLengthintThe number of characters in the verification code. Must be between 6 and 10. Default: 6
voicestringThe voice in which the messages needs to be read to the recipient. Possible values are: male, female.
languagestringThe 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.

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 test_gshuPaZoeEG6ovbc8M79w0QyM' -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"
}

Verify a token

Verifies a sent verification token. Can only be done once for each token.

ParameterTypeDescriptionrequired
idstringA unique random ID which is created on the MessageBird platform and is returned upon creation of the object.Yes
tokenstringAn unique token which was sent to the recipient upon creation of the object. RequiredYes

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

ParameterTypeDescriptionrequired
idstringA 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.

ParameterTypeDescriptionrequired
idstringA 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.

Definition

DELETE https://rest.messagebird.com/verify/{verifyId}

Example request

curl -X DELETE https://rest.messagebird.com/verify/4e213b01155d1e35a9d9571v00162985 \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Example response

[empty]
cURL
PHP
Node
C#
Java
Ruby
Go
Python
Cookie Settings