Events

Suggest Edits

Introduction

Events track certain changes that happen to your MFS Africa account. Events are created automatically when certain changes occur, and you can use them to stay informed about the changes. For example, when a new contact is created, we will create a “contact.created” event.

You can use the events API to retrieve information about recent events. Events are saved for at least 30 days. After that, they may be discarded.

📘

The events api endpoint is:

https://api.mfsafrica.com/api/events

You can also set up your account to automatically notify you as events occur. See the Webhooks API for more information about setting up automatic notifications for events.

Supported Events types

The following events are supported

EventDescriptionObject returned in data
payment.status.changedTriggered any time a payment changes state. See the “Payments” section for possible state values.Payment object
collection.receivedTriggered any time a collection (an incoming payment) is received from a customerCollection object
contact.createdTriggered any time a contact is created in your accountContact object
collectionrequest.status.changedTriggered any time a collection request status changes. See the “Collection Requests” section for possible status values.CollectionRequest object

The Event object

FieldTypeDescription
idlong integerUnique object identifier
organizationlong integerThe ID of the organization that the event belongs to. (This is usually your organization ID)
typestringThe event type. See Supported Event Types above
dataobjectThe details about the event. This is a representation of the object that triggered the event. For example, for the “contact.created” event, this will repesent a “Contact” object
createdstringThe date that the event was created, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
authorlong integerThe ID of the user who created the event
modifiedstringThe date that the event was last modified, in the UTC timezone. Format: “YYYY-MM-DDTHH:MM:SSZ”
updated_bystringThe ID of the user who last modified the event
{
    "id": 1146,
    "organization":1,
    "type": "contact.created",
    "data": {
        "id": 26,
        "organization": 1,
        "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
    },
    "created": "2013-09-19T21:26:10Z",
    "author": 1,
    "modified": "2015-04-14T18:21:47Z",
    "updated_by": 42
}

Retrieving a Single Account

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

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

Sample Request

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

ackage com.beyonic.samples;

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

Beyonic.API_KEY = "ab594c14986612f6167a975e1c369e71edab6900";

String response = null;

try{
    response = new Event().get(123);
    System.out.println(response);
}
catch (Exception e){
    e.printStackTrace();
}

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

$event = Beyonic_Event::get(12);
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

event = beyonic.Event.get(12)

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

event = Beyonic::Event.get(12)

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": 1146,
    "organization":1,
    "type": "contact.created",
    "data": {
        "id": 26,
        "organization": 1,
        "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
    },
    "created": "2013-09-19T21:26:10Z",
    "author": 1,
    "modified": "2015-04-14T18:21:47Z",
    "updated_by": 42
}

Listing all Events

To retrieve a list of all events, make a GET request to the events end point. This will return a list of events.

Sample Request

curl https://api.mfsafrica.com/api/events -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 Event().list(null, null);
    System.out.println(response);
}
catch (Exception e){
    e.printStackTrace();
}

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

$events = Beyonic_Event::getAll();
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

events = beyonic.Event.list()

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

events = Beyonic::Event.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": 1,
    "next": "https://api.mfsafrica.com/api/events?offset=10",
    "previous": null,
    "results": [
        {
            "id": 1146,
            "organization":1,
            "type": "contact.created",
            "data": {
                    "id": 26,
                    "organization": 1,
                    "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
                }
        },
    ]
}

Filtering Events

You can search or filter events 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.

  • type - the event type

Sample Request

curl https://api.mfsafrica.com/api/events?type=contact.created -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> filterValues = new HashMap<>();
    filterValues.put("type", "contact.created");
    response = new Event().filter(filterValues, null);
    System.out.println(response);
}
catch (Exception e){
    e.printStackTrace();
}

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

$events = Beyonic_Event::getAll(array(
  "type" => "contact.created"
));
?>

import beyonic
beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

events = beyonic.Event.list(type='contact.created')

require 'beyonic'
Beyonic.api_key = 'ab594c14986612f6167a975e1c369e71edab6900'

events = Beyonic::Event.list(
  type: "contact.created"
)

Updated 11 months ago