SimpleTexting API Documentation (2.0.0)

Download OpenAPI specification:Download

Introduction

Thousands of businesses rely on SimpleTexting to communicate with their audience via text message. With our API, developers can access many of our platform’s features and integrate them with other websites or applications. This document details the available SimpleTexting API functions and their parameters. For additional security, our API is by approval only. If you’d like access, sign up for a trial account and email [email protected] with details about your use case.

How it works

Our API is organized around REST. It uses standard HTTP response codes and authentication. Before you get started, there a few things to keep in mind:

  • When using the POST request, you must specify that content-type is application/json.

  • The default response for all requests is JSON. To use XML, you must change the value for the Accept request header to application/xml.

Authentication

Each time you make a request to our API, we use a bearer token in your header to authenticate your account. API requests without authentication will fail. Your API token can be found under settings.

Please be sure to keep your bearer token secure. Don’t share it any public areas such as GitHub, client-side code, etc.

bearerAuth

Bearer authentication (also called token authentication) is an authentication scheme that involves security tokens called bearer tokens. The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization: Bearer <token> header when making requests to protected resources. To understand more about bearer tokens, please take a look at the following resource.

Security Scheme Type bearer

Campaigns

Send and manage campaigns directly from the SimpleTexting API. The endpoint allows you to Create and Send a campaign, get a specific campaign by its name or id, or list all of your SimpleTexting campaigns.

Note: If the message contains a link from a common third-party link shortener such a bit.ly, it will appear from our URL shortener instead and occupy 20 characters. Learn more.

Get all Campaigns

Get all campaigns from the SimpleTexting system.

Example: We request all SENT campaigns sent from 8005551234 to the list My First List:

https://api-app2.simpletexting.com/v2/api/campaigns?page=100&size=2&accountPhone=8005551234&state=SENT&listNameOrId=My First List&startDateFrom=2021-04-28T23:20:08.489Z&startDateTo=2021-05-28T23:20:08.489Z

query Parameters
page
integer <int32> >= 0
Default: 0
Example: page=100

The number of campaigns returned with each request

size
integer <int32> <= 500
Default: 50
Example: size=2

The size of the page.

accountPhone
integer <int32>
Default: 0
Example: accountPhone=8005551234

The phone number the campaign was sent from

state
string
Default: "SENT"
Enum: "DRAFT" "PAUSED" "SENT" "SCHEDULED"
Example: state=SENT

The current state of the campaigns you wish to retrieve:

  • DRAFT: Returns all those campaigns in Draft mode

  • PAUSED: Returns Paused campaigns on your account

  • SENT: Returns all campaigns sent on your account

  • SCHEDULED: Returns any campaign you may have scheduled on your account

listNameOrId
string
Example: listNameOrId=My First List

The list name or list id

startDateFrom
string <date-time>
Example: startDateFrom=2021-04-28T23:20:08.489Z

List campaigns starting from a certain date. The time is in ISO 8601 format.

startDateTo
string <date-time>
Example: startDateTo=2021-05-28T23:20:08.489Z

List campaigns up to a certain date. The time is in ISO 8601 format.

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "totalPages": 0,
  • "totalElements": 0
}

Send a Campaign

Create and send a campaign

Example: Here we created a campaign from our short code 8005551234 and sent it to a segment identified here by its id, along with a list called My First List. We also specified that the First Name custom field will only take up 20 characters. Finally, we specified that 2 pieces of media will be attached. One is housed on SimpleTexting and identified by its id, the other is getting pulled from an external link:

{ "title": "My first campaign", "listsOrSegments": [ "507f191e810c19729de860ea", "My First List" ], "accountPhone": "8005551234", "customFieldsMaxLength": { "firstName": 20 }, "messageTemplate": { "title": "My first campaign", "subject": "My first campaign", "text": "Hi %%firstname%%, welcome to our campaign!", "fallbackText": "My first campaign", "mediaItems": [ "https://txt.so/img.jpg", "507f1f77bcf86cd799439011" ] } }

Request Body schema: application/json
title
required
string

Campaign title

Example: My first campaign

listsOrSegments
Array of strings

Lists or segments ids or names

Example: ["507f191e810c19729de860ea","My First List"]

accountPhone
string

Account phone, primary number is default

Example: 8005551234

object

Custom fields length in current campaign, overwrite default settings. See /custom-fields

Example: {"firstname":"20"}

required
object

Campaign Template

