The Property Hive API is a robust, RESTful web service designed to power real estate management applications. It provides a comprehensive set of endpoints that facilitate various operations essential to property management, user authentication, and financial tracking within the real estate industry.
\nAuthentication and User Management
\nCompany registration
\nUser login and logout
\nPassword management (including forgot and reset password functionalities)
\nProfile Management
\nCompany profile creation and updates
\nUser profile retrieval and management
\nProperty Management
\nProperty listing and information retrieval
\n(Potential future features for property creation, updating, and deletion)
\nFinancial Operations
\nInvoice generation and retrieval
\nTransaction tracking
\nThe Base Urls are:
\nhttps://api.propertyhive.com.ng/\nhttps://express-api.propertyhive.com.ng/\n\nThe current version of the API is v1, which is reflected in the endpoint URLs (e.g., /api/v1/login/).
The API uses Bearer Token authentication. After a successful login, clients receive an access token which must be included in the Authorization header of subsequent requests:
\nAuthorization: Bearer <access_token>\n\nThe API accepts and returns data in JSON format. Ensure that requests with a body have the Content-Type: application/json header set.
The API uses standard HTTP status codes to indicate the success or failure of requests. Common status codes include:
\n200 OK: Successful request
\n201 Created: Successful creation of a resource
\n400 Bad Request: Invalid input or parameters
\n401 Unauthorized: Missing or invalid authentication
\n403 Forbidden: Authenticated but lacking necessary permissions
\n404 Not Found: Requested resource doesn't exist
\n429 Too Many Requests: Rate limit exceeded
\n500 Internal Server Error: Server-side issues
\nThe API implements rate limiting to prevent abuse and ensure fair usage. Clients should handle 429 Too Many Requests responses gracefully, potentially implementing exponential backoff strategies.
\nFor endpoints that may return large datasets (e.g., listing properties or transactions), pagination details should be implemented. Clients should be prepared to handle paginated responses and navigate through result sets accordingly.
\nThe API employs HTTPS for all requests, ensuring data encryption in transit. The use of bearer tokens for authentication adds an additional layer of security, protecting against unauthorized access to sensitive operations and data.
\nAuthentication: Handles user registration, login, logout, and password management.
\nProfile Management: Allows retrieval and updates of company and user profiles.
\nProperty Management: Facilitates property-related operations.
\nFinancial Operations: Manages invoices and tracks transactions.
\nThis API provides a robust foundation for building comprehensive real estate management applications, offering essential features for user account management, property listings, and financial operations within the Property Hive ecosystem.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Property Hive API Introduction","slug":"property-hive-api-introduction"}],"owner":"38661757","collectionId":"ee559a9e-8b8e-4139-8aaa-e7047f0e6189","publishedId":"2sAXxMgDfr","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2024-10-05T23:32:42.000Z"},"item":[{"name":"Version 1","item":[{"name":"Authentication","item":[{"name":"Register Company","id":"e6e4d3ad-d3db-459d-b2e3-063443ab2777","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"email\":\"property@gmail.com\",\n \"password\":\"property2\",\n \"fname\": \" john \",\n \"lname\": \"boss\",\n \"business_name\": \" property hive \",\n \"profile_picture\": null,\n \"phone_number\": \"080123456\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.propertyhive.com.ng/api/v1/register/company/","description":"POST Register Company: Registers a new company on the platform
Post Register customer :registers / creates account for a new customer
{\n \"errors\": {\n \"password\": [\n \"Password must contain at least one digit.\"\n ]\n }\n}\n\nSuccessful registration
\n{\n \"message\": \"Customer created successfully\",\n \"data\": {\n \"email\": \"abdulhamidbabawale@gmail.com\",\n \"fname\": \"john\",\n \"lname\": \"boss\",\n \"profile_picture\": null,\n \"phone_number\": \"0801234\"\n }\n}\n\nnote: after the user is done registering they will reveive 5 digit email verification which will be sent to the verify email endpoint https://api.propertyhive.com.ng//api/v1/verify-email/
POST Forgot Password: Initiates the password recovery process for a company account.
POST Login Company: Authenticates the company using credentials to log in.
**Login Company:**this endpoint authenticates customers
\nresponse: if a company tries to login
{\n \"non_field_errors\": [\n \"Not allowed to login as a customer\"\n ]\n}\n\nResponse:account doesn't exist
{\n \"detail\": \"No active account found with the given credentials\"\n}\n\n{\n \"non_field_errors\": [\n \"User not found\"\n ]\n}\n\nresponse: succesfull login
{\n \"refresh\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTcyODQwMzM1MSwiaWF0IjoxNzI4MzE2OTUxLCJqdGkiOiJmY2FkYWI2ZjY2M2Q0MzBiYWUwZDA5OWQ0NTFjNDVmYiIsInVzZXJfaWQiOjQ2fQ.yuCF0Uh37EenRmikAHjvNzlCbqQWRrEjj5TibbRFVIY\",\n \"access\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzI4MzI0MTUxLCJpYXQiOjE3MjgzMTY5NTEsImp0aSI6ImU2OTY2NzkyOTJjNDQzMTBhZmI1NzU2ODExOGZiNTViIiwidXNlcl9pZCI6NDZ9.K2xCk5_RjFGrsmX9KR2ZMa12MZ-bN9leMsKQviV3gB0\"\n}\n\nPOST Logout: Logs out the authenticated company from the platform
POST Reset Password: Resets the password for a company account after verification.
This endpoint is used to verify an email address.
\nRequest Body
\nemail (string, required): The email address to be verified.
code (string, required): The verification code.
Response
\nStatus: 400
\nContent-Type: application/json
\nmessage (string): A message indicating the result of the verification process.
The Authentication section handles user registration, login, logout, and password management functionalities.
\nEndpoint: POST /api/v1/register/company/
This endpoint allows new companies to register on the Property Hive platform.
\nRequest Body:
\n{\n \"email\": \"propertyhive@gmail.com\",\n \"password\": \"property\",\n \"fname\": \"john\",\n \"lname\": \"boss\",\n \"business_name\": \"property hive\",\n \"profile_picture\": null,\n \"phone_number\": \"080123456\"\n}\n\nFields:
\nemail: (string, required) The company's email address.
password: (string, required) The chosen password for the account.
fname: (string, required) First name of the company representative.
lname: (string, required) Last name of the company representative.
business_name: (string, required) The official name of the company.
profile_picture: (string, nullable) URL or reference to a profile picture.
phone_number: (string, required) Contact number for the company.
Response:
\n201 Created: Registration successful
\n400 Bad Request: Invalid input data
\nNotes:
\nEnsure all required fields are provided.
\nThe email and business name should be unique in the system.
\nPassword should meet the platform's security requirements (if any).
\nEndpoint: POST /api/v1/login/
This endpoint authenticates a company and provides access tokens for subsequent API calls.
\nRequest Body:
\n{\n \"email\": \"property@gmail.com\",\n \"password\": \"property2\"\n}\n\nResponse:
\n{\n \"refresh\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"access\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"\n}\n\nFields:
\nrefresh: JWT refresh token for obtaining new access tokens.
access: JWT access token for authenticating API requests.
Response Codes:
\n200 OK: Successful login
\n401 Unauthorized: Invalid credentials
\nNotes:
\nThe access token should be included in the Authorization header of subsequent requests.
\nThe refresh token can be used to obtain a new access token when it expires.
\nEndpoint: POST /api/v1/log-out/
This endpoint logs out the currently authenticated user, invalidating their access token.
\nRequest Body: Empty
\nHeaders:
\nAuthorization: BearerResponse:
\n200 OK: Successful logout
\n401 Unauthorized: Invalid or missing token
\nNotes:
\nAfter logout, the access token becomes invalid and should not be used for further requests.
\nThe client should discard the stored tokens after a successful logout.
\nEndpoint: POST /api/v1/forgot-password/
This endpoint initiates the password reset process for a user who has forgotten their password.
\nRequest Body:
\n{\n \"email\": \"propertyhive@gmail.com\"\n}\n\nResponse:
\n200 OK: Password reset email sent
\n400 Bad Request: Invalid email or user not found
\n429 Too Many Requests: Rate limit exceeded
\nNotes:
\nThis endpoint is rate-limited to prevent abuse.
\nA password reset link or token will typically be sent to the provided email address.
\nEndpoint: POST /api/v1/reset-password/
This endpoint allows users to set a new password using a reset token.
\nRequest Body:
\n{\n \"token\": \"<reset_token>\",\n \"newPassword\": \"123admin\"\n}\n\nResponse:
\n200 OK: Password successfully reset
\n400 Bad Request: Invalid token or password
\n404 Not Found: Token not found or expired
\nNotes:
\nThe token is typically provided via email after initiating the forgot password process.
Ensure the new password meets any required security criteria.
\nURL:/api/v1/dashboard/
Method: GET
Description: This endpoint retrieves the dashboard statistics for a company, including profile views, total listings, active listings, and sold properties.
\n| timestamp | Array(String) | An array containing the dates when profile views were recorded. |
| profile_views | Array(Number) | An array representing the number of views the profile received per day. |
| total_listings | Number | Total number of property listings associated with the company. |
| active_listings | Number | Number of currently active property listings. |
| sold_properties | Number | Number of properties sold by the company. |
GET Get Company Profile: Retrieves the profile details of a company
\n","urlObject":{"path":["api","v1","company-profile",""],"host":["https://api.propertyhive.com.ng/"],"query":[],"variable":[]}},"response":[],"_postman_id":"f12b0898-db25-46e4-938b-41740c5d2ebd"},{"name":"Generate Company Url","id":"d9f21f60-819d-4eb5-9210-f02e5efc98e9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"https://api.propertyhive.com.ng//api/v1/company/generate-url/","urlObject":{"path":["api","v1","company","generate-url",""],"host":["https://api.propertyhive.com.ng/"],"query":[],"variable":[]}},"response":[],"_postman_id":"d9f21f60-819d-4eb5-9210-f02e5efc98e9"}],"id":"dea5b528-e714-4ef0-b8aa-0a5bc5279308","description":"The Profile Management section handles operations related to company and user profiles.
\nEndpoint: PUT /api/v1/company-profile/
This endpoint allows companies to update their profile information.
\nHeaders:
\nAuthorization: BearerRequest Body:
\n{\n \"data\": {\n \"phone_number\": \"080123456\",\n \"company_address\": \"lagos\",\n \"company_logo\": null,\n \"company_banner\": null,\n \"title\": \"best in lagos\",\n \"description\": \"we are aimed at being the best\",\n \"instagram\": \"property_hive\",\n \"linkedin\": null,\n \"facebook\": null,\n \"twitter\": null\n }\n}\n\nFields:
\nAll fields are optional and represent updatable company information.
\nSocial media fields (instagram, linkedin, facebook, twitter) can be null if not applicable.
Response:
\n200 OK: Profile successfully updated
\n400 Bad Request: Invalid input data
\n401 Unauthorized: Invalid or missing token
\nNotes:
\nOnly authenticated companies can update their own profile.
\nFields not included in the request body will remain unchanged.
\nEndpoint: GET /api/v1/company-profile/
This endpoint retrieves the profile information of the authenticated company.
\nHeaders:
\nAuthorization: BearerResponse:
\n200 OK: Successfully retrieved company profile
\n401 Unauthorized: Invalid or missing token
\nNotes:
\nEndpoint: GET /api/v1/profile/
This endpoint retrieves the profile information of the authenticated user.
\nHeaders:
\nAuthorization: BearerResponse:
\n200 OK: Successfully retrieved user profile
\n401 Unauthorized: Invalid or missing token
\nNotes:
\nThis endpoint may return different information compared to the company profile endpoint.
\nIt's designed for individual user accounts within a company, if applicable.
\nGET Retrieve Properties: Retrieves a list of all available properties.
\n","urlObject":{"path":["v1","properties",""],"host":["https://express-api.propertyhive.com.ng/api"],"query":[],"variable":[]}},"response":[{"id":"4db2c190-0f8a-40f8-888b-6f819555f4f2","name":"Retrieve Properties","originalRequest":{"method":"GET","header":[],"url":"https://express-api.propertyhive.com.ng/api/v1/properties/"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.24.0 (Ubuntu)"},{"key":"Date","value":"Tue, 01 Oct 2024 12:00:14 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"2174"},{"key":"Connection","value":"keep-alive"},{"key":"X-Powered-By","value":"Express"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"ETag","value":"W/\"87e-a1/IvX1T7COHaLffP0oNlOnuKUM\""}],"cookie":[],"responseTime":null,"body":"{\n \"statusCode\": 200,\n \"totalCount\": 3,\n \"page\": 1,\n \"limit\": 10,\n \"properties\": [\n {\n \"id\": 48,\n \"name\": \"Wisdom Fred Apartments\",\n \"state\": \"San Francisco\",\n \"city\": \"Ohio\",\n \"address\": \"20 main street\",\n \"description\": \"A Nice Landed Property\",\n \"squaremeters\": \"450ft\",\n \"property_type\": \"apartment\",\n \"number_of_bathrooms\": null,\n \"number_of_bedrooms\": null,\n \"installment_duration\": \"7\",\n \"payment_frequency\": \"20000\",\n \"down_payment\": \"1000\",\n \"installment_payment_price\": 1000,\n \"keywords\": [\n \"Apartment\",\n \"Lagos\"\n ],\n \"price\": 2000,\n \"is_sold\": false,\n \"date_sold\": null,\n \"created_at\": \"2024-10-01T11:27:17.601Z\",\n \"updated_at\": \"2024-10-01T11:27:17.601Z\",\n \"sellerid_id\": 1,\n \"common_user\": {\n \"id\": 1,\n \"email\": \"test@gmail.com\",\n \"fname\": \"test\",\n \"lname\": \"test\",\n \"business_name\": null\n },\n \"common_propertyimages\": []\n },\n {\n \"id\": 49,\n \"name\": \"Lagos\",\n \"state\": \"Lagos\",\n \"city\": \"Lagos\",\n \"address\": \"Main Street 123\",\n \"description\": \"5 Bedrooms and 3 Bathrooms\",\n \"squaremeters\": \"200\",\n \"property_type\": \"Apartment\",\n \"number_of_bathrooms\": 3,\n \"number_of_bedrooms\": 5,\n \"installment_duration\": \"8\",\n \"payment_frequency\": \"4\",\n \"down_payment\": \"200000\",\n \"installment_payment_price\": 1000,\n \"keywords\": [\n \"Apartment\",\n \"Lagos\"\n ],\n \"price\": 5000000,\n \"is_sold\": false,\n \"date_sold\": null,\n \"created_at\": \"2024-10-01T11:57:49.903Z\",\n \"updated_at\": \"2024-10-01T11:57:49.903Z\",\n \"sellerid_id\": 1,\n \"common_user\": {\n \"id\": 1,\n \"email\": \"test@gmail.com\",\n \"fname\": \"test\",\n \"lname\": \"test\",\n \"business_name\": null\n },\n \"common_propertyimages\": [\n {\n \"id\": 3,\n \"img\": \"http://express-api.propertyhive.com.ng/static/images/1727783869745.png\"\n },\n {\n \"id\": 4,\n \"img\": \"http://express-api.propertyhive.com.ng/static/images/1727783869746.png\"\n }\n ]\n },\n {\n \"id\": 50,\n \"name\": \"Lagos\",\n \"state\": \"Lagos\",\n \"city\": \"Lagos\",\n \"address\": \"Main Street 123\",\n \"description\": \"3 bathrooms and 5 bedrooms\",\n \"squaremeters\": \"200\",\n \"property_type\": \"Apartment\",\n \"number_of_bathrooms\": 3,\n \"number_of_bedrooms\": 5,\n \"installment_duration\": \"7\",\n \"payment_frequency\": \"20000\",\n \"down_payment\": \"1000\",\n \"installment_payment_price\": 1000,\n \"keywords\": [\n \"Apartment\",\n \"Lagos\"\n ],\n \"price\": 20000,\n \"is_sold\": false,\n \"date_sold\": null,\n \"created_at\": \"2024-10-01T11:58:58.682Z\",\n \"updated_at\": \"2024-10-01T11:58:58.682Z\",\n \"sellerid_id\": 1,\n \"common_user\": {\n \"id\": 1,\n \"email\": \"test@gmail.com\",\n \"fname\": \"test\",\n \"lname\": \"test\",\n \"business_name\": null\n },\n \"common_propertyimages\": []\n }\n ]\n}"}],"_postman_id":"1ecb5840-6c00-422e-8d7c-95dff28f2b13"},{"name":"Search Properties","id":"8995cc91-886e-4edc-8f1f-91a031900072","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://express-api.propertyhive.com.ng/api/v1/properties/search/?query=\"\"","description":"Search Properties: Searches properties based on specified criteria.