SMS Validation API

Verify phone ownership so customers can opt in to receive loyalty program messages through SessionM.

The SMS Validation API is no longer supported for new integrations.

The SMS Validation API contains two new complementary routes that work together to allow clients to verify phone ownership, which is necessary for opting in to receive messages about their loyalty programs through SessionM.

API Contingencies and Combinations:

You must create a customers before sending a code to that customer. Use the Standard Profile API to create customers and specify profile attributes.

This API has the following methods:

Create an SMS Validation Request
Create an SMS Validation Confirmation

Create an SMS Validation Request

Creates an SMS validation request for either a mobile device or a Web form. The client application sends a request to the endpoint shown below. Doing so, logs the customer's phone into our system and sends a message to the customer's phone with a code that is used in the confirmation endpoint detailed in Create an SMS Validation Confirmation.

Important to note that this API cannot send a validation request unless a global SMS campaign exists and the opt-in keyword for that global campaign is "YES".

Endpoints for Create an SMS Validation Request

REST Endpoints

POST /priv/v1/apps/:api_key/messaging_events/sms/validation/request

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters for Create an SMS Validation Request

Endpoint Parameter	Description
api_key	Supplied by the SessionM Platform. Necessary to authenticate any HTTP request to a SessionM API. The key is associated with an API secret, which ties the authentication to a specific application or web site within the organization. The SessionM Platform maintains each application or site as a digital property, which can be configured using the SessionM UI.

Request Object for Create an SMS Validation Request

This method supplies the SMS request validation object shown below:

JSON Request

{
    "external_id": "twiliofeb211",
    "to_phone_number": "13139711649",
    “message_text”: “Some message text prefixing validation code in sms: ”
}

Request Attributes for SMS Validation Request

Attribute	Type Required/Optional	Description
external_id	string required	External ID for customer.
to_phone_number	string required	Phone number being used to validate customer.
message_text	string optional	Whatever text you deem appropriate. "Validation Code: " is default.

Response Object for Create an SMS Validation Request

This method returns the response object shown below:

JSON Response

{
    "status": "OK"
}

Statuses and Errors for Create an SMS Validation Request

When this method makes a successful call to the platform, it returns a 200-level status code and a string that indicates ok. However, when the string returned is error, returned errors can be either method-specific or generic.

This method can return a few different 400-level errors in the following format:

{
    "status": "Bad Request",
    "message": "Message text for error"
}

Possible message text is detailed in this table:

Code	Reason
"required parameter `to_phone_number` missing"	Customer's phone number is missing.
"required parameter `validation_code` missing"	Customer's validation code is missing.
"Invalid validation code"	Validation code provided is not valid.

For information on the generic statuses and errors returned for any object, see Generic Statuses and Errors.

Create an SMS Validation Confirmation

Creates a confirmation for an SMS validation request pertaining to either a mobile device or a Web form. Once the validation request is sent to get the customer's phone number logged into the SessionM system, a message with a code is sent to the customer's phone. That code is used in the endpoint detailed below to confirm the customer's phone.

Endpoints for Create an SMS Validation Confirmation

REST Endpoints

POST /priv/v1/apps/:api_key/messaging_events/sms/validation/confirm

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters for Create an SMS Validation Confirmation

Endpoint Parameter	Description
api_key	Supplied by the SessionM Platform. Necessary to authenticate any HTTP request to a SessionM API. The key is associated with an API secret, which ties the authentication to a specific application or web site within the organization. The SessionM Platform maintains each application or site as a digital property, which can be configured using the SessionM UI.

Request Object for Create an SMS Validation Confirmation

This method supplies the SMS request validation object shown below:

JSON Request

{
    "external_id": "twiliofeb211",
    "to_phone_number": "13139711649",
    "validation_code": "383ue73733eee"
}

Request Attributes for SMS Validation Confirmation

Attribute	Type Required/Optional	Description
external_id	string required	External ID for customer.
to_phone_number	string required	Phone number being used to validate customer.
validation_code	string required	Validation code received on the mobile device.

Response Object for Create an SMS Validation Confirmation