Example: { "mode": "MMS_PREFERRED", "subject": "My first campaign", "text": "Hi %%firstname%%, welcome to our campaign!", "fallbackText": "My first campaign", "unsubscribeText": "If you no longer wish to hear from us, reply STOP", "fallbackUnsubscribeText": "If you no longer wish to hear from us, reply STOP", "mediaItems": [ "https://txt.so/img.jpg", "507f1f77bcf86cd799439011" ] }

Responses

Request samples

Content type
application/json
{
  • "title": "My first campaign",
  • "listsOrSegments": [
    ],
  • "accountPhone": "8005551234",
  • "customFieldsMaxLength": {
    },
  • "messageTemplate": {
    }
}

Get a Campaign

Get a campaign via its unique id.

Example: Below we return the information associated with the campaign whose id is 507f1f77bcf86cd799439011. You can use the Get all Campaigns endpoint to retrieve campaign id's for all of your campaigns:

https://api-app2.simpletexting.com/v2/api/api/507f1f77bcf86cd799439011

path Parameters
campaignId
required
string
Example: 507f1f77bcf86cd799439011

Campaign id in hexadecimal format

Responses

Response samples

Content type
application/json
{
  • "campaignId": "607f0558a7c898629dd47d7a",
  • "title": "My first campaign",
  • "accountPhone": "8005551234",
  • "customFieldsMaxLength": {
    },
  • "state": "COMPLETED",
  • "listsOrSegments": [
    ],
  • "created": "2021-04-28T23:20:08.489Z",
  • "modified": "2021-04-28T23:20:08.489Z",
  • "started": "2021-04-28T23:20:08.489Z",
  • "finished": "2021-04-28T23:20:08.489Z",
  • "messageTemplate": {
    },
  • "origin": "API_V2",
  • "outcome": {
    },
  • "trackingLinks": [
    ]
}

Messages

In SimpleTexting, users can send and receive messages. With our API, this can be done programmatically.

Note: If the message contains a link from a common third-party link shortener such a bit.ly, it will appear from our URL shortener instead and occupy 20 characters. Learn more.

Get all Messages

Retrieves a list of all messages sent to a specific contact from a specific number on your account.

Example: Here we return all messages from an account:

https://api-app2.simpletexting.com/v2/api/messages?page=100&size=500

query Parameters
page
integer <int32> >= 0
Default: 0
Example: page=25

The number of messages returned with each request

size
integer <int32> <= 500
Default: 50
Example: size=50

The size of the page.

accountPhone
string
Example: accountPhone=8005551234

The phone number on your account the messages were sent to. If blank, the request will return the messages sent to the primary account phone

since
string <date-time>
Example: since=2021-04-28T23:20:08.489Z

First sent/received timestamp. The time is in ISO 8601 format.

contactPhone
string
Example: contactPhone=8001234567

The contact's phone number

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "totalPages": 0,
  • "totalElements": 0
}

Send a Message

Send either an MMS or SMS message to a contact. Use this programmatically to send to multiple contacts.

If the message contains a link from a common third-party link shortener such as bit.ly, it will appear from our URL shortener instead and occupy 20 characters. Learn more.

There are limitations on Media Files with MMS messages. The size limitations of these items are discussed here.

Example: Below, we have an example of an MMS message being sent. We specified that we wanted to send an MMS message to 1234567 from one of the numbers on our account - 8005551234. We also provided some fallback text, should the receiving cellphone be unable to receive an MMS, and provided a link/id to the media we wished to attach:

{ "contactPhone": "1234567890", "accountPhone": "8005551234", "mode": "MMS_STRICTLY", "text": "Hello! How are you?", "subject": "Some message from SimpleTexting", "fallbackText": "[url=%%fallback_link%%]", "mediaItems": [ "https://txt.so/img.jpg", "507f1f77bcf86cd799439011" ] }

Request Body schema: application/json
contactPhone
required
string

Contact's phone

Example: 1234567890

accountPhone
string

The account phone to send from. If this field is left blank, the primary account number will be used as a default

Example: 8005551234

mode
string
Enum: "AUTO" "SINGLE_SMS_STRICTLY" "MMS_STRICTLY"

Determines how your message will be presented:

  • AUTO: this means that SimpleTexting will find more relative types for your message content

  • SMS_STRICTLY: this will send only a single SMS or return an error

  • MMS: this will send a MMS or fallback SMS if MMS is not enabled by your contacts' carriers

Example: SINGLE_SMS_STRICTLY

AUTO is the default value for this field.

text
required
string

Text Body

