API Documentation

This document is for version 1 of the API.

Introduction

The Texting For Less API is a REST API. It is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON will be returned in all responses from the API, including errors (though if you’re using one of our libraries, we will use exceptions to indicate an error).

Authentication

Overview

In order for an application to access the Texting For Less API, it needs to have a valid access token. The token is generated when a Texting For Less customer grants the application access to their account. An access token is currently valid for a period of 10 years, and the application needs to use it for each API call to the user’s Texting For Less resources. In simplest terms, you register your application with Texting For Less, parse a token from an HTTP response, and send the token to the Texting For Less API you wish to access. OAuth 2.0 lets a user authorize your application to access their private Texting For Less resources without having to share their log in credentials with your application.The OAuth 2.0 flows requires the following, which you can find in your Texting For Less account after you have registered for an account.

  1. Login to your Texting For Less account.

  2. Go to your settings page, click the integrations tab.

  3. Scroll down to the applications section, click ‘Create new application’ in the top right.

  4. Enter an application name and the redirect url (located on your server) and click 'Create Application’.

  5. A client id, consumer secret will be generated for you which are used to authenticate the application with Texting For Less.

Once the app is authenticated, and the Texting For Less user grants access to their account, the app receives an access_token to use when making API calls to that user’s account resources. The Texting For Less API supports the Server (authorization code) OAuth 2.0 authentication flows.

Request Permissions

Implementation Details

The OAuth2-specific endpoints you’ll need to worry about:

OAuth 2.0 Server Flow

The OAuth 2.0 server authentication flow is used whenever a Texting For Less account uses your integration for the first time. The Texting For Less user must login to their account and give permission to your application to access their Texting For Less account. The Server Authentication flow consists of 2 main transactions:

  • The app makes an authorization request.

    • The authorization server responds with an authorization code.
  • The app then makes an access token request using the authorization code.

  • The authorization server responds with an access token.

Authorization Request

Parameter Values Required Description
response_type code YES A value of code tells the authentication server it is sending an authorization code to a web server. It MUST be the code for server applications. (Scopes are below)
client_id YOUR_CLIENT_ID YES Identifies the app that is making the request to the server; this parameter MUST always be set to the exact value of the client id provider when creating an application.
redirect_uri YOUR_REDIRECT_URL YES Tells the Authorization Server where to send the user once access is granted. This must be the same redirect_uri that is associated with your applications when it was created.
scope Scopes YES A space delimited list of scopes
Scopes
campaigns.create campaigns.delete campaigns.update
campaigns.view contacts.create contacts.delete
contacts.update contacts.view coupons.create
coupons.delete coupons.update coupons.view
groups.create groups.delete groups.update
groups.view messages.create messages.unread.view
messages.update messages.view message.schedule.view
message.schedule.create message.schedule.update message.schedule.delete
optins.view phone-numbers.lookup carriers.view

Authorization Response

If the user grants the access request, the authorization server issues an authorization code and delivers it by adding it to the query component of the redirection URI.

Field Description
code Unique 27 character authorization code generated for the request. It is valid for 10 minutes, and must be exchanged for an access token in order to make API calls.
error Error label and description if an error condition is detected in the authentication request.

Access Token Request

After the application receives the authorization code, it must exchange it for an access token by making a call to the Token endpoint.

  1. The application requests an access token from the Texting For Less authentication server, providing its client_id, client_secret, redirect_URI and the authorization_code.

  2. The authorization server validates the client credentials, the authorization code, and the redirect_URI (it must match the redirect_uri used in the Authorization Request exactly, including any parameters added). If the validation is successful, the authorization server sends back an access token. The application needs to retain the access token and use it when making API calls on behalf of the user.

Parameter Values Required Description
grant_type authorization_code YES This parameter MUST always be set to 'authorization_code’
client_id your_API_KEY YES This parameter MUST always be set to the value of your_API_KEY
client_secret your_client_secret YES This parameter MUST always be set to the your_client_secret value associated with the API_key.
code unique_code YES MUST be set to the authorization code provided in the Authorization request response.
redirect_uri your_encoded_redirect_URI YES It must match the redirect URI used in the authorization request, including any parameters.

