General API information

Details that apply to all the Portal APIs

Suggest Edits

The intended audience for these API details are software developers, architects, engineers or others involved in 3P systems integration. Readers are assumed to be knowledgeable about web service technologies and service-oriented architecture.

REST and JSON

The Portal APIs are REST based.

Onafriq also provides libraries for several languages including PHP, Java, Ruby, and Python.

All responses are returned using JSON, however, if you are using the language libraries, the JSON responses will be converted into native, language-specific objects.

Authentication

🚧

HTTPS Required

All requests must use HTTPS

The Portal APIs uses Token Based Authentication and requires an API key for authentication. You can generate or change your API key by logging into your account. Keep your API key secret to maintain the integrity of your account.

You must supply your API key with all API requests using the “Authorization” header as shown in the examples. You should include your API key with all requests.

The API key in all the examples is a valid test key, so you can test the examples immediately.

curl https://api.mfsafrica.com/api -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"

<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey('ab594c14986612f6167a975e1c369e71edab6900');
?>

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

package com.beyonic;

import com.beyonic.Beyonic;

Beyonic.API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";

Versioning

The APIs try to maintain backward compatibility for all released API versions. This way, your code continues to work whether you wrote it 10 years ago, or 10 days ago.

New API versions are released only when we make backward-incompatible changes to the API. We define these as changes that will prevent our official clients from working on old versions. Some changes DO NOT result in a new version, including:

  • Adding new API methods
  • Adding optional parameters to existing API methods
  • Or adding new fields to responses.

This means that you should write your software with the expectation that new API methods or new optional parameters, or new fields may be added to existing APIs without a change in version

You don’t need to specify a version in your request. The first time an API request is made for your organization, the version is saved, and will be used on subsequent API requests unless it is changed in the organization settings, or overridden as below. This allows your client applications to continue working even if newer API versions are released.

You can temporarily override the API version for a specific request in 2 ways:

  • Using version-specific URLS like: https://api.mfsafrica.com/api/v1
  • Or including the Beyonic-Version header in your request as shown in the examples to the right.

The various API libraries provide methods for changing the version, as shown in the examples below

curl -H "Beyonic-Version: v1" https://api.mfsafrica.com/api

import com.beyonic.Beyonic;

Beyonic.API_VERSION = "v1";

<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiVersion("v1");
?>

import beyonic
beyonic.api_version = 'v1'

require 'beyonic'
Beyonic.api_version = 'v1'

📘

Note:

Note that this doesn’t change your organization’s default API version, which was saved in your organization's settings the first time you interacted with the Portal APIs.

To change your default API version, log into the web portal and go to

  • Settings (Cogwheel) > “Organization Settings” > “Advanced Settings” > General settings

Pagination

Most Portal API methods support a way to retrieve a list of records. For example, you can retrieve a list of contacts.

When retrieving a list, you can control the number of records returned by adding two parameters to your request:

  • limit: This limits the number of records returned per page. If omitted, only 10 records are returned per page
  • offset: This tells the API where to start getting

The API response body shall include the following parameters:

  • count: The total number of records available (not just on the returned page)
  • next: A link to the next page of records. If there is no next page, this shall be equal to null
  • previous: A link to the previous page of records. If there is no previous page, this shall be equal to null
  • results: This will contain the list of records for the current page 
curl https://api.mfsafrica.com/api/v2/contacts?limit=10&offset=5 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"

package com.beyonic.examples;

import com.beyonic.models.Contact;

HashMap<String, String> paginationDetails = new HashMap<>();
paginationDetails.put("limit", "10");
paginationDetails.put("offset", "5");
response = new Contact().filter(paginationDetails, null);
System.out.println(response);

<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiVersion("v2");
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$contacts = Beyonic_Contact::getAll(array(
  "limit" => "10",
  "offset" => "5"
));
?>

import beyonic
beyonic.api_version = 'v2'
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = beyonic.Contact.list(limit='10', offset='5')

require 'beyonic'
Beyonic.api_vesion = 'v2'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = Beyonic::Contact.list(
  limit: 10,
  offset: 5
)

Filtering Results

Most API methods support a way to retrieve a list of records or a single record. For example, you can retrieve a list of contacts or a single contact.

When retrieving a list or a single record, you can limit the results to records where a given field matches specific search criteria. To do this, add the keyword to your request as shown in the examples.

Not all fields are filterable. See the documentation for each method below to see which fields are filterable within that method.

curl https://api.mfsafrica.com/api/contacts?first_name=tom -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"

package com.beyonic.examples;

import com.beyonic.models.Contact;

HashMap<String, String> contactFilter = new HashMap<>();
contactFilter.put("first_name", "Jerry");
response = new Contact().filter(contactFilter, null);
System.out.println(response);

<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$contacts = Beyonic_Contact::getAll(array(
  "first_name" => "tom"
));
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = beyonic.Contact.list(first_name='tom')

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = Beyonic::Contact.list(
  first_name: 'tom'
)

Ordering Results

When retrieving a list, you can control the order in which records are returned in by adding one parameter to your request:

  • ordering: This orders the records by one of the visible fields on the object

Ascending or Descending order:

  • To use ascending order, just use the field name E.g. ordering=created
  • To use descending order, add a “-” to the field name E.g. ordering=-created 
curl https://api.mfsafrica.com/api/contacts?ordering=-created -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"

package com.beyonic.examples;

import com.beyonic.models.Contact;

HashMap<String, String> orderingDetails = new HashMap<>();
orderingDetails.put("ordering", "-created");
response = new Contact().filter(orderingDetails, null);
System.out.println(response);

<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$contacts = Beyonic_Contact::getAll(array(
  "ordering" => "-created"
));
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = beyonic.Contact.list(ordering='-created')

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = Beyonic::Contact.list(
  ordering: '-created'
)

Updated 6 months ago