Example: Hello! How are you?

subject
string

MMS Subject (available for MMS)

Example: Some message from SimpleTexting

fallbackText
string

Custom fallback text if mms cannot be received. Should contain '[url=%%fallback_link%%]' placeholder that will be replaced with a link to the message

Example: [url=%%fallback_link%%]

mediaItems
array

List of mms media urls for temporal storing or media items ids

Example: ["https://txt.so/img.jpg", "507f1f77bcf86cd799439011"]

Responses

Request samples

Content type
application/json
{
  • "contactPhone": "1234567890",
  • "accountPhone": "8005551234",
  • "mode": "MMS_STRICTLY",
  • "text": "Hello! How are you?",
  • "subject": "Some message from SimpleTexting",
  • "fallbackText": "[url=%%fallback_link%%]",
  • "mediaItems": []
}

Get a Message

Retrieve a specific message from the system via its message id.

Example: Below we return the information associated with the message whose id is 507f1f77bcf86cd799439011. You can use the Get all Messages endpoint to retrieve message id's for all of your messages:

https://api-app2.simpletexting.com/v2/api/messages/507f1f77bcf86cd799439011

path Parameters
messageId
required
string
Example: 507f1f77bcf86cd799439011

Message id in hexadecimal format

Responses

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "subject": "Some message from SimpleTexting",
  • "text": "Hello! How are you?",
  • "contactPhone": "8001234567",
  • "accountPhone": "8005551234",
  • "directionType": "MO",
  • "timestamp": "2020-04-28T23:20:08.489Z",
  • "referenceType": "API_SEND",
  • "category": "SMS",
  • "mediaItems": [
    ]
}

Evaluate a Message

Evaluate the body of your message before sending it to a contact or contacts.

Example: We evaluate a message to determine a number of properties. These include the number of credits it will use, whether it is an extended SMS or a regular SMS and any potential errors that may occur:

https://api-app2.simpletexting.com/v2/api/messages/evaluate

Request Body schema: application/json
text
required
string

Text Body

Example: Hello! How are you?

mode
string
Enum: "AUTO" "SINGLE_SMS_STRICTLY" "MMS_STRICTLY"

Determines how your message will be presented:

  • AUTO: this means that SimpleTexting will find more relative types for your message content

  • SMS_STRICTLY: this will send only a single SMS or return an error

  • MMS: this will send a MMS or fallback SMS if MMS is not enabled by your contacts' carriers' carrier

Example: SINGLE_SMS_STRICTLY

AUTO is the default value for this field.

Example: SINGLE_SMS_STRICTLY

subject
string

MMS Subject (available for MMS)

Example: New In Store

fallbackText
string

A custom fallback text if a contact can't receive a MMS message. It should contain a '[url=%%fallback_link%%]' placeholder that will be replaced with a link to the message.

Example: [url=%%fallback_link%%]

mediaItems
array

List of mms media urls for temporal storing or media items ids

Example: ["https://txt.so/img.jpg", "507f1f77bcf86cd799439011"]

Responses

Request samples

Content type
application/json
{
  • "text": "Hello! How are you?",
  • "mode": "MMS_STRICTLY",
  • "subject": "New In Store",
  • "fallbackText": "[url=%%fallback_link%%]",
  • "mediaItems": []
}

Response samples

Content type
application/json
{
  • "detectedCategory": "SMS",
  • "length": 134,
  • "remains": 23,
  • "maxLength": 150,
  • "unicode": true,
  • "sumOfCredits": 1,
  • "warnings": [
    ],
  • "errors": [
    ]
}

Media Items

When sending messages via the SimpleTexting platform, you may need to attach various media items. This API allows you to perform various operations needed to manage your media attachments. The size limitations of these items are discussed here.

Get Media Items

This endpoint allows you to retrieve all Media Items.

Example: Here we return all Media Items from an account:

https://api-app2.simpletexting.com/v2/api/mediaitems?page=100&size=500

query Parameters
page
integer <int32> >= 0
Default: 0
Example: page=29

Number of pages

size
integer <int32> <= 500
Default: 50
Example: size=50

Page size

Responses

Response samples

Content type
application/json
{}

Delete Media

Remove media that you have previously uploaded to SimpleTexting.

Example: Here we delete a Media Item whose id is507f1f77bcf86cd799439011. You can use the Get all Media Items endpoint to retrieve Media Items id's for all of your Media Items:

https://api-app2.simpletexting.com/v2/api/contact-lists/507f1f77bcf86cd799439011