Access Token Response

Field Description
access_token hyphenated hexadecimal string used to make API calls to a users account.
expires_in 315359999 seconds - Tokens are currently valid for 10 years
token_type This is always set to Bearer

Personal Access Token

If you would like a quick way to experiment with the API or don't have a need for the authorization code redirect flow, you can create a personal access token.

Once you're logged in, use the following steps to generate a personal access token.

  1. Navigate to Settings -> Integrations tab -> Personal Access Tokens.

  2. Click "Create New Token" in the upper right corner of the Personal Access Tokens subsection.

  3. Enter a meaningful name for your reference in the future.

  4. Choose the scopes you would like to grant to this token.

  5. Click the "Create" button.

  6. A popup will display your new token, it will only be shown once so make sure it's stored in a safe place.

Filtering, Ordering & Pagination

Filtering

This API can filter returned collections based on provided query parameters.

For example, when requesting a list of contacts from the /v1/contacts endpoint, you may want to limit these to only those of a specific reward points. This could be accomplished with a request like GET /v1/contacts?filter[reward_points]=10.

Ordering

This API can sort returned collections. A generic query parameter sort is used to describe sorting rules. This parameter can take a list of comma separated field, each with a possible unary negative to imply descending sort order.

E.g. GET /v1/messages?sort=-created_at - Retrieves a list of messages in descending order by creation date.

Includes

On certain endpoints you can choose to include additional data by specifying an include query parameter.

E.g. GET /v1/groups/f82e541a-a4b1-11e8-a85f-127fd0971098/contacts?include[]=status&include[]=fields - Retrieves a list of contacts with the corresponding status and custom fields for each contact.

Pagination

To do pagination for list resources, the query string in the url should be used. The two parameters are ‘limit’ and ‘page’ with the default and max number of results being 100.

Example: GET /v1/groups/limit=20 - This will return 20 results per page. Under the ‘meta’ -> ‘pagination’ in the api response will have a few fields that are used for pagination. Total is the total number of records, per_page is essentially the limit parameter from the url. current_page and total_pages are self explanatory.

Under ‘links’ are the ‘next’ and ‘previous’ keys which are in the url to use and retrieve the next page of results. When paginating you can check if those keys exist.

curl https://api.textingforless.com/v1/groups?limit=2
 {
    "data": [
        {
            "id": "8075886f-5f3e-486a-97ba-9e91829732e1",
            "name": "My test group",
            "join_message": "My new message",
            "one_time_message": false,
            "always_send_join": false,
            "social_profiling": false,
            "email_new_contact": false,
            "created_at": "2014-07-10T00:01:01+0000",
            "updated_at": "2015-06-29T12:40:05+0000",
            "optin": {
                "id": "4e4b3bda-e68b-4981-a5c6-2ddffd52d059",
                "name": "Email",
                "description": "Text Email Address to confirm",
                "enabled": true
            }
        },
        {
            "id": "6d9265cc-a310-406d-8f7a-abe015ee561a",
            "name": "My test group 2",
            "join_message": "My new message 2",
            "one_time_message": false,
            "always_send_join": false,
            "social_profiling": false,
            "email_new_contact": false,
            "created_at": "2015-03-16T17:01:43+0000",
            "updated_at": "2015-06-18T14:09:52+0000",
            "optin": {
                "name": "Email",
                "description": "Text Email Address to confirm",
                "enabled": true
            }
        }
    ],
    "meta": {
        "pagination": {
            "total": 6,
            "count": 2,
            "per_page": 2,
            "current_page": 1,
            "total_pages": 2,
            "links": {
                "next": "https://api.textingforless.com/v1/groups?limit=2&page=2"
            }
        }
    }
}

HTTP Methods

This API uses HTTP verbs (methods) as following:

  • GET - Read - used to read (or retrieve) a representation of a resource,

  • POST - Create - used to create new resources. In particular, it's used to create subordinate resources.

  • PUT - Update/Replace - used for update capabilities, PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource. On successful request, replaces identified resource with the request body.

  • PATCH - Update/Modify - used for modify capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource.

  • DELETE - Delete - used to delete a resource identified by a URI.

