Api Docs

Introduction

Learn how to integrate our APIs into your application

API Basics

The DebtRecuva API gives you access to pretty much all the features you can use on our dashboard and lets you extend them for use in your application. It strives to be RESTful and is organized around the main resources you would be interacting with - with a few notable exceptions.

Before you do anything
You should create a free account on Debtrecuva that you can use the API against.

Sample Requests

We provide sample API calls next to each method using javascript. All you need to do is insert your specific parameters, and you can test the calls from your web browsers.

You can also use Postman. Postman is an easy to use API development environment for making HTTP requests. You can download Postman to make testing the API easier.

Requests and Response

Both request body data and response data are formatted as JSON. Content type for responses will always be application/json. Generally, all responses will be in the following format:

The message key is a string which will contain a summary of the response and its status. For instance when trying to retrieve a list of customers, message might read “Customers retrieved”. In the event of an error, the message key will contain a description of the error as with the authorization header situation above. This is the only key that is universal across requests.

The data key is where you want to look at for the result of your request. It can either be an object, or an array depending on the request made. For instance, a request to retrieve a single customer will return a customer object in the data key, while the key would be an array of customers if a list is requested instead.

Response Format

 1  {
 2     "status" : [boolean], // Only true if the details provided could be processed and no error occured while processing  
 3     "message": [string], // Explains why status is false... Entirely informational. Please only log this but do not use for your checks  
 4     "data": [object] // contains actionable result of processing if present  
 5  }

Authentication

Authenticate your API calls by including your secret key in the Authorization header of every request you make. You can manage your API keys from the profile. Simply go there and click on the Reveal API key button.

We provide you with an API key which is meant to be used from your front-end when integrating DebtRecuva's functionalities into your own interface. By design, your apikey cannot be used to modify your account information. The apikey however has to be kept secret. If for any reason you believe your apikey has been compromised or you wish to reset them, you can do so from your profile page.

Secure your API key
Do not commit your API key to git, or display them on your custom client side interface.

API requests made without apikeys will fail with the status code 401: Unauthorized. All API requests must be sent via POST.

Get Profile Data

Get your profile data from your api request

apikey
string
Your apikey which is found on your account profile page.

/externalApi-access/profile

Parameter
 apikey:  [apikey]

Sample Response

1 {
2    "status": "false",
3    "message": "Company data fetched successfully",
4    "data": {
5        "company_id": "nr413c2ve8582e36r4130s2l0o81a4",
6        "companyName": "Varmland Invest Limited",
7        "companyEmail": "Varmland@gmail.com",
8        "imagepath": "4097195861pexels-pixabay-269077.jpg",
9        "companyPhone": "18143008234",
10        "companyAddress": "4758  Lamberts Branch Road",
11       "companyType": "Mortgage Bank",
12       "date_registered": "April 10, 2021"
13    }
14 }

Add Debtor Account

Add the details of a debtor for effective and detailed debt collection by the DebtRecuva team.

apikey
string
Your apikey which is found on your account profile page.
name
string
The debtors name
mail
string
The debtors email
phone
string
Debtor's phone number
phonetwo
string
Debtor's second contact phone number [optional]
homePhone
string
Debtor's home contact phone number [optional]
address
string
Debtor's address/location
employer
string
Debtor's employer
officeAddress
string
Debtor's office address
netpay
number
Debtor's net pay
salary
string
Debtor's monthly salary
salaryPaymentDate
string
The date the debtor receives salary.
lastPaymentDate
string
Last date debtor was paid salary
jobDescription
string
Debtor's job description
loanAmount
number
Loan full amount
totalPaid
string
Total loan repaid till date
loanInterest
number
Loan Interest
loanInstallments
number
How many times loan payment needs to be made before completion
monthlyRepayment
number
Amount paid monthly towards the loan full repayment
totalDue
number
Next payment amount
accountState
string
The account state is either any one of these (Non Performing Loans, Write Off or, Past Due Obligation)
principalDue
number
Total unpaid loan balance
daysinarreas
number
Loan repayment period left in days
bucket
string
Bucket
branch
string
Branch
totalBalance
number
total balance left. This is the amount remaining from the loan plus the interest from the loan.
loansold
string
Has loan been sold
creditOfficer
string
debtor credit officer
defaultReasons
string
Why repayment agreement on loan repayment has not been honored
nextofkinName
string
Debtor's Next of kin
nextofkinPhone
string
Next of kin's Phone Number
nextofkinPhonetwo
string
Next of kin's alternative Phone Number (optional)
nextofkinEmail
string
Next of kin's email address
nextofkinAddress
string
Next of kin's location
nextofkinRelationship
string
Debtor's relationship to next of kin's

/externalApi-access/add-debtor

