©2021 UtatuziCenter - All Rights Reserved.

Getting Started

The UtatuziCenter API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the UtatuziCenter API in sandbox mode, which does not affect your live data or interact with the existing data. You use an API Key and Secret to authenticate your request.

Authentication

The Utatuzi Center API uses API keys to authenticate requests. You can view and manage your API keys in the Utatuzi Center Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key and secret for authentication. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Request Headers

These are the standard request headers that are needed when authenticating with the API.

Parameter Type Description
Apikey String Required Your account's Apikey.
Apisecret String Required Your account's Apisecret.
Content-Type String Required The requests content type. Only application/x-www-form-urlencoded is accepted.
Accept String Optional The requests response type. Can be application/json or application/xml. Defaults to application/json.

New Dispute

Endpoint

Submit a new dispute by making a HTTP POST request to the following endpoint:

copy

https://www.api.utatuzicenter.com/v1/newdispute

To provide a new dispute via the API the following request parameters that are required in the body of the request. These fields must be provided in an application/x-www-form-urlencoded format.

Request Parameters

Parameter Type Description
environment String Required The environment of the request. Can be sandbox or production.
title String Required The title/subject of the dispute.
description String Required A description of the dispute.
amount Integer Required The Amount in question for the dispute.
numberOfDisputants Integer Required Number of people involved in the dispute. API does not accept more than 10 disputants in a dispute.
disputants String Required A description of the disputants, their names; contacts; and addresses; etc.
organization JSON Optional This is your organization's internal categorization/description of dispute. There are no limits imposed on the structure of this parameter other than the valid JSON formatting requirement. Such as :
copy

{
    "GoodCompany": {
        "DisputeDetails": {
            "department": "HR",
            "country": "Kenya",
            "negotiation": "failure"
        }
    }
}

Code

CURL

copy

curl -X POST \
    https://www.api.utatuzicenter.com/v1/ \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -H 'Apikey: myApiKey' \
    -H 'Apisecret: myApiSecret' \
    -d 'environment=sandbox&title=The%20best%20%20title.&description=Description%20of%20the%20best%20dispute.&amount=20000&numberOfDisputants=2&disputants=Mzushi%20Mbaya%200787657987%2C%20Bizna%20poa%2009372938201'
	

API response

The body of the response will be a JSON or XML object containing the following fields:

Parameter Sub - Parameter Type Description
UCDisputeData
ClientDetails
id string The id of the client making the request.
name string The name of the company.
DisputeDetails
statusCode Integer This corresponds to the status of the request.
environment String The environment of the request. Can be sandbox or production.
status String The status of the request. Can be success or error.
disputeId String The ID of the dispute.
disputeTitle String The title of the dispute received by the API.
timeStamp DateTime A time stamp of the time the request was received.

API Response Example

JSON

copy

{
    "UCDisputeData": {
        "ClientDetails": {
            "id": "U0VJE9CDD7",
            "name": "Best Client",
        },
        "DisputeDetails": {
            "statusCode": "200",
            "environment": "sandbox",
            "status": "Success",
            "disputeId": "44CFY7VQ0C_B681A5D701",
            "disputeTitle": "The%20best%20%20title.",
            "timeStamp": "2020-07-05T14:29:24+0000"
        }
    }
}

XML

copy

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <UCDisputeData>
      <ClientDetails>
         <id>C2FE87CDD7</id>
         <name>Jasiri Shopper</name>
      </ClientDetails>
      <DisputeDetails>
         <disputeId>44CF4ACC0C_B681A5D701</disputeId>
         <disputeTitle>I want  my laptop fixed now or be given a new now one.</disputeTitle>
         <environment>sandbox</environment>
         <status>Success</status>
         <statusCode>200</statusCode>
         <timeStamp>2020-07-05T14:29:24+0000</timeStamp>
      </DisputeDetails>
   </UCDisputeData>
</root>

Get Disputes

Endpoint

Get disputes by making a HTTP GET request to the following endpoint:

copy

https://www.api.utatuzicenter.com/v1/getdispute

This API endpoint allows Seek Pagination to get a list of disputes using date (before and since) and limit constraints.

To get a list of disputes via the API the following request parameters that are required.

Request Parameters

Parameter Type Description
environment String Required The environment of the dispute. Can be sandbox or production.
before Timestamp Optional The timestamp indicating the end of pagination of the disputes. This is will return a the disputes from the timestamp moving backwards.
since Timestamp Optional The timestamp indicating the start of pagination of the disputes.This is will return a the disputes from the timestamp moving forwards.
limit Integer Optional The maximum number of disputes you want returned. Default limit is 10.

URLs

copy

https://www.api.utatuzicenter.com/v1/getdispute?environment=production
copy

https://www.api.utatuzicenter.com/v1/getdispute?environment=production&limit=100&since=1596968866
copy

https://www.api.utatuzicenter.com/v1/getdispute?environment=production&limit=100&before=1596968866

API response

The body of the response will be a JSON or XML object containing the following fields:

Parameter Sub - Parameter Type Description
UCDisputeData
ClientDetails
id string The id of the client making the request.
name string The name of the company.
Disputes
dispute json A json object with all the relevant fields of a dispute.
Pagination
previous string The url of the previous pagination list.
next string The url of the next pagination list.

API Response Example

JSON

copy