path Parameters
mediaItemId
required
string
Example: 507f1f77bcf86cd799439011

The mediaItemId in hexadecimal format

Responses

Upload Media

Upload a media file from a local directory to SimpleTexting.

Example: Here we upload an image from our local directory using an HTTP request. We state that the media should be shared with teammates:

POST /api/mediaitems/upload?shared=true HTTP/1.1 Host: https://api-app2.simpletexting.com/v2/ accept: */* Authorization: Bearer {{YOUR_TOKEN}} Content-Length: 176 Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW ----WebKitFormBound

query Parameters
shared
boolean
Default: true

Define whether a media file is shared with teammates

Request Body schema: multipart/form-data
file
string <binary>

The media file you want to upload

Responses

Response samples

Content type
application/json
{}

File Information

We can accept a wide variety of file types over MMS. The industry standard maximum file size limit is 600KB for toll-free accounts and is 1MB on shortcode accounts.

We support the following file type: MPEG Audio, MPEG Video, MP4 Video, VCARDs, PDF

For popular image types we can accept media up to 15MB, our system will automatically compress these to the 600KB industry limitation. These media types include: JPEG, PNG, GIF

Contacts

At a minimum, each contact in SimpleTexting must have a phone number. Contacts can also hold additional information including first name, last name, and email address. You can also create custom fields to store data specific to your website or app’s needs.

Get all Contacts

For a given account, return all contacts that have been created in the account. A paginated list of contacts will be returned to you:

Example: Here we return all Contacts from an account since April 28th 2021:

https://api-app2.simpletexting.com/v2/api/contacts?page=100&size=2&since=2021-04-28T23:20:08.489Z&direction=ASC

query Parameters
page
integer <int32> >= 0
Default: 0
Example: page=250

The number of contacts returned with each request

size
integer <int32> <= 500
Default: 50
Example: size=150

The size of the page.

since
string <date-time>
Example: since=2021-04-28T23:20:08.489Z

List contacts updated since a specified date. The time is in ISO 8601 format.

direction
string
Default: "desc"
Enum: "ASC" "DESC"
Example: direction=desc

Specify the sort order of your results. By default, results are sorted by the 'updated' field:

  • ASC: Sort values in ascending order

  • DESC: Sort values in descending order

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "totalPages": 0,
  • "totalElements": 0
}

Create a Contact

Create a new contact and add them to a specific list.

Example: Below we created our contact, John Doe. We declared his custom field value for zipcode is 12345 and that he gets added to the list with an id 507f191e810c19729de860ea and another list called My First List:

{ "contactPhone": "1234567890", "firstName": "John", "lastName": "Doe", "email": "[email protected]", "birthday": "1985-05-05", "customFields": { "zipcode": "12345" }, "comment": "VIP client", "listIds": [ "507f191e810c19729de860ea", "My First List" ] }

query Parameters
upsert
boolean
Default: true

If a contact already exists with the phone number in your request body, the contact will be updated with the information in the request when upsert is set to true.

listsReplacement
boolean
Default: true

If listsReplacement is set to true, a contact will be removed from their existing list. If set to false, a contact will be added to a new list and stay in their original list.

Request Body schema: application/json
contactPhone
required
string

Contact's phone number

Example: 1234567890

firstName
string <= 100

Contact first name

Example: John

lastName
string <= 100

Contact last name

Example: Doe

email
string

Contact's email

Example: [email protected]

birthday
string

Contact's birthday in format (yyyy-mm-dd): yyyy-mm-dd

Example: 1985-05-05

object

Any custom field of a contact, where customField must be replaced with the actual custom field’s parameter. For example, if you have a Street address custom field, you would use the parameter street_address.

comment
string <= 1000

Notes about the contact.

Example: VIP client

listIds
array

All the lists (List ids or names) to add the contact to or replace.

Example: ["507f191e810c19729de860ea", "My First List"]

Responses

Request samples

Content type
application/json
{
  • "contactPhone": "1234567890",
  • "firstName": "John",
  • "lastName": "Doe",
  • "email": "[email protected]",
  • "birthday": "1985-05-05",
  • "customFields": {
    },
  • "comment": "VIP client",
  • "listIds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea"
}

Get a Contact

Get a contact via their unique id or phone number. Phone number is the preferred parameter for this call.

Example: Below we return the information associated with the Contact whose id is 507f1f77bcf86cd799439011. You can use the Get all Contacts endpoint to retrieve contact id's for all of your contacts:

