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.
string Your apikey which is found on your account profile page.
string The debtors name
string The debtors email
string Debtor's phone number
string Debtor's second contact phone number [optional]
string Debtor's home contact phone number [optional]
string Debtor's address/location
string Debtor's employer
string Debtor's office address
number Debtor's net pay
string Debtor's monthly salary
string The date the debtor receives salary.
string Last date debtor was paid salary
string Debtor's job description
number Loan full amount
string Total loan repaid till date
number Loan Interest
number How many times loan payment needs to be made before completion
number Amount paid monthly towards the loan full repayment
number Next payment amount
string The account state is either any one of these (Non Performing Loans, Write Off or, Past Due Obligation)
number Total unpaid loan balance
number Loan repayment period left in days
string Bucket
string Branch
number total balance left. This is the amount remaining from the loan plus the interest from the loan.
string Has loan been sold
string debtor credit officer
string Why repayment agreement on loan repayment has not been honored
string Debtor's Next of kin
string Next of kin's Phone Number
string Next of kin's alternative Phone Number (optional)
string Next of kin's email address
string Next of kin's location
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 }