Get Started

Learn the basics. Connect your application using Apifon’s API and optimize the communication with your customers.

To get started, you need to have an Account and an API Token on our platform, and use that Token within the HTTP headers for every request.

Introduction

These guidelines assist the connection of your application to the ADMS (Apifon Distributed Messaging System), allowing you to seamlessly communicate with customers anywhere in the world.

There are two ways of using Apifon’s services: The first one is via the SMPP protocol, which effectively links your application to the SMSC servers. To set up an SMPP bind, please contact here. The second one is via the HTTP interface, which enables your application to send out SMS and IM messages.

The following two images explain how the Apifon REST API messaging and callback services function: alt text

alt text

HTTP Methods

4 HTTP Methods are supported:

GET for data retrieval. GET endpoints will never modify your data.
POST for creating new resources.
PUT for updating existing resources.
DELETE for removing resources.

Versioning

Apifon's REST API supports API versioning. It uses URI versioning and deprecation of resources.

Versioning in the URI is placed before the resource in format vX - where X is the number of the version.

See the example below:

https://ars.apifon.com/services/api/v1

In case of a breaking change in the API, a new URI versioning will be established and documented.

Older versions may end up being deprecated and marked for removal.
It is strongly recommended not using deprecated resources as they may get removed in the future.

Callbacks

Callbacks for message delivery / status reports as well as reply callbacks from two-way messaging are sent from the following IP address/es. It is mostly used for whitelisting and securing the inbound traffic.

20.56.2.71

Parameters

There are four main categories of parameters for each endpoint in the REST API:

Path parameters
Query parameters
Request body
Response body

The API reference includes all available parameters for each possible request. See below an overview of the categories:

Path Parameters

In the API URL, resource names and unique identifiers help you figure out the structure of the requests. Resource names are immutable. However, resource identifiers are required. Thus, they are needed to be replaced with real values.

See the example below:

https://ars.apifon.com/services/api/v1/list/{list_id}/field/{field}

In this URL there is one resource (lists) and one subresource (field). There are also two path parameters that are needed to be replaced with real values (list_id and field).

NOTE: Path parameters are enclosed in { } in the API reference.

When these values are replaced, the final URL should look like this:

https://ars.apifon.com/services/api/v1/list/5ce4fcef7ed5cc3898208e67/field/date_BIRTHDAY

Query Parameters

Apifon REST API allows query parameters to be used for partial responses, result filtering, pagination and result sorting.

Partial Responses

Use the field parameter to reduce the amount of data transferred, by limiting the fields the API returns. For example, if not all details of the resource are needed, it is recommended to pass a comma-separated list. In this way, only the desired fields are to be included in the field parameter.

For example, the following API returns list resources which include only the id, title and the description fields:

https://ars.apifon.com/services/api/v1/list?fields=id,title,description

NOTE: The parameter fields will throw an error response if a field in the request is not valid.

Pagination

Paginate requests to limit response results and facilitate the process.

Page and size parameters can be used as query parameters in the URL query string to paginate GET requests or POST requests.

size refers to the maximum amount of results which will be included in the results. page refers to the current page of the results viewed.

For example, if you want the second page to feature 20 results, the following query parameter must be included in your request:

https://ars.apifon.com/services/api/v1/list?page=2&size=20

NOTE: Pagination parameters can be omitted from your request and will be set back to default values by the API. For the default values refer to the specific endpoint implementations in the API reference.

Sort

Apifon's API supports results sorting when multiple resources are returned from an endpoint.

sort and sort_dir parameters can be used in the URL query string to paginate on GET requests or in the JSON request body of POST requests.

Sort contains a property name on which the sort is applied. sort_dir is an enumeration (DESC/ASC) which indicates the sort direction.

For example, in case you want to retrieve lists resources sorted by their creation date in ascending order, the link should look like this:

https://ars.apifon.com/services/api/v1/list?sort=date_created&sort_dir=ASC

NOTE: Sort parameters can be omitted from your request, and will be set to default values by the API. For the default values refer to the specific endpoint implementations in the API reference.

Result Filtering

Apifon's API supports filtering of returned results. The API reference explains which resources can be filtered and what should be included in the URL query string.

NOTE: If multiple filters are provided, the API returns resources which match all filters.

Request body

For PUT and POST requests, a request body in JSON format needs to be included.

Content-Type : application/json

The API Reference shows all available request parameters for each endpoint, including required fields and default values.

Response body

The API Reference includes all possible response body parameters.

NOTE: Some endpoints may return an empty response body.

Links

For endpoints that provide paginated results, links object will contain URIs that access the first, last, previous and next page of results.

HTTP ETag

Entity Tags (Commonly called ETags) are identifiers for a resource.

Apifon's REST API generates ETags for resources which are transmitted back to the client in the meta field.

"meta": { "Etag": "9b914344475f6b31beec7a4decb5d93d" }

ETags can be used for cache management and for preventing simultaneous updates of a resource from overwriting each other.

For further information on how to use entity tags refer to the MDN Entity Tag documentation or to the API examples