{
    "UCDisputeData": {
        "ClientDetails": {
            "id": "U0VJE9CDD7",
            "name": "Best Client",
        },
        "Disputes": {
            "dispute": {
				"environment": "sandbox",
				"progress": "Success",
				"dateOfSubmission": "2019-11-05T14:29:24+0000",
				"disputeId": "44CFY7VQ0C_B681A5D701",
				"disputeTitle": "The best title.",
				"disputeDescription": "The best description.",
				"disputeAmount": "10200000",
				"disputeResolutionProfessional": "Mwenye Busara",
				"dateOfResolution": "2020-07-05T14:29:24+0000"
				},
            "dispute": {
				"environment": "sandbox",
				"progress": "Success",
				"dateOfSubmission": "2020-01-05T14:29:24+0000",
				"disputeId": "8SHJY7VQ0C_B681A5DUYS",
				"disputeTitle": "The second best title.",
				"disputeDescription": "The second best description.",
				"disputeAmount": "10200000",
				"disputeResolutionProfessional": "Mtatuzi Mkuu",
				"dateOfResolution": "2020-04-05T14:29:24+0000"
				}
		},
        "Pagination": {
            "previous": "https://www.api.utatuzicenter.com/v1/getdispute?environment=production&before=1596968866",
            "next": "https://www.api.utatuzicenter.com/v1/getdispute?environment=production&since=1596968866"
        },
    }
}

XML

copy

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <UCDisputeData>
      <ClientDetails>
         <id>U0VJE9CDD7</id>
         <name>Best Client</name>
      </ClientDetails>
      <Disputes>
         <dispute>
            <element>
               <dateOfResolution>2020-07-05T14:29:24+0000</dateOfResolution>
               <dateOfSubmission>2019-11-05T14:29:24+0000</dateOfSubmission>
               <disputeAmount>10200000</disputeAmount>
               <disputeDescription>The best description.</disputeDescription>
               <disputeId>44CFY7VQ0C_B681A5D701</disputeId>
               <disputeResolutionProfessional>Mwenye Busara</disputeResolutionProfessional>
               <disputeTitle>The best title.</disputeTitle>
               <environment>sandbox</environment>
               <progress>Success</progress>
            </element>
            <element>
               <dateOfResolution>2020-04-05T14:29:24+0000</dateOfResolution>
               <dateOfSubmission>2020-01-05T14:29:24+0000</dateOfSubmission>
               <disputeAmount>10200000</disputeAmount>
               <disputeDescription>The second best description.</disputeDescription>
               <disputeId>8SHJY7VQ0C_B681A5DUYS</disputeId>
               <disputeResolutionProfessional>Mtatuzi Mkuu</disputeResolutionProfessional>
               <disputeTitle>The seond best title.</disputeTitle>
               <environment>sandbox</environment>
               <progress>Success</progress>
            </element>
         </dispute>
      </Disputes>
      <Pagination>
         <next>https://www.api.utatuzicenter.com/v1/getdispute?environment=production&since=1596968866</next>
         <previous>https://www.api.utatuzicenter.com/v1/getdispute?environment=production&before=1596968866</previous>
      </Pagination>
   </UCDisputeData>
</root>

Get Dispute

Endpoint

Get disputes by making a HTTP GET request to the following endpoint:

copy

https://www.api.utatuzicenter.com/v1/getdispute

This API endpoint allows Seek Pagination to get a list of disputes using date (before and since) and limit constraints.

API response

To get specific dispute via the API the following request parameters that are required of the request.

Request Parameters

Parameter Type Description
environment String Required The environment of the dispute. Can be sandbox or production.
id String Required The ID of the dispute.

URL

copy

https://www.api.utatuzicenter.com/v1/getdispute?environment=production&id=44CFY7VQ0C_B681A5D701

API Response Example

JSON

copy

{
    "UCDisputeData": {
        "ClientDetails": {
            "id": "U0VJE9CDD7",
            "name": "Best Client",
        },
        "Dispute": {
			"environment": "sandbox",
			"progress": "Success",
			"dateOfSubmission": "2019-11-05T14:29:24+0000",
			"disputeId": "44CFY7VQ0C_B681A5D701",
			"disputeTitle": "The best title.",
			"disputeDescription": "The best description.",
			"disputeAmount": "10200000",
			"disputeResolutionProfessional": "Mwenye Busara",
			"dateOfResolution": "2020-07-05T14:29:24+0000"
		}
    }
}

XML

copy

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <UCDisputeData>
      <ClientDetails>
         <id>U0VJE9CDD7</id>
         <name>Best Client</name>
      </ClientDetails>
      <Dispute>
         <dateOfResolution>2020-07-05T14:29:24+0000</dateOfResolution>
         <dateOfSubmission>2019-11-05T14:29:24+0000</dateOfSubmission>
         <disputeAmount>10200000</disputeAmount>
         <disputeDescription>The best description.</disputeDescription>
         <disputeId>44CFY7VQ0C_B681A5D701</disputeId>
         <disputeResolutionProfessional>Mwenye Busara</disputeResolutionProfessional>
         <disputeTitle>The best title.</disputeTitle>
         <environment>sandbox</environment>
         <progress>Success</progress>
      </Dispute>
   </UCDisputeData>
</root>

API Errors

The UtatuziCenter API is has can respond with the following errors depending on the request made.

Error Code Description
204 No data provided.
400 Bad Request. Some information is missing.
401 Invalid API credentials.
402 Payment required. Subscription should be renewed before using the API.
403 Request made over plain HTTP. All requests must be made via HTTPS.
404 Not found. Request made to an non-existent endpoint.
405 Method Not Allowed.
422 Incorrect Content Format Sent.