https://api-app2.simpletexting.com/v2/api/messages/507f1f77bcf86cd799439011

path Parameters
phoneNumberOrContactId
required
string
Example: 3051234567 or 507f1f77bcf86cd799439011

Phone number (preferred) or Contact id in hexadecimal format

Responses

Response samples

Content type
application/json
{
  • "contactId": "607f0558a7c898629dd47d7a",
  • "contactPhone": "1234567890",
  • "firstName": "John",
  • "lastName": "Doe",
  • "email": "[email protected]",
  • "birthday": "1985-05-05",
  • "customFields": {
    },
  • "comment": "VIP client",
  • "lists": [
    ],
  • "subscriptionStatus": "OPT_IN",
  • "created": "2021-04-28T23:20:08.489Z",
  • "updated": "2021-05-28T20:20:08.489Z",
  • "updateSource": "IMPORTED_FROM_FILE"
}

Update a Contact

Update a contact’s phone number or any other field.

Example: Below we update our contact, 3051234567. We declared thier custom field value for zipcode is 12345 and that they get added to the list with an id 507f191e810c19729de860ea and another list called My First List. In our URL, we requested that the contact gets added to a new list while remaining on the current one. We also requested not to update the contact's information if they already exist within the system:

URL:

https://api-app2.simpletexting.com/v2/api/contacts/3051234567?listsReplacement=false&false

Request Body:

{ "contactPhone": "1234567890", "firstName": "John", "lastName": "Doe", "email": "[email protected]", "birthday": "1985-05-05", "customFields": { "zipcode": "12345" }, "comment": "VIP client", "listIds": [ "507f191e810c19729de860ea", "My First List" ] }

path Parameters
contactIdOrNumber
required
string
Example: 3051234567 / 507f1f77bcf86cd799439011

Contact id in hexadecimal format or the contact's phone number.

query Parameters
listsReplacement
boolean
Default: true

If listsReplacement is set to true, a contact will be removed from their existing list. If set to false, a contact will be added to a new list and stay in their original list.

upsert
boolean
Default: true

If a contact already exists with the phone number in your request body, the contact will be updated with the information in the request when upsert is set to true.

Request Body schema: application/json
contactPhone
string

Contact's phone number

Example: 1234567890

firstName
string <= 100

Contact's first name.

Example: John

lastName
string <= 100

Contact's last name

Example: Doe

email
string

Contact's email

Example: [email protected]

birthday
string

Contact's birthday in format (yyyy-mm-dd)

Example: 1985-05-05

object

Any custom field of a contact, where customField must be replaced with the actual custom field’s parameter. For example, if you have a Street address custom field, you would use the parameter street_address.

comment
string <= 1000

Notes about the contact.

Example: VIP client

listIds
array

All the lists (List ids or names) to add the contact to or replace.

Example: ["507f191e810c19729de860ea", "My First List"]

Responses

Request samples

Content type
application/json
{
  • "contactPhone": "1234567890",
  • "firstName": "John",
  • "lastName": "Doe",
  • "email": "[email protected]",
  • "birthday": "1985-05-05",
  • "customFields": {
    },
  • "comment": "VIP client",
  • "listIds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea"
}

Delete a Contact

Delete a contact via their unique id or phone.

Example: Here we delete a Contact whose id is507f1f77bcf86cd799439011. You can use the Get all Contacts endpoint to retrieve Contact id's for all of your Contacts:

https://api-app2.simpletexting.com/v2/api/webhooks/507f1f77bcf86cd799439011

path Parameters
contactIdOrNumber
required
string
Example: 507f1f77bcf86cd799439011

Contact id in hexadecimal format or phone number

Responses

Contacts - Batch Operations

An endpoint to assist in batch operations on your contacts. Using these operations, you can update specific contact information, or delete contacts, all using the contacts phone as an id.

Update a group of contacts

Update multiple fields at once for a batch of contacts. You can update their first name, last name, emails, lists, and more.

Example: Here we update two contacts, seen here in the array. The list replacement is set to true, so they will be removed from their existing list and added to a new one:

{ "updates": [ { "contactPhone": "1234567890", "firstName": "John", "lastName": "Doe", "email": "[email protected]", "birthday": "1985-05-05", "customFields": { "zipcode": "12345" }, "comment": "VIP client", "listIds": [ "507f191e810c19729de860ea", "My First List" ] },{ "contactPhone": "0987654321", "firstName": "Jane", "lastName": "Doe", "email": "[email protected]", "birthday": "1984-05-05", "customFields": { "zipcode": "54321" }, "comment": "VIP client", "listIds": [ "507f191e810c19729de860ea", "My First List" ] } ], "listsReplacement": true }