Media Type

Where applicable this API MUST use the JSON content-type. Requests with a message-body are using plain JSON to set or update resource states.

Content-type: application/json and Accept: application/json headers SHOULD be set on all requests if not stated otherwise.

Representation of Date and Time

All exchange of date and time-related data MUST be done according to ISO 8601 standard and stored in UTC.

When returning date and time-related data YYYY-MM-DDThh:mm:ss.SSSZ format MUST be used.

Resource IDs

The ‘id’ fields will always be a UUID

Example

f82e541a-a4b1-11e8-a85f-127fd0971098

Status Codes and Errors

The Texting For Less API uses HTTP status codes to communicate with the API consumer.

  • 200 OK - Response to a successful GET, PUT, PATCH or DELETE.

  • 201 Created - Response to a POST that results in a creation.

  • 204 No Content - Response to a successful request that won't be returning a body (like a DELETE request).

  • 400 Bad Request - Malformed request; form validation errors.

  • 401 Unauthorized - When no or invalid authentication details are provided.

  • 402 Payment Required - You need to pay for campaign or contact messages.

  • 403 Forbidden - When authentication succeeded but authenticated user doesn't have access to the resource.

  • 404 Not Found - When a non-existent resource is requested.

  • 405 Method Not Allowed - Method not allowed.

  • 406 Not Acceptable - Could not satisfy the request Accept header.

  • 415 Unsupported Media Type - Unsupported media type in request.

  • 422 Unprocessable Entity - Usually a validation error.

  • 429 Too Many Requests - Rate limit reached.

  • 500 Internal Server Error - An error occurred on our server.

  • 503 Service Unavailable - We’re temporarily offline for maintenance. Please try again later.

  • 504 Gateway Timeout' - A 3rd party service has timed out. Please try again later.

Error response

The Texting For Less API returns both, machine-readable error codes and human-readable error messages in response body when an error is encountered.

Example

Validation Error
{
    "status": 422,
    "message": "A validation error occurred",
    "errors": {
        "phone_number": [
            "The contact already exists."
        ]
    }
}
Generic Error
{
    "status": 400,
    "message": "An error has occurred with your request and is unable to be processed.",
    "errors": {}
}

Request ID's

Each API request has an associated request id. You can find this in the response headers, under X-Request-Id. If you need to contact us regarding a specific request, this id can be helpful for debugging purposes.

Rate Limits

All requests to the API are rate limited to 1 request per second for each route. Each response contains 2 headers that can be used to manage the rate limit.

Header Value
X-RateLimit-Limit 60
X-RateLimit-Remaining 59

If the rate limit is exceeded, a HTTP status code of 429 will be returned.

Contacts

Contacts

Contacts are the subscribers you market to using campaigns and coupons.

GET /contacts List all contacts

Returns a list of contacts that were previously created or joined your list.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes
Filter Type
phone_number Exact
reward_points Exact
Include Example
carrier /v1/contacts?include=carrier

Example URI

GET https://api.textingforless.com/v1/contacts

POST /contacts Create a contact

To create a new contact within your account, you create a new contact object. Note that a SMS message will be sent to the provided phone number and they must opt-in in order for you to send messages to them.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

POST https://api.textingforless.com/v1/contacts

Contact

GET /contacts/{id} Retrieve a contact

Retrieves the details of an existing contact.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes
Include Example
carrier /v1/contacts?include=carrier

Example URI

GET https://api.textingforless.com/v1/contacts/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

PUT /contacts/{id} Update a contact

Updates the specified contact by setting the values of the parameters passed. Any parameters not provided will be left unchanged. If you send an empty array of groups, the contact will be removed from all groups. This request accepts only the arguments used in table below, the phone number of a contact cannot be changed.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

PUT https://api.textingforless.com/v1/contacts/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

DELETE /contacts/{id} Delete a contact

Delete a contact based on the provided ID.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

