Navbar
Java PHP C# Python NodeJS
  • Get Started
  • Get Started

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

    Sign Up

    Before you start, please take a moment to register to the platform.

    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:

    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 adress/es. It is mostly used for whitelisting and securing the inbound traffic.

    Parameters

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

    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.

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

    Meta

    Meta object contain additional information about the response, such as the total number of resources on paginated results, entity tags (if applicable) etc. API Reference contains a list of all available meta information of a resource.

    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