Request Body schema: application/json
required
Array of objects (ContactUpdate) [ 0 .. 500 ] items

List of updates for contacts

listsReplacement
boolean
Default: true

If listsReplacement is set to true, a contact will be removed from their existing list. If set to false, a contact will be added to a new list and stay in their original list.

Example: true

Responses

Request samples

Content type
application/json
{
  • "updates": [
    ],
  • "listsReplacement": true
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Delete a group of contacts

Delete a group of contacts from SimpleTexting using their phone numbers.

Example: Below, we delete a batch of contacts identified here by their phone number in the array:

{ "contactPhones": [ "1234567890", "0987654321", "1122334455" ] }

Request Body schema: application/json
contactPhones
required
Array of strings [ 0 .. 500 ] items

List of contacts' phone numbers for deletion

Example: ["1234567890","1234567891"]

Responses

Request samples

Content type
application/json
{
  • "contactPhones": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Contact Lists

Create, update, and delete contact lists.

Get all Lists

Retrieves all lists from your SimpleTexting account.

Example: Here we return all lists from an account:

https://api-app2.simpletexting.com/v2/api/contact-lists?page=100&size=2

query Parameters
page
integer <int32> >= 0
Default: 0
Example: page=15

The number of lists returned with each request

size
integer <int32> <= 500
Default: 50
Example: size=50

The size of the page.

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "totalPages": 0,
  • "totalElements": 0
}

Create a List

This endpoint is used to create a new contact list in a given SimpleTexting account.

Example: Here we create a list whose name is My New List:

{ "name": "My New List" }

Request Body schema: application/json
name
required
string

A list name containing less than 42 characters

Example: My new list

Responses

Request samples

Content type
application/json
{
  • "name": "My new list"
}

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea"
}

Get a List

Return a contact list by its unique list id.

Example: Below we return the information associated with the List whose id is 507f1f77bcf86cd799439011. You can use the Get all Lists endpoint to retrieve List id's for all of your Lists:

https://api-app2.simpletexting.com/v2/api/messages/507f1f77bcf86cd799439011

path Parameters
listId
required
string
Example: 507f1f77bcf86cd799439011

List id in hexadecimal format

Responses

Response samples

Content type
application/json
{
  • "listId": "507f191e810c19729de860ea",
  • "name": "My First List",
  • "created": "2021-04-28T23:20:08.489Z",
  • "updated": "2021-04-28T23:20:08.489Z",
  • "description": "List for 'SALE' keyword",
  • "totalContactsCount": 25,
  • "activeContactsCount": 40,
  • "invalidContactsCount": 1,
  • "unsubscribedContactsCount": 2,
  • "keywords": [
    ]
}

Update a List Name

Update the name of an existing list.

Example: Here we updated a list name with a new name My Newer List:

{ "name": "My Newer List" }

path Parameters
listId
required
string
Example: 507f1f77bcf86cd799439011

List id in hexadecimal format

Request Body schema: application/json
name
required
string

A list name containing less than 42 characters

Example: My new list

Responses

Request samples

Content type
application/json
{
  • "name": "My new list"
}

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea"
}

Delete a List

Delete an existing list using the list id.

Example: Here we delete a List whose id is507f1f77bcf86cd799439011. You can use the Get all Lists endpoint to retrieve List id's for all of your Lists:

https://api-app2.simpletexting.com/v2/api/contact-lists/507f1f77bcf86cd799439011

path Parameters
listId
required
string
Example: 507f1f77bcf86cd799439011

List id in hexadecimal format

Responses

Contact Segments

Get all of the segments on a given SimpleTexting account.

Get all Segments

Retrieves all segments from your SimpleTexting account.

Example: Here we return all segments from an account:

https://api-app2.simpletexting.com/v2/api/contact-segments?page=100&size=2

query Parameters
page
integer <int32> >= 0
Default: 0

The page number to load.

size
integer <int32> <= 500
Default: 50
Example: size=50

The size of the page.

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "totalPages": 0,
  • "totalElements": 0
}

Custom Fields

SimpleTexting's Custom Fields feature plays a key role in managing your customer data. Not only does it give you enormous flexibility when it comes to collecting or importing data, it also lets you quickly and easily personalize each message in a mass text campaign.

Get all Custom Fields

