Primal Connect


Primal Connect API

1.1 Sign Up
1.2 HTTP Methods
1.3 Data Format - JSON
1.4 Token Authentication
1.5 HTTP Response Codes

Using Our API

2.1 Send SMS
2.1.1 CURL Example Request
2.1.2 Java example code
2.2 Receive SMS
2.2.1 POST callback URL
2.2.2 GET callback URL 5

Primal Connect API

Representational state transfer (REST) or RESTful Web services are one way of providing interoperability between computer systems on the Internet. REST-compliant Web services allow requesting systems to access and manipulate textual representations of Web resources using a uniform and predefined set of stateless operations.

Primal Connect API is a Restful API which is built over lightweight REST framework Spark, embedding famous Jetty web server, and provides company or individual developer ability to send and receive Text and MMS over internet.

1.1 Sign Up Primal Connect

In order to use Primal Connect API, first, you have to sign up. Afterwards login to receive your Token and send a message.

1.2 HTTP Methods

Primal Connect API uses four HTTP methods when accessing API resources: GET, POST, PUT and DELETE.

The HTTP GET method is used to retrieve (or read) a representation of a resource such as account, SMS, MMS.

The PUT method is used to update an existing resource.

The POST method is used to create new resources.

1.3 Data Format - JSON

Primal Connect API responses all data in JSON format, and requires the HTTP content data in JSON format as well.

1.4 Token Authentication

Primal Connect API works with a token to secure authentication. You can generate a token from Primal Connect dashboard. To use the Token, you must put the following into the header for each API call. token: <token> Token is generated from Skynet, it is global unique 40-character token.

1.5 HTTP Response Codes

The following are examples of HTTP error codes that the API will generate when a correctly authenticated request fails:

400 - The request was formatted incorrectly, or one of the required fields contains invalid data
401 - Authentication failed or the user does not have permission to access the requested resource.
403 - The user is attempting to perform an action/request that is not allowed.
404 - The requested resource was not found.
405 - The requested method is not supported.
429 - Too many requests.
500 - General error or it is an unexpected error.

Other response codes include:
200 - Everything worked correctly.
201 - Everything worked correctly and public ID or location of the new resource is returned.

Using Our API

2.1 Send SMS

2.1.1 CURL Example Request:

2.1.2 Java Example Code:

Sending SMS with HttpClient
1. Download Apache HttpComponents
2. Create HttpClient and HttpPost request
3. Set Request Entity: JSON format
4. Execute Request
5. Print Response Code
6. Print Results

2.2 Receive SMS

In order to receive the replied SMS to your application, you need visit Primal Skynet to set up your application callback URL and Method.

For example:

2.2.1 POST callback URL

The SMS message is delivered in POST content with JSON format:

2.2.2 GET callback URL

The SMS message is appended into GET method as querying parameters: Note: text in query parameter is percent encoding (also called URL encoding).