Groups
Create Group
This API lets you create new groups which you can use to organize your contacts. To create a group, send a POST request to the following endpoint
EndPoint: https://api.braceafrica.com/v1/contacts/groups/add
The json to the POST to the endpoint
| name | String | Compulsory - The group name |
| tags | String | Optional - These are tags in the contacts you want to link. The group will be formed and the contacts automatically linked to the group |
{
"name": "",
"tags": "",
}
API code samples
import requests
import json
# authentication
x_username = "";
x_apikey = "";
params = {
"name": "",
"tags": "",
}
# endpoint
addGroupURL = "https://api.braceafrica.com/v1/contacts/groups/add"
headers = {
'Content-type': 'application/json',
'Accept': 'application/json',
'x-api-user': x_username,
'x-api-key' : x_apikey
}
# endoint
req = requests.post(addGroupURL, data=json.dumps(params), headers=headers)
# response
print(req.text)
// authentication
$x_username = "";
$x_apikey = "";
// id of contact to delete
$params = array(
"name" => "",
"tags" => "",
);
$addGroup = json_encode($params);
// endoint
$addGroupURL = "https://api.braceafrica.com/v1/contacts/groups/add";
$req = curl_init($addGroupURL);
curl_setopt($req, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($req, CURLOPT_TIMEOUT, 60);
curl_setopt($req, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_POSTFIELDS, $addGroup);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'x-api-user: '.$x_username,
'x-api-key: '.$x_apikey
));
// read api response
$res = curl_exec($req);
// close curl
curl_close($req);
// print the raw json response
var_dump($res);
var request = require('request');
// authentication
var x_username = ""
var x_apikey = ""
// data
var params = {
"name": "",
"tags": "",
}
// endpoint
var addGroupURL = "https://api.braceafrica.com/v1/contacts/groups/add";
var headers = {
'Content-Type' : 'application/json',
'Content-Length' : params.length,
'Accept' : 'application/json',
'x-api-user' : x_username,
'x-api-key' : x_apikey
}
var options = {
url: addGroupURL,
method: 'POST',
headers: headers,
form: params
}
// the request and response
request(options, function (error, response, body) {
if (!error && response.statusCode == 200) {
// Print out the response body
console.log(body)
}
console.log(body)
})
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
"strconv"
)
func main() {
// endpoint
var addGroupURL string = "https://api.braceafrica.com/v1/contacts/groups/add"
// authentication
var x_username string = ""
var x_apikey string = ""
// data
groupData := map[string]string{
"name": "",
"tags": "",
}
params, _ := json.Marshal(groupData)
request, err := http.NewRequest("POST", addGroupURL, bytes.NewBuffer(params))
request.Header.Add("Content-Type", "application/json")
request.Header.Set("x-api-user", x_username)
request.Header.Set("x-api-key", x_apikey)
request.Header.Set("Content-Length", strconv.Itoa(len(params)))
response, err := http.DefaultClient.Do(request)
if err != nil {
panic(err.Error())
}
body, err := ioutil.ReadAll(response.Body)
if err != nil {
panic(err.Error())
}
defer response.Body.Close()
fmt.Println(string(body))
}
Edit Group
This API allows you to change the name of your group by sending a POST request to the following endpoint.
EndPoint: https://api.braceafrica.com/v1/contacts/groups/edit/:groupId
The json to the POST to the endpoint
{
"name": "",
}
API code samples
import requests
import json
# authentication
x_username = "";
x_apikey = "";
params = {
"name": "",
}
groupId = ""
# endpoint
editGroupURL = "https://api.braceafrica.com/v1/contacts/groups/edit/" + groupId
headers = {
'Content-type': 'application/json',
'Accept': 'application/json',
'x-api-user': x_username,
'x-api-key' : x_apikey
}
# endoint
req = requests.post(editGroupURL, data=json.dumps(params), headers=headers)
# response
print(req.text)
// authentication
$x_username = "";
$x_apikey = "";
$groupId = "";
// id of contact to delete
$params = array(
"name"=>""
);
$editGroup = json_encode($params);
// endoint
$editGroupURL = "https://api.braceafrica.com/v1/contacts/groups/edit/".$groupId;
$req = curl_init($editGroupURL);
curl_setopt($req, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($req, CURLOPT_TIMEOUT, 60);
curl_setopt($req, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_POSTFIELDS, $editGroup);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'x-api-user: '.$x_username,
'x-api-key: '.$x_apikey
));
// read api response
$res = curl_exec($req);
// close curl
curl_close($req);
// print the raw json response
var_dump($res);
var request = require('request');
// authentication
var x_username = ""
var x_apikey = ""
// data
var params = {
"name": "",
}
var groupId = ""
// endpoint
var editGroupURL = "https://api.braceafrica.com/v1/contacts/groups/edit/" + groupId
var headers = {
'Content-Type' : 'application/json',
'Content-Length' : params.length,
'Accept' : 'application/json',
'x-api-user' : x_username,
'x-api-key' : x_apikey
}
var options = {
url: editGroupURL,
method: 'POST',
headers: headers,
form: params
}
// the request and response
request(options, function (error, response, body) {
if (!error && response.statusCode == 200) {
// Print out the response body
console.log(body)
}
else{
console.log(error)
}
})
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func main() {
var groupId string = ""
// endpoint
var editGroupURL string = "https://api.braceafrica.com/v1/contacts/groups/edit/" + groupId
// authentication
var x_username string = ""
var x_apikey string = ""
// data
groupData := map[string]string{
"name": "",
}
params, _ := json.Marshal(groupData)
request, err := http.NewRequest("POST", editGroupURL, bytes.NewBuffer(params))
if err != nil {
panic(err.Error())
}
// headers
request.Header.Set("Content-Type", "application/json")
request.Header.Set("x-api-user", x_username)
request.Header.Set("x-api-key", x_apikey)
response, err := http.DefaultClient.Do(request)
if err != nil {
panic(err.Error())
}
body, err := ioutil.ReadAll(response.Body)
if err != nil {
panic(err.Error())
}
fmt.Println(string(body))
}
When the request is successful, you should expect the following response.
{
"status": 200,
"message": "Group has been updated"
}
Fetch Groups
To fetch your groups, send a GET request to the following endpoint.
EndPoint: https://api.braceafrica.com/v1/contacts/groups/fetch
API code samples
import requests
import json
# authentication
x_username = "";
x_apikey = "";
# endoint
fetchGroupsURL = "https://api.braceafrica.com/v1/contacts/groups/fetch"
headers = {
'Content-type': 'application/json',
'Accept': 'application/json',
'x-api-user': x_username,
'x-api-key' : x_apikey
}
req = requests.get(fetchGroupsURL, headers=headers)
# response
print(req.text)
// authentication
$x_username = "";
$x_apikey = "";
// endoint
$fetchGroupsURL = "https://api.braceafrica.com/v1/contacts/groups/fetch";
$req = curl_init($fetchGroupsURL);
curl_setopt($req, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($req, CURLOPT_TIMEOUT, 60);
curl_setopt($req, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'x-api-user: '.$x_username,
'x-api-key: '.$x_apikey
));
// read api response
$res = curl_exec($req);
// close curl
curl_close($req);
// print the raw json response
var_dump($res);
var request = require('request');
// authentication
var x_username = ""
var x_apikey = ""
// endpoint
var fetchGroupsURL = "https://api.braceafrica.com/v1/contacts/groups/fetch";
var headers = {
'Content-Type' : 'application/json',
'Accept' : 'application/json',
'x-api-user' : x_username,
'x-api-key' : x_apikey
}
var options = {
url: fetchGroupsURL,
method: 'GET',
headers: headers
}
// the request and response
request(options, function (error, response, body) {
if (!error && response.statusCode == 200) {
// Print out the response body
console.log(body)
}
else{
console.log(error)
}
})
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
// endpoint
var fetchGroupsURL string = "https://api.braceafrica.com/v1/contacts/groups/fetch"
// authentication
var x_username string = ""
var x_apikey string = ""
// request
request, err := http.NewRequest("GET", fetchGroupsURL, nil)
if err != nil {
panic(err.Error())
}
// headers
request.Header.Set("Content-Type", "application/json")
request.Header.Set("x-api-user", x_username)
request.Header.Set("x-api-key", x_apikey)
// response
response, err := http.DefaultClient.Do(request)
if err != nil {
panic(err.Error())
}
body, _ := ioutil.ReadAll(response.Body)
defer response.Body.Close()
fmt.Println(string(body))
}
When the request is successful, you should expect the following response.
{
"status": 200,
"groups": [
{
"groupId": 12,
"groupName": "Kenzu Safaris",
"createdOn": "2019-05-17T00:00:00.000Z",
"contacts": []
}
]
}
Link Contacts to Group
This API lets you add contacts to a group by sending a POST request to the following endpoint.
EndPoint: https://api.braceafrica.com/v1/contacts/add/:groupId
The json to the POST to the endpoint
{
"contactIds": [1,2,3,4]
}
API code samples
import requests
import json
# authentication
x_username = "";
x_apikey = "";
params = {
"contactIds": [1,2,3,4]
}
groupId = ""
# endpoint
addContactsToGroupURL = "https://api.braceafrica.com/v1/contacts/add/" + groupId
headers = {
'Content-type': 'application/json',
'Accept': 'application/json',
'x-api-user': x_username,
'x-api-key' : x_apikey
}
# endoint
req = requests.post(addContactsToGroupURL, data=json.dumps(params), headers=headers)
# response
print(req.text)
// authentication
$x_username = "";
$x_apikey = "";
$groupId = "";
// id of contact to delete
$params = array(
"contactIds"=>array(1,2,3,4),
);
$contactsData = json_encode($params);
// endoint
$addContactsToGroupURL = "https://api.braceafrica.com/v1/contacts/add/".$groupId;
$req = curl_init($addContactsToGroupURL);
curl_setopt($req, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($req, CURLOPT_TIMEOUT, 60);
curl_setopt($req, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_POSTFIELDS, $contactsData);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'x-api-user: '.$x_username,
'x-api-key: '.$x_apikey
));
// read api response
$res = curl_exec($req);
// close curl
curl_close($req);
// print the raw json response
var_dump($res);
var request = require('request');
// authentication
var x_username = ""
var x_apikey = ""
// data
var params = {
"contactIds": [1,2,3,4],
}
var groupId = ""
// endpoint
var addContactsToGroupURL = "https://api.braceafrica.com/v1/contacts/add/" + groupId
var headers = {
'Content-Type' : 'application/json',
'Content-Length' : params.length,
'Accept' : 'application/json',
'x-api-user' : x_username,
'x-api-key' : x_apikey
}
var options = {
url: addContactsToGroupURL,
method: 'POST',
headers: headers,
form: params
}
// the request and response
request(options, function (error, response, body) {
if (!error && response.statusCode == 200) {
// Print out the response body
console.log(body)
}
else{
console.log(error)
}
})
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func main() {
var groupId string = ""
// endpoint
var addContactsToGroupURL string = "https://api.braceafrica.com/v1/contacts/add/"+groupId
// authentication
var x_username string = ""
var x_apikey string = ""
// data
data:= map[string][]int{
"contactIds":[]int{1,2,3,4}
}
params, _ := json.Marshal(data)
// request
request, err := http.NewRequest("POST", addContactsToGroupURL, bytes.NewBuffer(params))
if err != nil {
panic(err.Error())
}
// headers
request.Header.Set("Content-Type", "application/json")
request.Header.Set("x-api-user", x_username)
request.Header.Set("x-api-key", x_apikey)
// response
response, err := http.DefaultClient.Do(request)
if err != nil {
panic(err.Error())
}
body, err := ioutil.ReadAll(response.Body)
if err != nil {
panic(err.Error())
}
defer response.Body.Close()
fmt.Println(string(body))
}
When the request is successful, you should expect the following response.
{
"status": 200,
"message": "The contacts linked to group"
}
Fetch Group Contacts
This API lets you fetch all the contacts in a group by sending a GET request to the following endpoint.
EndPoint: https://api.braceafrica.com/v1/contacts/groups/fetch/:groupId
Send a GET request to the endpoint
API code samples
import requests
import json
# authentication
x_username = "";
x_apikey = "";
groupId = ""
# endoint
fetchGroupContactsURL = "https://api.braceafrica.com/v1/contacts/groups/fetch/" + groupId
headers = {
'Content-type': 'application/json',
'Accept': 'application/json',
'x-api-user': x_username,
'x-api-key' : x_apikey
}
req = requests.get(fetchGroupContactsURL, headers=headers)
# response
print(req.text)
// authentication
$x_username = "";
$x_apikey = "";
$groupId = "";
// endoint
$fetchGroupContactsURL = "https://api.braceafrica.com/v1/contacts//groups/fetch/".$groupId;
$req = curl_init($fetchGroupContactsURL);
curl_setopt($req, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($req, CURLOPT_TIMEOUT, 60);
curl_setopt($req, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'x-api-user: '.$x_username,
'x-api-key: '.$x_apikey
));
// read api response
$res = curl_exec($req);
// close curl
curl_close($req);
// print the raw json response
var_dump($res);
var request = require('request');
// authentication
var x_username = ""
var x_apikey = ""
var groupId = ""
// endpoint
var fetchGroupContactsURL = "https://api.braceafrica.com/v1/contacts//groups/fetch/"+groupId
var headers = {
'Content-Type' : 'application/json',
'Accept' : 'application/json',
'x-api-user' : x_username,
'x-api-key' : x_apikey
}
var options = {
url: fetchGroupContactsURL,
method: 'GET',
headers: headers
}
// the request and response
request(options, function (error, response, body) {
if (!error && response.statusCode == 200) {
// Print out the response body
console.log(body)
}
else{
console.log(error)
}
})
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
var groupId string = ""
// endpoint
var fetchGroupContactsURL string = "https://api.braceafrica.com/v1/contacts/groups/fetch/" + groupId
// authentication
var x_username string = ""
var x_apikey string = ""
// request
request, err := http.NewRequest("GET", fetchGroupContactsURL, nil)
if err != nil {
panic(err.Error())
}
// headers
request.Header.Set("Content-Type", "application/json")
request.Header.Set("x-api-user", x_username)
request.Header.Set("x-api-key", x_apikey)
// response
response, err := http.DefaultClient.Do(request)
if err != nil {
panic(err.Error())
}
body, err := ioutil.ReadAll(response.Body)
if err != nil {
panic(err.Error())
}
defer response.Body.Close()
fmt.Println(string(body))
}
When the request is successful, you should expect the following response.
{
"groupId": 2536,
"groupName": "Chama Ya Mama",
"contacts": [
{
"id": 65,
"name": "John Doe",
"phoneNumber": "+2547xxx4578",
"tags": "chairman"
},
{
"id": 63,
"name": "Pendo JM",
"phoneNumber": "+2547xxy4597",
"tags": "member"
}
]
}
Remove Group Contacts
This API allows you to unlink contacts from a group by sending a POST request to the following endpoint.
EndPoint: https://api.braceafrica.com/v1/contacts/delete/:groupId
The json to the POST to the endpoint
{
"contactIds": [1,2,3,4]
}
API code samples
import requests
import json
# authentication
x_username = "";
x_apikey = "";
params = {
"contactIds": [1,2,3,4],
}
groupId = ""
# endpoint
deleteGroupContactsURL = "https://api.braceafrica.com/v1/contacts/delete/" + groupId
headers = {
'Content-type': 'application/json',
'Accept': 'application/json',
'x-api-user': x_username,
'x-api-key' : x_apikey
}
# endoint
req = requests.post(deleteGroupContactsURL, data=json.dumps(params), headers=headers)
# response
print(req.text)
// authentication
$x_username = "";
$x_apikey = "";
$groupId = "";
// id of contact to delete
$params = array(
"contactIds"=>array(1,2,3,4),
);
$contactsData = json_encode($params);
// endoint
$deleteGroupContactsURL = "https://api.braceafrica.com/v1/contacts/delete/".$groupId;
$req = curl_init($deleteGroupContactsURL);
curl_setopt($req, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($req, CURLOPT_TIMEOUT, 60);
curl_setopt($req, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_POSTFIELDS, $contactsData);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'x-api-user: '.$x_username,
'x-api-key: '.$x_apikey
));
// read api response
$res = curl_exec($req);
// close curl
curl_close($req);
// print the raw json response
var_dump($res);
var request = require('request');
// authentication
var x_username = ""
var x_apikey = ""
// data
var params = {
"contactIds": [1,2,3,4],
}
var groupId = ""
// endpoint
var deleteGroupContactsURL = "https://api.braceafrica.com/v1/contacts/delete"+groupId
var headers = {
'Content-Type' : 'application/json',
'Content-Length' : params.length,
'Accept' : 'application/json',
'x-api-user' : x_username,
'x-api-key' : x_apikey
}
var options = {
url: deleteGroupContactsURL,
method: 'POST',
headers: headers,
form: params
}
// the request and response
request(options, function (error, response, body) {
if (!error && response.statusCode == 200) {
// Print out the response body
console.log(body)
}
else{
console.log(error)
}
})
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func main() {
var groupId string = ""
var deleteGroupContactsURL string = "https://api.braceafrica.com/v1/contacts/delete/"+groupId
// authentication
var x_username string = ""
var x_apikey string = ""
// data
contactIds := map[string][]int{
"contactIds":[]int{1,2,3,4}
}
params, _ := json.Marshal(contactIds)
// request
request, err := http.NewRequest("POST", deleteGroupContactsURL, bytes.NewBuffer(params))
if err != nil {
panic(err.Error())
}
request.Header.Set("Content-Type", "application/json")
request.Header.Set("x-api-user", x_username)
request.Header.Set("x-api-key", x_apikey)
// response
response, err := http.DefaultClient.Do(request)
if err != nil {
panic(err.Error())
}
body, err := ioutil.ReadAll(response.Body)
if err != nil {
panic(err.Error())
}
fmt.Println(string(body))
}
When the request is successful, you should expect the following response.
{
"status": 200,
"message": "Contacts removed form group"
}
Delete Groups
Our delete groups API allows you to delete the groups by sending a POST request to the following endpoint.
EndPoint: https://api.braceafrica.com/v1/contacts/groups/delete
The json to the POST to the endpoint
{
"groupIds": [1,2,3,4]
}
Some sample request in the common programming languages would look like this
import requests
import json
# authentication
x_username = "";
x_apikey = "";
# endpoint
deleteGroupURL = "https://api.braceafrica.com/v1/contacts/groups/delete"
params = {
"groupIds":[1,2,3,4]
}
headers = {
'Content-type': 'application/json',
'Accept': 'application/json',
'x-api-user': x_username,
'x-api-key' : x_apikey
}
# endoint
req = requests.post(deleteGroupURL,data=json.dumps(params), headers=headers)
# response
print(req.text)
// authentication
$x_username = "";
$x_apikey = "";
// id of group to delete
$groupId = "";
// endoint
$deleteGroupURL = "https://api.braceafrica.com/v1/contacts/groups/delete";
$params = array(
"groupIds"=>array(1,2,3,4)
);
$deleteGroups = json_encode($params)
$req = curl_init($deleteGroupURL);
curl_setopt($req, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($req, CURLOPT_TIMEOUT, 60);
curl_setopt($req, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($req, CURLOPT_POSTFIELDS, $deleteGroups);
curl_setopt($req, CURLOPT_RETURNTRANSFER, true);
curl_setopt($req, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'x-api-user: '.$x_username,
'x-api-key: '.$x_apikey
));
// read api response
$res = curl_exec($req);
// close curl
curl_close($req);
// print the raw json response
var_dump($res);
var request = require('request');
// authentication
var x_username = ""
var x_apikey = ""
var params = {
"groupIds":[1,2,3,4]
}
// endpoint
var deleteGroupURL = "https://api.braceafrica.com/v1/contacts/groups/delete"
var headers = {
'Content-Type' : 'application/json',
'Accept' : 'application/json',
'x-api-user' : x_username,
'x-api-key' : x_apikey
}
var options = {
url: deleteGroupURL,
method: 'POST',
headers: headers,
form:params
}
// the request and response
request(options, function (error, response, body) {
if (!error && response.statusCode == 200) {
// Print out the response body
console.log(body)
}
else{
console.log(error)
}
})
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
// endpoint
var deleteGroupURL string = "https://api.braceafrica.com/v1/contacts/groups/delete"
// authentication
var x_username string = ""
var x_apikey string = ""
groupIds := map[string][]int{
"groupIds":[]int{1,2,3,4}
}
params, _ := json.Marshal(groupIds)
// request
request, err := http.NewRequest("POST", deleteGroupURL, bytes.NewBuffer(params))
if err != nil {
panic(err.Error())
}
// headers
request.Header.Set("Content-Type", "application/json")
request.Header.Set("x-api-user", x_username)
request.Header.Set("x-api-key", x_apikey)
// response
response, err := http.DefaultClient.Do(request)
if err != nil {
panic(err.Error())
}
body, err := ioutil.ReadAll(response.Body)
if err != nil {
panic(err.Error())
}
fmt.Println(string(body))
}
When the request is successful, you should expect the following response.
{
"status": 200,
"message": "4 groups have been deleted"
}