DELETE https://api.textingforless.com/v1/contacts/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

Contact

PATCH /contacts/unsubscribe Unsubscribe contacts

Unsubscribe a batch of up to 100 phone numbers per request.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

PATCH https://api.textingforless.com/v1/contacts/unsubscribe

Add Groups

POST /contacts/{id}/groups Add a group to a contact

Add a group to the specified contact.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

POST https://api.textingforless.com/v1/contacts/f82e541a-a4b1-11e8-a85f-127fd0971098/groups

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

Remove Group

DELETE /contacts/{id}/groups/{group} Remove group from contact

Remove a group from the specified contact.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

DELETE https://api.textingforless.com/v1/contacts/f82e541a-a4b1-11e8-a85f-127fd0971098/groups/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

group

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

Carriers

Carriers

Carrier are the network that contacts are on.

GET /carriers List all carriers

Returns a list of carriers.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

GET https://api.textingforless.com/v1/carriers

Carrier

GET /carriers/{id} Retrieve a carrier

Retrieves the details of a carrier.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

GET https://api.textingforless.com/v1/carriers/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

Groups

Groups

Groups are used to organize contacts.

GET /groups List all groups

Returns a list of groups you’ve previously created.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes
Include Details
keyword If a keyword exists on the group it will be an object, otherwise it will be null.

Example URI

GET https://api.textingforless.com/v1/groups

POST /groups Create a group

To create a new group to organize your contacts, you create a new group object.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

POST https://api.textingforless.com/v1/groups

Group

GET /groups/{id} Retrieve a group

Retrieves the details of a group that was previously created.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes
Include Details
keyword If a keyword exists on the group it will be an object, otherwise it will be null.

Example URI

GET https://api.textingforless.com/v1/groups/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

PUT /groups/{id} Update a group

Updates the specified group by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

PUT https://api.textingforless.com/v1/groups/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

Group Contacts

GET /groups/{id}/contacts Retrieve a group contacts

Retrieves the contacts of a group.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes
Filter Type
phone_number Exact
reward_points Exact
Include
status
groups
fields

Example URI

GET https://api.textingforless.com/v1/groups/f82e541a-a4b1-11e8-a85f-127fd0971098/contacts

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

Opt-in's

Opt-ins are used to confirm subscribers allow you to send them messages. They can also be used to collect subscriber data such as email addresses which can help you market to them further.

Opt-ins

GET /opt-ins List all opt-in's

Returns a list of opt-ins.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

GET https://api.textingforless.com/v1/opt-ins

Opt-in

GET /opt-ins/{id} Retrieve an opt-in

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

GET https://api.textingforless.com/v1/opt-ins/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

Campaigns

Campaigns are an easy way to help maintain brand loyalty, inform your contacts of what’s happening with your business or send promotional offers.

Campaigns

GET /campaigns List all campaigns

Returns a list of campaigns that were previously created.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

GET https://api.textingforless.com/v1/campaigns

POST /campaigns Create a campaign

Create a campaign to market to your contacts.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

POST https://api.textingforless.com/v1/campaigns

Campaign

GET /campaigns/{id} Retrieve a campaign

Retrieves the details of a campaign that was previously created.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

GET https://api.textingforless.com/v1/campaigns/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

PUT /campaigns/{id} Update a campaign

Updates the specified campaign by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

PUT https://api.textingforless.com/v1/campaigns/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

DELETE /campaigns/{id} Delete a campaign

You can delete a campaign only if it has not yet been sent or is in the process of sending.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

DELETE https://api.textingforless.com/v1/campaigns/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

Campaign templates

Campaign templates are an easy way to easily create new campaigns for common messages that you send to your contacts.

Campaign Templates

GET /campaigns/templates List all campaign templates

Returns a list of campaign templates that were previously created.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

GET https://api.textingforless.com/v1/campaigns/templates

POST /campaigns/templates Create a campaign template

Create a campaign template.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

POST https://api.textingforless.com/v1/campaigns/templates

Campaign Template

GET /campaigns/templates/{id} Retrieve a campaign template

