Contacts

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

Field	Type	Description
id	long integer	Unique object identifier
organization	long integer	The ID of the organization that the contact belongs to. (This is usually your organization ID)
first_name	string	The contact’s first name
last_name	string	The contact’s last name
email	string	The contact’s email address
phone_number	string	The contact’s phone number, in international format, starting with a +
type	string	The contact’s type, as set in the system. One of: employee, beneficiary, vendor, other OR a custom string
status	string	The contact’s status. One of: active or inactive
metadata	hash	Any custom metadata that was added to the contact object at creation time
created	string	The date that the contact was created, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
author	long integer	The ID of the user who created the contact
modified	string	The date that the contact was last modified, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
updated_by	string	The 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)	Type	Description
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
email	String [email protected]	The contact’s email address
metadata	JSON 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]frica.com",
    "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)	Type	Description
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).

Parameter	Type	Description
first_name	String Ex. James	The contact’s first name
last_name	String Ex. Doe	The contact’s last name
email	String Ex, [email protected]	The contact’s email
phone_number	String 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_after	Date string Ex. 2017-01-01 00:00	Only return contacts requests created after this date
created_before	Date 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:

Add the keyword “sync” with a value of 1 or “1” to your contact metadata.
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.
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"
}

Contacts

Introduction

📘
The contacts api endpoint is:

The Contact object

Creating a new Contact

📘
Note

Retrieving a single contact

📘
Note

Listing all Contacts

📘
Note

Filtering Contacts

Instant contact verification

Introduction

📘The contacts api endpoint is:

The Contact object

Creating a new Contact

📘Note

Retrieving a single contact

📘Note

Listing all Contacts

📘Note

Filtering Contacts

Instant contact verification

📘
The contacts api endpoint is:

📘
Note

📘
Note

📘
Note