This endpoint allows you to retrieve all custom fields.

Example: Here we return all Custom Fields from an account:

https://api-app2.simpletexting.com/v2/api/custom-fields?page=100&size=500

query Parameters
page
integer <int32> >= 0
Default: 0
Example: page=40

The number of custom fields returned with each request

size
integer <int32> <= 500
Default: 50
Example: size=50

The size of the page.

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "totalPages": 0,
  • "totalElements": 0
}

Webhooks

Use webhooks to communicate between the SimpleTexting platform and your server. Webhooks can be used to forward messages as well as provide info about unsubscribes and message delivery.

SimpleTexting can trigger webhooks for new incoming messages, delivery reports, unsubscribes, and more. Now you can build scripts that interpret and respond to events that occur in your SimpleTexting account! To set the URLs for your webhooks, visit the Webhooks tab on the API section of settings.

Get all Webhooks

Retrieve all the webhooks that you've created.

Example: Here we return all Webhooks from an account:

https://api-app2.simpletexting.com/v2/api/webhooks

query Parameters
page
integer <int32> >= 0
Default: 0
Example: page=5

The number of webhooks returned with each request

size
integer <int32> <= 500
Default: 50
Example: size=50

The size of the page.

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "totalPages": 0,
  • "totalElements": 0
}

Create a Webhook

Create a new webhook from scratch

Request Body schema: application/json
url
required
string

The URL for handling a POST request

Example: https://example.com

triggers
required
Array of strings
Items Enum: "INCOMING_MESSAGE" "OUTGOING_MESSAGE" "DELIVERY_REPORT" "NON_DELIVERED_REPORT" "UNSUBSCRIBE_REPORT"

Trigger a webhook based on a specific platform event:

  • INCOMING_MESSAGE: Trigger a webhook event based on an incoming message

  • OUTGOING_MESSAGE: Trigger a webhook event based on an outgoing message

  • DELIVERY_REPORT: Trigger a webhook when a delivery confirmation is received from a contact

  • NON_DELIVERED_REPORT: Trigger a webhook when a failed delivery is reported from a contact

  • UNSUBSCRIBE_REPORT: Trigger a webhook when a contact unsubscribes

Example: UNSUBSCRIBE_REPORT

requestPerSecLimit
required
integer <int32> <= 25

The maximum number of requests that can be sent within a second

Example: 15

accountPhone
string

Optional: requests will come exclusively for the specified account phone number

Example: 8881234567

contactPhone
string

Optional: requests will come exclusively for the specified contact's phone number

Example: 3051234567

Responses

Request samples

Content type
application/json
{
  • "triggers": [
    ],
  • "requestPerSecLimit": 15,
  • "accountPhone": "8881234567",
  • "contactPhone": "3051234567"
}

Update a Webhook

Update an existing webhook using its unique id.

path Parameters
webhookId
required
string
Example: 507f1f77bcf86cd799439011

Webhook id in hexadecimal format

Request Body schema: application/json
url
required
string

The URL for handling a POST request

Example: https://example.com

triggers
required
Array of strings
Items Enum: "INCOMING_MESSAGE" "OUTGOING_MESSAGE" "DELIVERY_REPORT" "NON_DELIVERED_REPORT" "UNSUBSCRIBE_REPORT"

Trigger a webhook based on a specific platform event:

  • INCOMING_MESSAGE: Trigger a webhook event based on an incoming message

  • OUTGOING_MESSAGE: Trigger a webhook event based on an outgoing message

  • DELIVERY_REPORT: Trigger a webhook when a delivery confirmation is received from a contact

  • NON_DELIVERED_REPORT: Trigger a webhook when a failed delivery is reported from a contact

  • UNSUBSCRIBE_REPORT: Trigger a webhook when a contact unsubscribes

Example: UNSUBSCRIBE_REPORT

requestPerSecLimit
required
integer <int32> <= 25

The maximum number of requests that can be sent within a second

Example: 15

accountPhone
string

Optional: requests will come exclusively for the specified account phone number

Example: 8881234567

contactPhone
string

Optional: requests will come exclusively for the specified contact's phone number

Example: 3051234567

Responses

Request samples

Content type
application/json
{
  • "triggers": [
    ],
  • "requestPerSecLimit": 15,
  • "accountPhone": "8881234567",
  • "contactPhone": "3051234567"
}

Delete a Webhook

Delete an exsisting Webhook by its unique id.

