Introduction

Contacts represent people to whom you can send payments, or from whom you receive payments. The contacts API method allows you to add, retrieve, list, and update contacts in your MFS Africa account. Contacts are also added automatically whenever you send a payment to a new phone number.

📘

The contacts api endpoint is:

https://api.mfsafrica.com/api/contacts

The Contact object

FieldTypeDescription
idlong integerUnique object identifier
organizationlong integerThe ID of the organization that the contact belongs to. (This is usually your organization ID)
first_namestringThe contact’s first name
last_namestringThe contact’s last name
emailstringThe contact’s email address
phone_numberstringThe contact’s phone number, in international format, starting with a +
typestringThe contact’s type, as set in the system. One of: employee, beneficiary, vendor, other OR a custom string
statusstringThe contact’s status. One of: active or inactive
metadatahashAny custom metadata that was added to the contact object at creation time
createdstringThe date that the contact was created, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
authorlong integerThe ID of the user who created the contact
modifiedstringThe date that the contact was last modified, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
updated_bystringThe ID of the user who last updated the contact
{
    "id": 26,
    "organization": "MFS Africa",
    "first_name": "Suzanne",
    "last_name": "Kwagala",
    "email": "[email protected]",
    "phone_number": "+80000000001",
    "type": "employee",
    "status": "active",
    "metadata": null,
    "created": "2013-09-19T21:26:10Z",
    "author": 1,
    "modified": "2015-04-14T18:21:47Z",
    "updated_by": 42
}

Creating a new Contact

To create a new contact, make a POST to the endpoint above, with the attributes below.

Parameter (*required field)TypeDescription
phone_number*String
Ex. +80000000001
Must be in international format
first_name*String
Ex. John
The contact’s first name
last_name*String
Ex. Doe
The contact’s last name
emailString
[email protected]
The contact’s email address
metadataJSON String
Ex. “{‘my_id’: ‘123ASDAsd123’}”
Custom attributes to store with this object. See the Metadata section for more information.

Sample Request

curl https://api.mfsafrica.com/api/contacts -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" \
-d first_name='John' \
-d last_name='Doe' \
-d phone_number='+80000000001' \
-d email='[email protected]' \
-d metadata.my_id='123ASDAsd123'
package com.beyonic.samples;

import com.beyonic.exceptions.BeyonicException;
import com.beyonic.models.*;

Beyonic.API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";

String response = null;

try{
    HashMap<String, Object> contactData = new HashMap<>();
    contactData.put("first_name", "Keneddy");
    contactData.put("last_name", "Amani");
    contactData.put("phone_number", "+80000000001");
    contactData.put("email", "[email protected]");
    response = new Contact().create(contactData, null);
    System.out.println(response);
}
catch (Exception e){
    e.printStackTrace();
}
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$contact = Beyonic_Contact::create(array(
  "phone_number" => "+80000000001",
  "first_name" => "John",
  "last_name" => "Doe",
  "email" => "[email protected]",
  "metadata" => array("my_id"=>"123ASDAsd123")
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contact = beyonic.Contact.create(phone_number='+80000000001',
                       first_name='John',
                       last_name='Doe',
                       email='[email protected]',
                       metadata={'my_id': '123ASDAsd123'}
                       )
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contact = Beyonic::Contact.create(
    phone_number: "+80000000001",
    first_name: "John",
    last_name: "Doe",
    email: "[email protected]",
    metadata: {"my_id": "123ASDAsd123"}
)

📘

Note

Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "id": 26,
    "organization": "MFS Africa",
    "first_name": "Suzanne",
    "last_name": "Kwagala",
    "email": "[email protected]",
    "phone_number": "+80000000001",
    "type": "employee",
    "status": "active",
    "metadata": {
        "my_id": "123ASDAsd123"
    },
    "created": "2013-09-19T21:26:10Z",
    "author": 1,
    "modified": "2015-04-14T18:21:47Z",
    "updated_by": 42
}

Retrieving a single contact

To retrieve a single contact, provide the contact id and a contact object will be returned.

Parameter (*required field)TypeDescription
id*Integer
Ex. 23
The id of the contact you want to retrieve

Sample Request

curl https://api.mfsafrica.com/api/contacts/44702 -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
package com.beyonic.samples;

import com.beyonic.exceptions.BeyonicException;
import com.beyonic.models.*;

Beyonic.API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";

String response = null;

try{
    response = new Contact().get(123);
    System.out.println(response);
}
catch (Exception e){
    e.printStackTrace();
}
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$contact = Beyonic_Contact::get(44702);
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contact = beyonic.Contact.get(44702)
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contact = Beyonic::Contact.get(44702)

Sample Response

📘

Note

Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "id":44702,
    "organization":4,
    "first_name":"John",
    "last_name":"Doe",
    "email":null,
    "phone_number":"+80000000001",
    "type":"employee",
    "status":"active",
    "metadata":{},
    "created":"2016-03-30T17:44:30Z",
    "author":134,
    "modified":"2016-03-30T17:45:22Z",
    "updated_by":134
}

Listing all Contacts

To retrieve a list of all contacts, make a GET request to the contact endpoint. This will return a list of contacts

