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",
		"balance": "123.45",
	}
}

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.
    • carrierID - The carrier ID of the mobile number this message was sent to
    • carrierName - The plain text name of the carrier (i.e. Verizon Wireless)
    • validNumber - True/False showing whether or not the number is valid
    • numberType - Can be one of M/L/VM/VL.
      • M - Mobile
      • L - Landline
      • VM - VoIP Mobile
      • VL - VoIP Landline
    • numberCountry - The country the number is registered in (i.e. United States)

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

Campaign Registry – Create Brand

  • Method: POST
  • Path: /brands
  • Parameters:
    • entityType: (required) string, predefined values only: "PRIVATE_PROFIT", "PUBLIC_PROFIT", "NON_PROFIT", "GOVERNMENT"
    • displayName: (required) string, name identifier for the desired brand
    • companyName: (required): string, name identifier of the company that will own the brand
    • ein: (required) string, 9 digit company ein format: "123456789"
    • phone: (required) string, 11 digit company phone number
    • street: (required) string, street address of company
    • city: (required) string, city of the address of the company in question
    • state: (required) string, state of the address of the company in question
    • postalCode: (required) string, postal code of the address of the company in question
    • country: (required) string, country of the address of the company in question
    • vertical: (required) string, predefined values only
      • "PROFESSIONAL"
      • "REAL_ESTATE"
      • "HEALTHCARE"
      • "HUMAN_RESOURCES"
      • "ENERGY"
      • "ENTERTAINMENT"
      • "RETAIL"
      • "TRANSPORTATION"
      • "AGRICULTURE"
      • "INSURANCE"
      • "POSTAL"
      • "EDUCATION"
      • "HOSPITALITY"
      • "FINANCIAL"
      • "POLITICAL"
      • "GAMBLING"
      • "LEGAL"
      • "CONSTRUCTION"
      • "NGO"
      • "MANUFACTURING"
      • "GOVERNMENT"
      • "TECHNOLOGY"
      • "COMMUNICATION"
    • website: (required) website of the company responsible for the brand
    • callbackURL: string, address to send webhook event to on success of brand creation, optional

Response

{
	"result": {
		"status": "Queued"
	}
}

Campaign Registry – Create Campaign

  • Method: POST
  • Path: /campaigns
  • Parameters:
    • campaignName: (required) string, name identifier of campaign,
    • usecase: (required) string, predetermined values only,
      • "2FA"
      • "ACCOUNT_NOTIFICATION"
      • "AGENTS_FRANCHISES"
      • "CARRIER_EXEMPT"
      • "CHARITY"
      • "CONVERSATIONAL"
      • "CUSTOMER_CARE"
      • "DELIVERY_NOTIFICATION"
      • "EMERGENCY"
      • "FRAUD_ALERT"
      • "HIGHER_EDUCATION"
      • "LOW_VOLUME"
      • "MARKETING"
      • "MIXED"
      • "POLITICAL"
      • "POLLING_VOTING"
      • "PUBLIC_SERVICE_ANNOUNCEMENT"
      • "SECURITY_ALERT"
      • "SOCIAL"
      • "SWEEPSTAKE"
      • "TRIAL"
    • description: (required) string, description of use case of the campaign,
    • sample1: (required) string, the primary sample for the campaign,
    • sample2: (required) string, the secondary sample for the campaign,
    • sample3: string, an optional third sample,
    • sample4: string, an optional fourth sample,
    • sample5: string, an optional fifth sample,
    • vertical: (required) string, predetermined values only,
      • "PROFESSIONAL"
      • "REAL_ESTATE"
      • "HEALTHCARE"
      • "HUMAN_RESOURCES"
      • "ENERGY"
      • "ENTERTAINMENT"
      • "RETAIL"
      • "TRANSPORTATION"
      • "AGRICULTURE"
      • "INSURANCE"
      • "POSTAL"
      • "EDUCATION"
      • "HOSPITALITY"
      • "FINANCIAL"
      • "POLITICAL"
      • "GAMBLING"
      • "LEGAL"
      • "CONSTRUCTION"
      • "NGO"
      • "MANUFACTURING"
      • "GOVERNMENT"
      • "TECHNOLOGY"
      • "COMMUNICATION"
    • callbackURL: string, an optional webhook address to send an event to on success of campaign creation
    • brandId: string, optionally specified brand used when an account has more than one brand to manage
    • subUsecases: array of multiple USECASE strings, optional parameter only used in MIXED use cases.

Response

{
	"result": {
		"status": "Queued"
	}
}

Get our Newsletter

Close Bitnami banner