Parameter
 apikey:  [apikey]
 name:  [name of the debtor]
 mail:  [email of the debtor]
 phone:  [debtor's phone number]
 phonetwo:  [debtor's alternative phone number (optional)]
 homePhone:  [debtor's home phone number (optional)]
 address:  [Address of debtor]
 employer:  [debtor's emloyer]
 officeAddress:  [debtor's office address]
 netpay:  [debtor's net pay]
 salary:  [debtor's salary amount]
 paymentDate:  [debtor's salary payment date]
 lastPaymentDate:  [debtor's last salary payment date]
 jobDescription:  [debtor's Job Description]
 loanAmount:  [Loan full amount]
 totalPaid:  [Loan amount repaid]
 loanInterest:  [Loan Interest]
 loanInstallments:  [Loan Installments]
 monthlyRepayment:  [Amount paid monthly towards loan payment]
 totalDue:  [total amount to pay next]
 accountState:  [Account State]
 principalDue:  [Total unpaid loan balance]
 daysinarreas:  [Loan repayment period left in days]
 bucket:  [bucket]
 branch:  [branch]
 totalBalance:  [total balance]
 loansold:  [Has loan been sold]
 creditOfficer:  [credit officer]
 defaultReasons:  [Why repayment loans has not been honored]
 nextofkinName:  [Next of kin's Name]
 nextofkinPhone:  [Next of kin's Phone Number]
 nextofkinPhonetwo:  [Next of kin's alternative Phone Number (optional)]
 nextofkinEmail:  [Next of kin's email address]
 nextofkinAddress:  [Next of kin's location]
 nextofkinRelationship:  [Relationship to next of kin's]

Sample Response

1 {
2    "status": "false",
3    "message": "Debtor has been added successfully"
4 }

Get All Debtors

Get the list of all the debtors added into your account.

apikey
string
Your apikey which is found on your account profile page.


/externalApi-access/companydebtors

Parameter
 apikey:  [apikey]

Sample Response

1  {
2     "status": "false",
3     "message": "Debtors List received successfully",
4     "count": 2,
5     "data": [
6          {
7              "accountid": "80aeet81053coa138h4nc7s06o1f423u2t4tt",
8              "accountstate": "Past Due Obligation",
9              "debtorname": "John Doe",
10             "debtors_homePhone": "09120129832",
11             "debtormobile": "091101290000",
12             "debtormobile2": "08110190000",
13             "debtoraddress": "address",
14             "debtoremail": "jd@example.mail",
15             "debtoremployer": "Jane Doe",
16             "debtor_officelocation": "address",
17             "debtors_netpay": "32897",
18             "debtors_jobdescription": "job description",
19             "debtors_salary_paymentdate": "12/11/2019",
20             "debtors_lastpayment_amount": "19327",
21             "debtors_lastpayment_date": "16/01/2021",
22             "loan_interest_rate": "32",
23             "loan_number_of_installments": "327",
24             "monthly_repayments": "3287",
25             "total_balance": "3268",
26             "default_reasons": "Why have failed to make payment.",
27             "total_paid": "137841",
28             "loanamount": "3241798",
29             "totalDue": "124326",
30             "debtor_nextofkin": "James",
31             "nextofkin_mobile": "08110190000",
32             "nextofkin_mobile2": "08110190000",
33             "nextofkin_address": "address",
34             "nextofkin_relationship": "Cousin",
35             "nextofkin_email": "james@j.d",
36             "principalDue": "272123",
37             "days_in_arreas": "420",
38             "branch": "Abuja",
39             "bucket": "No",
40             "loansoldby": "Not sold",
41             "creditofficer": "Michael Gonzalez",
42             "lastModified": "May 13, 2021",
43             "date_created": "May 13, 2021"
44        },
45        {
46             "accountid": "y7aewt81053mlopzzh4nc7s06o1f403u2t401",
47             "accountstate": "Write Off",
48             "debtorname": "Mikel Smith",
49             "debtors_homePhone": "0911002000",
50             "debtormobile": "091101290010",
51             "debtormobile2": "08110190010",
52             "debtoraddress": "address",
53             "debtoremail": "miksmith@example.mail",
54             "debtoremployer": "Joshua Gerald",
55             "debtor_officelocation": "address",
56             "debtors_netpay": "32897",
57             "debtors_jobdescription": "job description",
58             "debtors_salary_paymentdate": "22/01/2017",
59             "debtors_lastpayment_amount": "19327",
60             "debtors_lastpayment_date": "21/11/2020",
61             "loan_interest_rate": "32",
62             "loan_number_of_installments": "327",
63             "monthly_repayments": "3287",
64             "total_balance": "3268",
65             "default_reasons": "Why have failed to make payment.",
66             "total_paid": "137841",
67             "loanamount": "3241798",
68             "totalDue": "124326",
69             "debtor_nextofkin": "James Franklin",
70             "nextofkin_mobile": "08110190001",
71             "nextofkin_mobile2": "08110190001",
72             "nextofkin_address": "address",
73             "nextofkin_relationship": "Friend",
74             "nextofkin_email": "jamyfox@example.net",
75             "principalDue": "272123",
76             "days_in_arreas": "420",
77             "branch": "Abuja",
78             "bucket": "No",
79             "loansoldby": "Not sold",
80             "creditofficer": "Michael Gonzalez",
81             "lastModified": "May 10, 2021",
82             "date_created": "May 10, 2021"
83        }
84     ]
85  }

View Debtor Detail

Get a single debtor detail.

apikey
string
Your apikey which is found on your account profile page.

accountid
string
This is id for the specific debtor account


/externalApi-access/companydebtor

Parameter
 apikey:  [apikey]
 accountid`:  [debtor id]

Sample Response

1  {
2     "status": "false",
3     "message": "Debtors List received successfully",
4     "data": [
5          {
6              "accountid": "80aeet81053coa138h4nc7s06o1f423u2t4tt",
7              "accountstate": "Past Due Obligation",
8              "debtorname": "John Doe",
9              "debtors_homePhone": "09120129832",
10             "debtormobile": "091101290000",
11             "debtormobile2": "08110190000",
12             "debtoraddress": "address",
13             "debtoremail": "jd@example.mail",
14             "debtoremployer": "Jane Doe",
15             "debtor_officelocation": "address",
16             "debtors_netpay": "32897",
17             "debtors_jobdescription": "job description",
18             "debtors_salary_paymentdate": "12/11/2019",
19             "debtors_lastpayment_amount": "19327",
20             "debtors_lastpayment_date": "16/01/2021",
21             "loan_interest_rate": "32",
22             "loan_number_of_installments": "327",
23             "monthly_repayments": "3287",
24             "total_balance": "3268",
25             "default_reasons": "Why have failed to make payment.",
26             "total_paid": "137841",
27             "loanamount": "3241798",
28             "totalDue": "124326",
29             "debtor_nextofkin": "James",
30             "nextofkin_mobile": "08110190000",
31             "nextofkin_mobile2": "08110190000",
32             "nextofkin_address": "address",
33             "nextofkin_relationship": "Cousin",
34             "nextofkin_email": "james@j.d",
35             "principalDue": "272123",
36             "days_in_arreas": "420",
37             "branch": "Abuja",
38             "bucket": "No",
39             "loansoldby": "Not sold",
40             "creditofficer": "Michael Gonzalez",
41             "lastModified": "May 13, 2021",
42             "date_created": "May 13, 2021"
43        }
44     ]
45  }

Delete Debtor Account

Delete a debtors' account. This action cannot be reversed

apikey
string
Your apikey which is found on your account profile page.

accountid
string
This is id for the specific debtor account


/externalApi-access/delete-debtor

Parameter
 apikey:  [apikey]
 debtorid:  [debtor id]

Sample Response

1  {
2     "status": "false",
3     "message": "Debtor detail deleted successfully"   
4  }

Add Address

Add an address which is to be verified.

apikey
string
Your apikey which is found on your account profile page.

name
string
This is the name of the person who is tied to the address.

number
string
This is the phone number of the person who is tied to the address

address
string
This is the address

jobDescription
string
This is the employer nature of what the user does at work.

officeaddress
string
This is the address of the users' workplace

homeaddress
string
This is the home address of the user tied to this account.


/externalApi-access/add-address

Parameter
 apikey:  [apikey]
 name:  [Name]
 number:  [Phone Numbner]
 location:  [Location]
 employer:  [Employer]
 jobDescription:  [Job Description]
 officeaddress:  [Office Address]
 homeaddress:  [Home Address]

Sample Response

1  {
2     "status": "false",
3     "message": "Address added successfully"   
4  }

Add Address

Get all added addresses.

apikey
string
Your apikey which is found on your account profile page.


/externalApi-access/allAddresses

Parameter
 apikey:  [apikey]

Sample Response

1  {
2     "status": "false",
3     "message": "Address records received successfully",   
4     "count": 1,
5     "0": {
6         "account_id": "zy6db5da3r572di14qps5oj73ev0a02ytr21ds0166",  
7         "account_holder_name": "Justin Ekwueme",
8         "mobile_phone": "09029932110",
9         "location": "17 Ogwo Road",
10        "employer": "Igwe Okpara",
11        "job_description": "Plumber",
12        "office_address": "27 Park Road Aba",
13        "clearedstatus": "pending",
14        "remark": null,
15        "date_added": "June 29, 2021"
16    }
17  }

Delete Address

Delete an address

apikey
string
Your apikey which is found on your account profile page.

addressid
string
Unique identifier for the address to be deleted


/externalApi-access/deleteAddress

Parameter
 apikey:  [apikey]
 addressid:  [addressid]

Sample Response

1  {
2     "status": "false",
3     "message": "Address Record deleted successfully"   
4  }