Introduction

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

📘

The contacts api endpoint is:

https://api.beyonic.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": "Beyonic",
    "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.beyonic.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": "Beyonic",
    "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)

Type

Description

id*

Integer
Ex. 23

The id of the contact you want to retrieve

Sample Request

curl https://api.beyonic.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.beyonic.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.beyonic.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.beyonic.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.beyonic.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"
}