SMS Gorilla HTTP API Documentation

The APIs all require BASIC authentication and will respond with JSON. When your account is provisioned you will be given a set of API Credentials to use.

Authentication

For reference on HTTP BASIC Authentication – https://en.wikipedia.org/wiki/Basic_access_authentication

API Base URL

https://api.smsgorilla.com

Send SMS

  • Method: POST
  • Path: /messages
  • Parameters:
    • to (required) – Expected to be full 11-digit phone number
    • from (required) – Expected to be full 11-digit number that is provisioned to your account.
    • body (required) – Up to 160 ASCII characters or 70 Unicode Characters.
    • callbackURL (optional) – A valid URL for SMSGorilla to post Message Status Updates to.

Response

{
	"result": {
		"id": "358e83d2-e479-48c2-a0dc-30a01d337bbe",
		"to": "12223334444",
		"from": "15556667777",
		"body": "My Awesome SMS Message",
		"status": "queued",
	}
}

Message Status Callback

An HTTP POST to your callbackURL will be sent for every action that SMSGorilla receives an alert on. Most often this will be a delivery receipt received from the mobile carrier. This request is sent as a normal Form (x-www-form-urlencoded) Post.

  • Method: POST
  • Sent to the URL specified in the callbackURL parameter of your message send
  • Parameters:
    • id - This matches the message ID you were given when you sent the message.
    • action - Always route_status
    • detail - The action received (Delivered, Failed, Sent, etc.)
    • reason - The reason that the above action was taken. Usually "SUCCESS"
    • reasonCode - If there is a particular "code" associated with the Reason we'll include that as well. Could offer more insight into failed messages.

Message Status

  • Method: GET
  • Path: /messages/status
  • Parameters:
    • id (required) – this is the message ID that you received when you originally sent the message.

Response

{
	"result": {
		"id": "6e5d42b5-205d-4d01-86b9-a89df99d23de",
		"to": "12223334444",
		"from": "15556667777",
		"body": "My Awesome SMS Message",
		"status": "sent",
		"events": [
		{
			"action": "received",
			"created": 1550874255716
		},
		{
			"action": "queued",
			"created": 1550874255724
		},
		{
			"action": "sent",
			"created": 1550874268169
		}
		]
	}
}

Account Balance

  • Method: GET
  • Path: /account/balance
  • Parameters: None

Response

{
	"result": {
	"balance": 299.971
}
				}

SMS Number – List

  • Method: GET
  • Path: /account/smsnumbers
  • Parameters:
    • skip (optional): How many records to skip for pagination.
    • o limit (optional): How many records you want back. Maximum of 100 records per api request.

Response

{
	"result": {
		"count": 6,
		"smsNumbers": [
		{
			"smsNumber": "15632026437",
			"purchased": 1551476829868,
			"route": "Route01"
		},
		{
			"smsNumber": "12025248865",
			"purchased": 1551740822414,
			"route": "Route01"
		},
		{
			"smsNumber": "18082785356",
			"purchased": 1551741528633,
			"route": "Route02"
		},
		{
			"smsNumber": "18082785343",
			"purchased": 1551741521663,
			"route": "Route02"
		},
		{
			"smsNumber": "15632026470",
			"purchased": 1551740484642,
			"route": "Route01"
		},
		{
			"smsNumber": "12024702358",
			"purchased": 1551741194656,
			"route": "Route01"
		}
		]
	}
}

SMS Number – Release

  • Method: POST
  • Path: /account/smsnumbers/release
  • Parameters:
    • smsNumber (required): The SMS Number you wish to release

Response

{
	"result": {
		{
			"smsNumber": "15632026440",
			"released": 1551722966316,
		} 
	}
}

Receive SMS

When an inbound message is received on one of your numbers we will forward it to your server using HTTP POST or GET. You can control this setting from inside your account here: Inbound Messages API. You can test your inbound message handling URL from the same Inbound Messages API page to make sure everything is working as expected.

  • Method: POST/GET
  • Sent to the URL configured inside your account
  • Parameters:
    • to: The number that the message was sent to
    • from: The number the message was sent from
    • body: The message body
    • received: Date/Time the message was received by our system