Retrieves the details of a campaign template that was previously created.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

GET https://api.textingforless.com/v1/campaigns/templates/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

PUT /campaigns/templates/{id} Update a campaign

Updates the specified campaign template by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

PUT https://api.textingforless.com/v1/campaigns/templates/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

DELETE /campaigns/templates/{id} Delete a campaign

Delete a campaign template.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

DELETE https://api.textingforless.com/v1/campaigns/templates/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

Coupons

Coupons are a great way to entice customers to come back to your establishment. They can also be used as an incentive for customers to join your list.

Coupons

GET /coupons List all coupons

Returns a list of coupons that were previously created.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

GET https://api.textingforless.com/v1/coupons

POST /coupons Create a coupon

Create a coupon that can be sent to contacts.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

POST https://api.textingforless.com/v1/coupons

Coupon

GET /coupons/{id} Retrieve a coupon

Retrieves the details of a coupon that was previously created.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

GET https://api.textingforless.com/v1/coupons/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

PUT /coupons/{id} Update a coupon

Updates the specified coupon by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

PUT https://api.textingforless.com/v1/coupons/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

DELETE /coupons/{id} Delete a coupon

Delete a coupon.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

DELETE https://api.textingforless.com/v1/coupons/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

Coupon Templates

Coupon templates are used to define a coupon’s style and design.

Coupon Templates

GET /coupon_templates List all coupon templates

Returns a list of coupon templates that were previously created.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

GET https://api.textingforless.com/v1/coupon_templates

Coupon Template

GET /coupon_templates/{id} Retrieve a coupon template

Retrieves the details of a coupon template that was previously created.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

GET https://api.textingforless.com/v1/coupon_templates/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

Messages

Messages that have been sent to and from your account.

Messages

GET /messages List all messages

Returns a list of messages that were sent or received.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes
Filter Type Value(s)
type Exact unknown
Include Example
receipt /v1/messages?include=receipt
contact.carrier /v1/messages?include=contact.carrier
Combined /v1/messages?include=receipt,contact.carrier

Example URI

GET https://api.textingforless.com/v1/messages

Message

GET /messages/{id} Retrieve a message

Retrieves the details of a message that was sent or received.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes
Include Example
receipt /v1/messages?include=receipt
contact.carrier /v1/messages?include=contact.carrier
Combined /v1/messages?include=receipt,contact.carrier

Example URI

GET https://api.textingforless.com/v1/messages/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

PUT /messages/{id} Update a message

Updates the specified message by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

PUT https://api.textingforless.com/v1/messages/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

Messages

POST /messages Send an individual message to a contact

Send 1 message to 1 contact.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

POST https://api.textingforless.com/v1/messages

Message

Send messages to subscribers

Message

POST /message Send an individual message

Send 1 message to 1 phone number.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

POST https://api.textingforless.com/v1/message

Message Batch

POST /message/batch Send a batch of messages

Send a message to multiple phone numbers.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

POST https://api.textingforless.com/v1/message/batch

Scheduled Messages

Schedule messages to be delivered to subscribers at a later time.

Scheduled Messages

Schedule messages to be delivered at a later time.

GET /message/schedule List all scheduled messages

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

GET https://api.textingforless.com/v1/message/schedule

POST /message/schedule Create a scheduled message

Create a scheduled message by sending the phone number, message and the date the message should be sent.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

POST https://api.textingforless.com/v1/message/schedule

Schedule Message

GET /message/schedule/{id} Retrieve a scheduled message

Retrieves the details of a scheduled message that was previously created.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

GET https://api.textingforless.com/v1/message/schedule/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

PUT /message/schedule/{id} Update a scheduled message

Updates the specified scheduled message by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

PUT https://api.textingforless.com/v1/message/schedule/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

DELETE /message/schedule/{id} Delete a scheduled message

Delete a scheduled message.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

DELETE https://api.textingforless.com/v1/message/schedule/f82e541a-a4b1-11e8-a85f-127fd0971098

URI Parameters

id

string  (required)  Example: f82e541a-a4b1-11e8-a85f-127fd0971098