Example: Here we delete a Webhook whose id is507f1f77bcf86cd799439011. You can use the Get all Webhooks endpoint to retrieve message id's for all of your Webhooks:

https://api-app2.simpletexting.com/v2/api/webhooks/507f1f77bcf86cd799439011

path Parameters
webhookId
required
string
Example: 507f1f77bcf86cd799439011

Webhook id in hexadecimal format

Responses

Webhook Reports

Use webhooks to communicate between the SimpleTexting platform and your server. Webhooks can be used to forward messages as well as provide info about unsubscribes and message delivery. SimpleTexting can trigger webhooks for new incoming messages, delivery reports and unsubscribes.

Incoming/Outgoing Message Report

Triggers when an outgoing message or Incoming message is handled.

Example: We create the incoming webhook for 8005551234 from contact phone 8001234567:

{"url": "http://www.yourdomain.com/receivesms.php","triggers": ["INCOMING_MESSAGE"],"requestPerSecLimit": 25,"accountPhone": "8005551234","contactPhone": "8001234567"}

Request Body schema: application/json
reportId
string

Unique report id in hexadecimal format

Example: 507f191e810c19729de860ea

webhookId
string

Webhook id in hexadecimal format

Example: 507f191e810c19729de860ea

type
string
Enum: "INCOMING_MESSAGE" "OUTGOING_MESSAGE"

Webhook report content type:

  • INCOMING_MESSAGE: Triggered when an incoming message is received

  • OUTGOING_MESSAGE: Triggered when an outgoing message is received

Example: OUTGOING_MESSAGE

object

report content

Request samples

Content type
application/json
{
  • "reportId": "507f191e810c19729de860ea",
  • "webhookId": "507f191e810c19729de860ea",
  • "type": "INCOMING_MESSAGE",
  • "values": {
    }
}

Delivery/Non Delivered Message Report

Triggers when an outgoing message is reported as delivered or undelivered by the carrier.

Example: We create the Delivery report for 8005551234 for the status of the outgoing messages to 8001234567:

{"url": "http://www.yourdomain.com/receivesms.php","triggers": ["INCOMING_MESSAGE"],"requestPerSecLimit": 25,"accountPhone": "8005551234","contactPhone": "8001234567"}

Your custom domain http://www.yourdomain.com/delivery.php has been set as delivery report webhook for this example. The SimpleTexting server will invoke the given call when a message with the messageId 507f191e810c19729de860ea is delivered.

Request Body schema: application/json
reportId
string

Unique report id in hexadecimal format

Example: 507f191e810c19729de860ea

webhookId
string

Webhook id in hexadecimal format

Example: 507f191e810c19729de860ea

type
string
Enum: "DELIVERY_REPORT" "NON_DELIVERY_REPORT"

Webhook report content type:

  • DELIVERY_REPORT: Triggered when a delivery confirmation is received from your contacts' carrier

  • NON_DELIVERY_REPORT: Triggered when a failed delivery is reported from your contacts' carrier

Example: NON_DELIVERY_REPORT

object

report content

Request samples

Content type
application/json
{
  • "reportId": "507f191e810c19729de860ea",
  • "webhookId": "507f191e810c19729de860ea",
  • "type": "NON_DELIVERY_REPORT",
  • "values": {
    }
}

Unsubscribe Report

Triggers when client send STOP to your number.

Example: We create the Unsubscribe report for 8005551234 for the status of the outgoing messages to 8001234567:

{"url": "http://www.yourdomain.com/receivesms.php","triggers": ["UNSUBSCRIBE_REPORT"],"requestPerSecLimit": 25,"accountPhone": "8005551234","contactPhone": "8001234567"}

Your custom domain http://www.yourdomain.com/delivery.php has been set as unsubscribe report URL for this example. The SimpleTexting server will invoke the given call when the subscriber with the number 8001234567 unsubscribes.

Request Body schema: application/json
reportId
string

Unique report id in hexadecimal format

Example: 507f191e810c19729de860ea

webhookId
string

Webhook id in hexadecimal format

Example: 507f191e810c19729de860ea

type
string
Value: "UNSUBSCRIBE_REPORT"

Webhook report content type:

UNSUBSCRIBE_REPORT: Triggered when a contact unsubscribes

Example: UNSUBSCRIBE_REPORT

object

report content

Request samples

Content type
application/json
{
  • "reportId": "507f191e810c19729de860ea",
  • "webhookId": "507f191e810c19729de860ea",
  • "type": "UNSUBSCRIBE_REPORT",
  • "values": {
    }
}