{"info":{"_postman_id":"d80a647c-f272-4af5-b832-2b8d1a55cc7c","name":"Home Space Background Check APIs","description":"

Introduction

\nHome Space is the leading digital background checks platform in Africa.\n

\nWe have exposed our core background check capabilities as RESTful APIs to make it easy for developers to integrate our services and create world-class user on-boarding experiences.\n\n

Developer Account Registration:

\nTo create a developer account, please contact our team at admin@gethomespace.com with the following information:\n

First & Last name
Phone number
Business name
Business email address
Business type
Job title

\n\n

Once we have successfully created your account, we will issue you with an access token that will allow you to use our APIs.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"99936","collectionId":"d80a647c-f272-4af5-b832-2b8d1a55cc7c","publishedId":"UUxxfT7s","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2021-09-24T11:17:25.000Z"},"item":[{"name":"Verifications","id":"d923d110-f48a-4e30-a48b-bd6432855670","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{token}}","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"user\": {\n \"username\": \"254797168810\",\n \"first_name\": \"Antony\",\n \"last_name\": \"Kaguara\",\n \"national_id\": \"27657762\",\n \"date_of_birth\": null,\n \"email\": \"support@gethomespace.com\",\n \"service_type_code\": \"OTH\",\n \"is_consent_provided\": true\n },\n \"verifications\": {\n \"run_id_verification\": true,\n \"run_phone_verification\": true\n }\n}"},"url":"{{hostname}}/api/v1/verifications","description":"

This API is used to request for ID and phone number verification on a given candidate. The candidate information is passed in the body of the request along with the flags that indicate which checks to run on the candidate.

Request Body

\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
user.username	string (required)	The candidate's phone number.
user.first_name	string (required)	The candidate's first name.
user.last_name	string (required)	The candidate's last name.
user.national_id	string (required)	The candidate's national identity number.
user.date_of_birth	string (required)	The candidate's date of birth.
user.email	string (optional)	The candidate's email address.
user.service_type_code*	string (optional)	The type of service being provided by the candidate.
user.is_consent_provided	boolean (required)	Flag indicating whether the candidate has provided consent for account creation.
verifications.run_id_verification	boolean (required)	Flag indicating whether to run identity verification on the candidate.
verifications.run_phone_verification	boolean (required)	Flag indicating whether to run phone number verification on the candidate.

Notes:\n
\n* Please reference the /config API response to retrieve the mapping of service names to service_type_code.

Success Response Body

\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
id	integer	The candidate's account_id.
first_name	string	The candidate's first name.
last_name	string	The candidate's last name.
username	string	The candidate's phone number.
date_of_birth	string	The candidate's date of brith.
email	string	The candidate's email
national_id	string	The candidate's national identity number.
certificate_of_good_conduct_serial_number	string	The serial number listed in the candidate's certificate of good conduct. Extracted from the document via OCR.
is_id_verified	boolean	Flag that indicates whether the candidate's ID number has been verified.
is_confirmed	boolean	Flag that indicates whether the candidate's phone number and account details have been verified.
is_consent_provided	boolean	Flag that indicates whether the candidate provided consent when their account was being created.

","urlObject":{"path":["api","v1","verifications"],"host":["{{hostname}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"d923d110-f48a-4e30-a48b-bd6432855670"},{"name":"Phone Confirmation Code","id":"6155c67d-c8c1-43bd-91d8-242fee74a7e3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","type":"text","value":"Bearer {{token}}"},{"warning":"This is a duplicate header and will be overridden by the Content-Type header generated by Postman.","key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"user\": {\n \"username\": \"254797168810\"\n },\n \"phone_verification_token\": \"545874\"\n}"},"url":"{{hostname}}/api/v1/verifications/confirm","description":"

This API takes a candidate's phone number and the phone confirmation code and verifies that the candidate's phone number belongs to them.

Request Body

\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
user.username	string (required)	The candidate's phone number.
phone_verification_token	string (required)	The 6-digit code that was sent to the candidate's phone number.

Success Response Body

\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
message	string	Message confirming that the candidate's account has been verified.

","urlObject":{"path":["api","v1","verifications","confirm"],"host":["{{hostname}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"6155c67d-c8c1-43bd-91d8-242fee74a7e3"},{"name":"Account","id":"e844d903-a420-4795-9c53-ebb92b140ab2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","type":"text","value":"Bearer {{token}}"}],"url":"{{hostname}}/api/v1/candidates?user_phone_number=254797168810","description":"

This API takes a candidate's phone number and returns their account information.

Request Parameter

\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
user_phone_number	integer (required)	The candidate's phone number. Format: country_code_phone_number. Example: 254722124560.

Success Response Body

\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
id	integer	The candidate's account_id.
first_name	string	The candidate's first name.
last_name	string	The candidate's last name.
username	string	The candidate's phone number.
date_of_birth	string	The candidate's date of brith.
email	string	The candidate's email
national_id	string	The candidate's national identity number.
certificate_of_good_conduct_serial_number	string	The serial number listed in the candidate's certificate of good conduct. Extracted from the document via OCR.
is_id_verified	boolean	Flag that indicates whether the candidate's ID number has been verified.
is_confirmed	boolean	Flag that indicates whether the candidate's phone number and account details have been verified.
is_consent_provided	boolean	Flag that indicates whether the candidate provided consent when their account was being created.

","urlObject":{"path":["api","v1","candidates"],"host":["{{hostname}}"],"query":[{"key":"user_phone_number","value":"254797168810"}],"variable":[]}},"response":[],"_postman_id":"e844d903-a420-4795-9c53-ebb92b140ab2"},{"name":"References","id":"d1130c85-32a6-437a-be9c-c682992866b5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","type":"text","value":"Bearer {{token}}"}],"body":{"mode":"raw","raw":"{\n \"user\": {\n \"username\": \"254797168810\",\n \"first_name\": \"Antony\",\n \"last_name\": \"Kaguara\",\n \"national_id\": \"27657762\",\n \"date_of_birth\": null,\n \"email\": \"support@gethomespace.com\",\n \"service_type_code\": \"OTH\",\n \"is_consent_provided\": true\n },\n \"references\": [\n {\n \"first_name\": \"Antony\",\n \"last_name\": \"Kaguara\",\n \"phone_number\": \"12154601124\",\n \"work_place_name\": \"HomeSpace\",\n \"reference_role\": \"P\"\n },\n {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"phone_number\": \"254797168810\",\n \"work_place_name\": \"Amazon\",\n \"reference_role\": \"DM\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{{hostname}}/api/v1/references","description":"

This API is used to request for reference feedback on a given candidate. The candidate information is passed in the body of the request along with the contact information for the candidate's two references.

Request Body

\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
user.username	string (required)	The candidate's phone number.
user.first_name	string (required)	The candidate's first name.
user.last_name	string (required)	The candidate's last name.
user.national_id	string (required)	The candidate's national identity number.
user.date_of_birth	string (required)	The candidate's date of birth.
user.email	string (optional)	The candidate's email address.
user.service_type_code*	string (optional)	The type of service being provided by the candidate.
user.is_consent_provided	boolean (required)	Flag indicating whether the candidate has provided consent for account creation.
references.first_name	string (required)	The first name of the candidate's reference.
references.last_name	string (required)	The last name of the candidate's reference.
references.phone_number	string (required)	The phone number of the candidate's reference.
references.work_place_name	string (required)	The name of the business where the candidate's reference currently works.
references.reference_role	string (required)	A key describing the nature of the reference's relationship to the candidate. Accepted values are: (\"DM\"=Direct Manager), (\"P\"=Peer).

Notes:\n
\n* Please reference the /config API response to retrieve the mapping of service names to service_type_code.\n
\n** Feedback quality is generated from the rating submitted by the reference\n
\n-We support exactly 2 references per candidate.

Success Response Body

\nList of reference objects.\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
first_name	string	The reference's first name.
last_name	string	The reference's last name.
phone_number	string	The reference's phone number.
feedback_rating	string	The rating provided by the candidate's reference.
feedback_comments	string	The comments submitted by the this reference.
feedback_quality	string	A summary of the general sentiment from the reference's feedback comments. Available values are: Positive \| Neutral \| Negative.
work_place_name	string	The name of the business where the candidate's reference currently works.
reference_role	string	A key describing the nature of the reference's relationship to the candidate. Accepted values are: (\"DM\"=Direct Manager), (\"P\"=Peer).
national_id	string	The reference's national identification number.
is_reference_national_id_verified	boolean	Flag indicating whether the reference's national ID number has been verified.

","urlObject":{"path":["api","v1","references"],"host":["{{hostname}}"],"query":[{"disabled":true,"key":"user","value":"254797168810"}],"variable":[]}},"response":[],"_postman_id":"d1130c85-32a6-437a-be9c-c682992866b5"},{"name":"References","id":"9026462b-b76f-44b5-8b71-f0504556a830","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","type":"text","value":"Bearer {{token}}"}],"body":{"mode":"formdata","formdata":[]},"url":"{{hostname}}/api/v1/references?user_phone_number=12154601124","description":"

This API takes a candidate's phone number and returns the list of their references.

Request Parameter

\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
user_phone_number	integer (required)	The candidate's phone number. Format: country_code_phone_number. Example: 254722124560.

Success Response Body

\nList of reference objects.\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
first_name	string	The reference's first name.
last_name	string	The reference's last name.
phone_number	string	The reference's phone number.
feedback_rating	string	The rating provided by the candidate's reference.
feedback_comments	string	The comments submitted by the this reference.
feedback_quality	string	A summary of the general sentiment from the reference's feedback comments. Available values are: Positive \| Neutral \| Negative.
work_place_name	string	The name of the business where the candidate's reference currently works.
reference_role	string	A key describing the nature of the reference's relationship to the candidate. Accepted values are: (\"DM\"=Direct Manager), (\"P\"=Peer).
national_id	string	The reference's national identification number.
is_reference_national_id_verified	boolean	Flag indicating whether the reference's national ID number has been verified.

","urlObject":{"path":["api","v1","references"],"host":["{{hostname}}"],"query":[{"key":"user_phone_number","value":"12154601124"}],"variable":[]}},"response":[],"_postman_id":"9026462b-b76f-44b5-8b71-f0504556a830"},{"name":"Background Checks","id":"5451cc6b-aab2-4cd3-8623-ac99d2cc80d0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","type":"text","value":"Bearer {{token}}"}],"body":{"mode":"formdata","formdata":[]},"url":"{{hostname}}/api/v1/background-checks?user_phone_number=254797168810","description":"

This API takes a candidate's phone number and returns their background check status information.

Request Parameter

\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
user_phone_number	integer (required)	The candidate's phone number. Format: country_code_phone_number. Example: 254722124560.

Success Response Body

\nList of background check objects.\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
id	integer	The object id for this background check object.
user_id	integer	The candidate's user_id
id_verification_status	string	The current status of the candidate's ID verification check. Expected values are: (\"A\"=\"Approved\"),(\"D\"=\"Declined\"),(\"U\"=\"Unknown\").
police_verification_status	string	The current status of the candidate's certificate of good conduct serial number verification check. Expected values are: (\"A\"=\"Approved\"),(\"D\"=\"Declined\"),(\"U\"=\"Unknown\").
references_verification_status	string	The current status of the candidate's reference feedback submission. Expected values are: (\"A\"=\"Approved\"),(\"U\"=\"Unknown\").
created_at	string	The date the background check object was created.
updated_at	string	The date the background check object was last updated.

","urlObject":{"path":["api","v1","background-checks"],"host":["{{hostname}}"],"query":[{"key":"user_phone_number","value":"254797168810"}],"variable":[]}},"response":[],"_postman_id":"5451cc6b-aab2-4cd3-8623-ac99d2cc80d0"},{"name":"Document","id":"c7d3e613-b27f-4ec5-8ce8-332118f39834","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","type":"text","value":"Bearer {{token}}"},{"warning":"This is a duplicate header and will be overridden by the Content-Type header generated by Postman.","key":"Content-Type","value":"multipart/form-data","type":"text"}],"body":{"mode":"formdata","formdata":[{"key":"name","value":"sample_id","type":"text"},{"key":"type_code","value":"CGC","type":"text"},{"key":"file","type":"file","src":"/Users/antonykaguara/Documents/Jobs/HomeSpace/Product/Sample Documents/sample_cgc.jpg"},{"key":"username","value":"254797168810","type":"text"}]},"url":"{{hostname}}/api/v1/documents","description":"

This API supports uploading candidate files for digital storage and OCR(optional).

Request Parameter (Form Data)

\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
name	string (optional)	The user-friendly name of the document.
type_code*	string (required)	The type_code that describes the type of document being uploaded.
file	string (required)	The file to be uploaded.
username	string (required)	The candidate's phone number.

Notes:

*Supported type codes are:

\"IDD\" = \"ID Document\"
\"CGC\" = \"Certificate of Good Conduct\"
\"R\" = \"Curriculum Vitae\"
\"CI\" = \"Certification Level I\"
\"CII\" = \"Certification Level II\"
\"CIII\" = \"Certification Level III\"
\"NSSF\" = \"NSSF Card\"
\"NHIF\" = \"NHIF Card\"
\"WP\" = \"Work Photo\"
\"WC\" = \"Work Contract\"
\"ICD\" = \"Incorporation Document\"
\"TD\" = \"Tax Document\"

\n\n

We currently support OCR on Certificate of Good Conduct documents. To request for OCR support for a new document type listed above, please send us 5 samples of that document to admin@gethomespace.com.

Success Response Body

\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
user_id	integer	The candidate's user_id.
name	string	The user-friendly name of the document.
type_code	string	The type_code that describes the type of document being uploaded.
created_at	string	The date the file was created.
url	string	The URL that contains the document ID.
view_url	string	The file download URL.

","urlObject":{"path":["api","v1","documents"],"host":["{{hostname}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"c7d3e613-b27f-4ec5-8ce8-332118f39834"},{"name":"Documents","id":"c490f448-1b06-41ce-b7f4-ada077b1180d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","type":"text","value":"Bearer {{token}}"}],"body":{"mode":"formdata","formdata":[]},"url":"{{hostname}}/api/v1/documents?user_phone_number=254797168810","description":"

This API returns the list of documents associated with the candidate.

Request Parameter

\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
user_phone_number	integer (required)	The candidate's phone number. Format: country_code_phone_number. Example: 254722124560.

Success Response Body

\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
user_id	integer	The candidate's user_id.
name	string	The user-friendly name of the document.
type_code	string	The type_code that describes the type of document being uploaded.
created_at	string	The date the file was created.
url	string	The URL that contains the document ID.
view_url	string	The file download URL.

","urlObject":{"path":["api","v1","documents"],"host":["{{hostname}}"],"query":[{"key":"user_phone_number","value":"254797168810"}],"variable":[]}},"response":[],"_postman_id":"c490f448-1b06-41ce-b7f4-ada077b1180d"},{"name":"Document Image","id":"6de94da5-d9f0-4bce-92bc-036cfabe0295","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","type":"text","value":"Bearer {{token}}"}],"body":{"mode":"formdata","formdata":[]},"url":"{{hostname}}/api/v1/document-image?document_id=76&user_phone_number=254797168810","description":"

This API returns the file object for the document associated with the document_id and the candidate provided in the request.

Request Parameter

\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
document_id	integer (required)	The candidate's document id.
user_phone_number	integer (required)	The candidate's phone number. Format: country_code_phone_number. Example: 254722124560.

Success Response Body

\n\n

File Object.

\n","urlObject":{"path":["api","v1","document-image"],"host":["{{hostname}}"],"query":[{"key":"document_id","value":"76"},{"key":"user_phone_number","value":"254797168810"}],"variable":[]}},"response":[],"_postman_id":"6de94da5-d9f0-4bce-92bc-036cfabe0295"},{"name":"Background Report PDF","id":"07eb6341-e428-4c25-a3b5-99ace23bf3dd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{token}}","type":"text"}],"url":"{{hostname}}/api/v1/report/pdf?user_phone_number=254797168810","description":"

This API returns the candidate's background check report as a PDF file.

Request Parameter

\n\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field Name	Type	Description
user_phone_number	integer (required)	The candidate's phone number. Format: country_code_phone_number. Example: 254722124560.

Success Response Body

\n\n

PDF File.

\n","urlObject":{"path":["api","v1","report","pdf"],"host":["{{hostname}}"],"query":[{"key":"user_phone_number","value":"254797168810"}],"variable":[]}},"response":[],"_postman_id":"07eb6341-e428-4c25-a3b5-99ace23bf3dd"}]}