unique uuid.

Phone numbers

Phone number of the contact.

Phone numbers

POST /phone-numbers/lookup Lookup carrier

Do phone number lookup's and return the carrier's information. Maximum 10 phone numbers per request.

Endpoint information

Access
Requires authentication Yes
Has restricted scope Yes

Example URI

POST https://api.textingforless.com/v1/phone-numbers/lookup

Webhooks

There are a variety of webhooks we offer in our application.

Webhook Requests

Each webhook is sent with a HTTP POST request with the body of the request containing a JSON object.

Inbound Messages

Sends data about an inbound message from a particular contact.

Field Nullable Description
id false Contact ID
first_name true Contact first name
last_name true Contact last name
email true Contact email address
short_code true Number that the contact texted into
phone_number true Contact phone number
message true Message the contact sent
unsubscribed_at true Contact unsubscribe date and time
created_at false Contact creation date and time
updated_at false Contact last updated date and time
received_at false Date and time the message was received
{
  "id": "f82e541a-a4b1-11e8-a85f-127fd0971098",
  "first_name": null,
  "last_name": null,
  "email": null,
  "short_code": "64600",
  "phone_number": "+19999999999",
  "message": "This is an example message",
  "unsubscribed_at": null,
  "created_at": "2016-07-01T15:11:09.553Z",
  "updated_at": "2016-07-01T15:11:09.553Z",
  "received_at": "2016-07-01T15:11:09.553Z"
}

Unsubscribe Messages

Sends data about a contact that was unsubscribed.

Field Nullable Description
id false Contact ID
first_name true Contact first name
last_name true Contact last name
email true Contact email address
phone_number true Contact phone number
to false Number that the contact texted into
unsubscribed_at true Contact unsubscribe date and time
created_at false Contact creation date and time
updated_at false Contact last updated date and time
{
  "id": "f82e541a-a4b1-11e8-a85f-127fd0971098",
  "first_name": null,
  "last_name": null,
  "email": null,
  "phone_number": "+19999999999",
  "to": "64600",
  "unsubscribed_at": "2016-07-01T15:11:09.553Z",
  "created_at": "2016-07-01T15:11:09.553Z",
  "updated_at": "2016-07-01T15:11:09.553Z",
}

Delivery Reports

Sends delivery report data for each message that is sent to a contact.

List of possible status codes and messages.