Sample Request

curl https://api.mfsafrica.com/api/contacts -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
package com.beyonic.samples;

import com.beyonic.exceptions.BeyonicException;
import com.beyonic.models.*;

Beyonic.API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";

String response = null;

try{
    response = new Contact().list(null, null);
    System.out.println(response);
}
catch (Exception e){
    e.printStackTrace();
}
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$contacts = Beyonic_Contact::getAll();
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = beyonic.Contact.list()
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = Beyonic::Contact.list

Sample Response

📘

Note

Sample Response (JSON) - if you use one of the development libraries, this is automatically converted into a native object for you:

{
    "count": 2,
    "next": "https://api.mfsafrica.com/api/contacts?offset=10",
    "previous": null,
    "results": [
        {
            "id": 1146,
            "organization": "Demo Org",
            "first_name": "Eliana",
            "last_name": "Kalema",
            "email": null,
            "phone_number": "+25677XXXXXX",
            "type": "other",
            "status": "active",
            "metadata": null,
            "created": "2015-02-13T04:22:31Z",
            "author": 7,
            "modified": "2015-02-26T13:00:35Z",
            "updated_by": 1
        },
        {
            "id": 1175,
            "organization": "Demo Org",
            "first_name": "Trina",
            "last_name": "Faith",
            "email": null,
            "phone_number": "+25677XXXXXX",
            "type": "employee",
            "status": "active",
            "metadata": null,
            "created": "2015-02-18T11:52:43Z",
            "author": 137,
            "modified": "2015-02-26T13:00:35Z",
            "updated_by": 1
        },
    ]
}

Filtering Contacts

You can search or filter contacts on the following fields. Simply add them to your request as shown in the examples. You can combine multiple filters. Note that filters return exact matches only. (The phone_number field is treated differently - see below).

ParameterTypeDescription
first_nameString
Ex. James
The contact’s first name
last_nameString
Ex. Doe
The contact’s last name
emailString
Ex, [email protected]
The contact’s email
phone_numberString
Ex. +80000000001
The contact’s phone number. Note that the phone number will be matched in the international format, starting with a ‘+’ sign. If the ‘+’ sign isn’t included in your request, it will be appended before attempting to match your request.
created_afterDate string
Ex. 2017-01-01 00:00
Only return contacts requests created after this date
created_beforeDate string
Ex. 2017-01-01 00:00
Only return collection requests created before this date.

Sample Response

curl https://api.mfsafrica.com/api/contacts?first_name=luke -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900"
package com.beyonic.samples;

import com.beyonic.exceptions.BeyonicException;
import com.beyonic.models.*;

Beyonic.API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";

String response = null;

try{
    HashMap<String, String> contactFilter = new HashMap<>();
    contactFilter.put("created_after", "2017-01-01 00:00");
    response = new Contact().filter(contactFilter, null);
    System.out.println(response);
}
catch (Exception e){
    e.printStackTrace();
}
<?php
require_once('./lib/Beyonic.php');
Beyonic::setApiKey("ab594c14986612f6167a975e1c369e71edab6900");

$contacts = Beyonic_Contact::getAll(array(
  "first_name" => "luke"
));
?>
import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = beyonic.Contact.list(first_name='luke')
require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

contacts = Beyonic::Contact.list(
  first_name: "luke"
)

Instant contact verification

Instant contact verification API can be used to verify the names of contact from our third-party connections.

Note: The API carries a charge, please contact [email protected] for more info. The API is only supported in Uganda for the following networks: Airtel, MTN, and M-sente. The sample requests provided won’t work because +800 aren’t real phone numbers. Please test with real phone numbers.

To use the API:

  1. Add the keyword “sync” with a value of 1 or “1” to your contact metadata.
  2. Use the contact read API if a contact already exists and the contact creation API if it’s a new contact. 3) Verification is done instantly, so when the API call returns, you’ll have the validation data.
  3. Verification data will include the full names + scoring information even if there is no match with the one you provided.

Sample Request

curl https://api.mfsafrica.com/api/contacts -H "Authorization: Token ab594c14986612f6167a975e1c369e71edab6900" \
-d first_name='John' \
-d last_name='Doe' \
-d phone_number='+80000000001' \
-d email='[email protected]' \
-d metadata.sync='1'
{
    "id": 5523949,
    "organization": 4,
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "+80000000001",
    "type": "employee",
    "status": "active",
    "metadata": {
        "sync": "1",
        "s_contact4gender": null,
        "s_contact4age": null,
        "s_contact4partner_id": null,
        "s_contact4tester": null,
        "s_contact4another_one": null,
        "s_contact4tested": null
    },
    "phone_is_supported": "yes",
    "phone_is_mm_registered": "yes",
    "name_on_network": "James Doe",
    "name_matches_network_status": "checked",
    "name_matches_network_score": 34.0,
    "network_name": "",
    "created": "2020-05-21T09:46:07Z",
    "author": 4926,
    "modified": "2020-05-21T09:46:10Z",
    "updated_by": 4926,
    "national_id": null,
    "national_id_type": "national"
}