Code Message
100 The message delivered successfully
101 The MSISDN is inactive or no longer active.
102 Fault in Number Portability Database or HLR of MSISDN range holder. Occurs more frequently if number ported more than once in certain countries.
103 Occurs when the MSC that a message has been sent to is not aware of the subscriber IMSI. Suggests HLR has not been updated or MSC malfunction.
104 It cannot be determined whether this message has been delivered or has failed due to lack of final delivery state information from the carrier.
105 Rejection due to failed authentication or filtering.
106 Destination number is not a valid mobile number or its routing cannot be determined.
107 Rejection due to subscription not supporting SMS.
108 Rejection due to subscription, handset or network not supporting SMS.
109 Rejection due to subscription or network not allowing SMS.
110 Subscriber handset is not logged onto the network due to it being turned off or out of coverage. Likely to have been unavailable for 12 hours or more.
111 Subscriber handset is not reachable on the network due to it being turned off or out of coverage. Likely to have very recently become unavailable.
112 Subscriber handset is not reachable on the network due to it being turned off or out of coverage. Likely to have been unavailable for several hours.
113 The MSC that the subscriber is currently registered to is experiencing a fault.
114 MSC is busy handling an existing transaction with the handset. The subscriber could be currently receiving an SMS at exactly the same time.
115 Receiving handset or equipment does not support SMS or an SMS feature. This is temporary because the subscriber could switch to a different device.
116 Rejection due to subscriber handset not having the memory capacity to receive the message. Likely to have been in state for 12 hours or more.
117 Rejection due to SS7 protocol or network failure.
118 Rejection due to subscriber network decoding error or signaling fault.
119 Rejection due to subscriber handset not having the memory capacity to receive the message. Likely to have run out of capacity recently.
120 Generic delivery failure
121 Internal SMSC error due to invalid message syntax.
122 Internal SMSC error caused by SS7 link/dialogue fault.
123 SMSC cannot decode the response received from destination network due to an encoding or protocol fault.
124 Subscriber network or signalling partner has terminated the signalling connection, preventing message transmission.
125 The reason of rejection for the message is Anti-Spam Rejection because of the content. Carrier identified this kind of traffic which has same marketing content as a spam and block it, this is a carrier based regulation.
126 Subscriber network not receiving packets from SMSC, or not responding to them. Alternatively, a 3rd party signalling partner may not be routing correctly.
127 Subscriber network or signalling partner has not responded to signalling connection setup or maintenance packets.
128 Subscriber network refuses signalling connection or message packet.
129 Signalling with destination network has been prevented by SMSC partner or signalling partner.
130 SMSC partner or 3rd party signalling partner has prevented messages being sent to this MSISDN or destination network.
131 SMSC partner has rejected the message due to an unacceptable message parameter.
132 SMSC partner could not process this message due to a platform fault, but it will be retired.
133 SMSC partner could not process this message due to a platform fault and it will not be retried.
134 SMSC partner cannot route this message currently, but it will be retried.
135 SMSC partner cannot route this message and it will not be retried.
136 Message is queued within REST API system and will be dispatched according to the rate of the account.
137 Message has been dispatched to SMSC.
138 SMSC rejected message. Retrying is likely to cause the same error.
139 An unexpected error caused the message to fail.
140 Message failed because of temporary delivery failure. Message can be retried.
141 One or more parameters in the message body has no mapping for this recipient.
142 Message was expired before reaching SMSC.
143 Message was canceled by user before reaching SMSC.
144 SS7 signalling link at destination network, SMSC, or 3rd party signalling partner is overloaded.
214 Subscriber network or signalling partner has rejected the signalling connection, preventing message transmission.
{
  "total_messages": 1,
  "statuses": [
    {
      "code": "100",
      "status": "The message delivered successfully.",
      "count": 1,
      "recipients": ["19999999999"],
      "success": true,
      "bounce": false
    }
  ],
  "messages": [
    {
      "id": "a8a2b40a-86ae-4a91-a61d-7b7ccfc4b148",
      "from": "+15555555555",
      "message": "This is an example message",
      "phone_number": "9999999999",
      "metadata": []
    }
  ]
}

Contact Status

Sends contact information when the status of a contact changes based on data received from carriers. The status field can have one of the following: suspended, deactivated, resumed, transferred

Field Nullable Description
id false Contact ID
first_name true Contact first name
last_name true Contact last name
email true Contact email address
phone_number false Contact phone number
previous_phone_number Only present in the transferred event
status false suspended, deactivated, resumed, or transferred
created_at false Contact creation date and time
updated_at false Contact last updated date and time
{
  "id": "f82e541a-a4b1-11e8-a85f-127fd0971098",
  "first_name": null,
  "last_name": null,
  "email": null,
  "phone_number": "+19999999999",
  "status": "deactivated",
  "created_at": "2016-07-01T15:11:09.553Z",
  "updated_at": "2016-07-01T15:11:09.553Z",
}

Bounced Message

Sends contact information when an outgoing message is detected as being a bounce based on data received from the carriers.

Field Nullable Description
id false Contact ID
first_name true Contact first name
last_name true Contact last name
email true Contact email address
phone_number false Contact phone number
unsubscribed_at true Contact unsubscribe date and time
bounces false Number of bounced messages
created_at false Contact creation date and time
updated_at false Contact last updated date and time
{
  "id": "f82e541a-a4b1-11e8-a85f-127fd0971098",
  "first_name": null,
  "last_name": null,
  "email": null,
  "phone_number": "+19999999999",
  "unsubscribed_at": "2016-07-01T15:11:09.553Z",
  "bounces": 2,
  "created_at": "2016-07-01T15:11:09.553Z",
  "updated_at": "2016-07-01T15:11:09.553Z",
}