Introduction
Welcome to the Land registry API! Xinfin provides a simple and powerful REST API's for Land Registry use case. You can use our API to access Land Registry API endpoints and integrate into your application.
This API reference provides information on available endpoints and how to interact with it.
API Interaction
Status Code
200 OK
Successful request400 Bad Request
Validation error401 Unauthorized
Invalid API Key404 Not Found
The specified resource does not exist409 Not Found
Not Found500 Internal Server Error
Something went wrong
Response format
Depending on whether the request is successful or not the response format will change. The response object is encapsulated in high level keys and underline data is different based on request.
A typical response on successful request :
{
status : true,
data : {
key_n : value_n
.
key_n : value_n
}
}
A typical response on failed request :
{
status : false
statusCode : 409,
appErrorCode : 1008,
errMessage : "message"
}
Errors
Errors are defined by error codes and error messages. On failed request status is set to false and http status code is set to error code. For detailed error codes, see error section.
Users
This section includes apis related to user management. There exist 4 type of users,
- Individual : Can sell or buy a property
- Financer : Provide finance to individual buying a property
- Corporation : Verifies property
- IGR : Admin, collects stamp duty
Signup
This endpoint onboards an user to the platform. /signup
adds user to the system, At the same time it automatically creates a Wallet account for the user by assigning the unique wallet address.
Based on user role, request details vary. On successful request, a system responds with success status.
Role argument decides the user role. The following roles are defined :
Role | Value |
---|---|
Individual | individual |
Financer | bank |
Corporation | corporation |
IGR | igr |
HTTP Request
POST http://example.com/signup
Individual Signup
Onboards individual to the platform.
A typical JSON structured individual signup request looks like this:
curl -X POST \
http://api.xinfin.org/api/v1/contact \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
"userDetails" : {
"email" : "[email protected]",
"password" : "123",
"role" : "individual",
"salutation" : "Mr",
"firstName" : "Viral",
"middleName" : "Mahendra",
"lastName" : "Pasad",
"aliasName" : "viral",
"identityMark1" : "Mole on Left Hand",
"identityMark2" : "Mark above left eye",
"dob" : "07/12/1995",
"age" : 28,
"uid" : "123456789923",
"identityTypeID" : "Aadhar",
"identityDesc" : "Aadhar card",
"pan" : "BCPPT9089H",
"occupation" : "Salaried Employee",
"gender" : "Male",
"mobileNo" : "9664818286",
"permAddress" : "Pali Hill, Bandra",
"tempAddress" : "Pali Hill, Bandra",
"district" : "Mumbai",
"taluka" : "Mumbai",
"village" : "Mumbai"
}
}'
Financer Signup
Onboards Financer to the platform.
A typical JSON structured financer signup requst looks like this:
curl -X POST \
http://api.xinfin.org/api/v1/contact \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
"userDetails" : {
"email" : "[email protected]",
"password" : "123",
"role" : "bank",
"name" : "State Bank Of India",
"city" : "Mumbai",
"branch" : "Pali Hill"
}
}'
IGR/Corporation Signup
Onboards IGR or Corporation to the platform.
To onboard IGR, argument role is set to a value "igr".
To onboard Corporation, argument role is set to a value "corporation"
A typical JSON structured corporation signup request looks like this:
curl -X POST \
http://api.xinfin.org/api/v1/contact \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
"userDetails" : {
"email" : "[email protected]",
"password" : "123",
"role" : "corporation"
"name" : "BMC",
"state" : "Maharashtra",
"dept" : "Housing and Urban Development"
}
}'
The above command returns JSON structured like this:
{
"status" : true,
"message": "User added successfully."
}
Login
Logs in user to the platform. Returns role specific user details.
HTTP Request
POST http://example.com/login
A typical JSON structured requst looks like this:11
curl -X POST \
http://api.xinfin.org/api/v1/contact \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
"email" : "[email protected]",
"password" : "123"
}'
The above command returns JSON structured like this. data object contains user details:
{
"status" : true,
"data" : {}
}
Get User Details
Get complete user details.
HTTP Request
POST http://example.com/getUserDetails
A typical JSON structured requst looks like this:
curl -X GET -i 'http://localhost:8001/[email protected]'
The above command returns JSON structured like this. data object contains user details :
{
"status" : true,
"data" : {}
}
Wallet
Land Registry has pre-integrated wallet with ERC-20 token standard. When user signs up for the platform, a wallet address is created for the user.
Get Balance
Returns a token balance for specified address.
HTTP Request
POST http://example.com/getBalance
A typical JSON structured requst looks like this:
curl -X POST \
http://localhost:8001/getBalance \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
"address" : "0x0640523060f197f8f57a56c74f78f4fab8378c5e"
}'
The above command returns JSON structured like this:
{
"balance" : 10000
}
Buy Tokens
Transfer tokens to a specified address from coinbase account(token pool).
HTTP Request
POST http://example.com/buyTokens
A typical JSON structured requst looks like this:
curl -X POST \
http://localhost:8001/buyTokens \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
"address" : "0x0640523060f197f8f57a56c74f78f4fab8378c5e",
"amount" : 500
}'
The above command returns JSON structured like this:
{
"status" : true
}
Property
Land registry stores and manages land records(properties) data. A individual user(owner) can add property to blockchain which is then verified by corporation. A property is invalid if rejected by corporation.
Add Poperty
This api endpoint enables property owner(individual) to add property to land records data on blockchain.
HTTP Request
POST http://localhost:8001/addPoperty
A typical JSON structured request looks like this:
curl -X POST
http://localhost:8001/addPoperty
-H 'cache-control: no-cache'
-H 'content-type: application/json'
-d '{
"propertyDetails" : {
"district" : "sangli",
"landType" : "Shop",
"taluka" : "Maval",
"localGovNo" : "MV123",
"city" : "Pune",
"location" : "Pune",
"surveyNo" : "S12345",
"usage" : "Shop",
"usageCategory" : "Non-Agriculture",
"constructedArea" : 1000,
"openParking" : 100,
"coveredParking" : 100,
"shopFloor" : 1,
"address" : "Maval, Pune",
"description" : "Shop",
"owner" : "[email protected]"
}
}'
The above command returns JSON structured like this. propertyDetails object contains property details submitted by user along with system generated propertyId :
{
"status" : true,
"propertyDetails" : {}
}
Verify Property
This endpoint enables user(corporation) to verify the property. The status
parameter sets property status. The following status are defined to verify property.
Status | Description |
---|---|
property_verified |
Property details are correct and verified |
property_rejected |
Property details are incorrect and property is rejected |
HTTP Request
POST http://localhost:8001/confirmProperty
A typical confirm property JSON structured request looks like this:
curl -X POST
http://localhost:8001/confirmProperty
-H 'cache-control: no-cache'
-H 'content-type: application/json'
-d '{
"propertyId" : "5447763e-3a97-48c5-a114-8d33069737a3",
"status" : "property_verified",
}'
The above command returns JSON structured like this:
{
"status" : true
}
List Property For Sell
This enpoint allows property owner to list a property for sell. By listing property, a new registry record is created, Where owner can add sell price, token amount, financer, buyer and other information of the porperty for sell.
Returns a regisryId of newly created registry record. registryId
is used for all registry related operations.
HTTP Request
POST http://localhost:8001/sellProperty
A typical sell property JSON structured request looks like this:
curl -X POST
http://localhost:8001/sellProperty
-H 'cache-control: no-cache'
-H 'content-type: application/json'
-d '{
"propertyId" : "5447763e-3a97-48c5-a114-8d33069737a3",
"owner" : "[email protected]",
"sellPrice" : 10000000,
"tokenAmt" : 50000
}'
The above command returns JSON structured like this:
{
"status" : true,
"data" : {
"propertyId" : "ygfgteru",
"registryId" : "fdtheryf"
}
}
Get Property Details
Returns Property Details from Land Records.
HTTP Request
GET http://localhost:8001/getPropertyDetails
A typical request looks like this:
curl -X GET -i http://localhost:8001/getPropertyDetails?propertyId=5447763e-3a97-48c5-a114-8d33069737a3'
The above command returns JSON structured like this. data object contains property detailes submitted by owner while adding property to land records:
{
"status" : true,
"data" : {}
}
Registry
Registry maintains registry records. A property can have multiple registry records. The complete buy/sell process is recorded in registry record. When buy/sell process is completed a new owner is added to the land record(property).
Add Owner
adds extra information about the property owner.
HTTP Request
POST http://localhost:8001/addOwner
A typical JSON structured request looks like this:
curl -X POST
http://localhost:8001/addOwner
-H 'cache-control: no-cache'
-H 'content-type: application/json'
-d '{
"registryId" : "3d69be4d-6976-47ac-9206-cd7de90f04a1",
"owner" : {
"email" : "[email protected]",
"address" : "0x40aece087558d1585e1c4e92e68f20e88562345f",
"partyType" : "Executor",
"partyCategory" : "Vendor",
"isExecuter" : true
}
}'
The above command returns JSON structured like this:
{
"status" : true
}
Add Owner Financer
This endpoint enables owner to add owner financer to the registry record. If there is no financer involved or owner can skip adding financer using the same api endpoint.
HTTP Request
POST http://localhost:8001/addOwnerFinancer
A typical add owener financer JSON structured request looks like this:
curl -X POST
http://localhost:8001/addOwnerFinancer
-H 'cache-control: no-cache'
-H 'content-type: application/json'
-d '{
"registryId" : "3d69be4d-6976-47ac-9206-cd7de90f04a1"
"ownerFinancer" : {
"email" : "[email protected]",
"address" : "0x40aece087558d1585e1c4e92e68f20e88562345f",
"loanAmount;" : 700000,
"outstandingLoan" : 200000
}
}'
The above command returns JSON structured like this:
{
"status" : true
}
Confirm Financer
This api enpoint enables financer to approve or reject finance details in registry records.
Both owner and buyer can add fiancer to registry record. Financer can approve or reject finance details added by owner or buyer. The approved
flag in request object confirms fianancer.
Approved Flag | Description |
---|---|
true |
Finance details are correct and approved |
false |
Finance details are incorrect and rejected |
HTTP Request
POST http://localhost:8001/confirmFinancer
A typical verify financer JSON structured request looks like this:
curl -X POST
http://localhost:8001/confirmFinancer
-H 'cache-control: no-cache'
-H 'content-type: application/json'
-d '{
"registryId" : "3d69be4d-6976-47ac-9206-cd7de90f04a1",
"currentStatus" : "currentStatus",
"approved" : true
}'
The above command returns JSON structured like this:
{
"status" : true
}
Add Buyer
This endpoint enables property owner to add buyer to registry record.
HTTP Request
POST http://localhost:8001/addBuyer
A typical JSON structured request looks like this:
curl -X POST
http://localhost:8001/addBuyer
-H 'cache-control: no-cache'
-H 'content-type: application/json'
-d '{
"registryId" : "3d69be4d-6976-47ac-9206-cd7de90f04a1",
"buyer" : {
"email" : "[email protected]",
"partyType" : "Executer",
"partyCategory" : "Vendor",
"isExecuter" : true|false
}
}'
The above command returns JSON structured like this:
{
"status" : true
}
Confirm Buyer
This endpoints enables buyer to confirm registry buyer details added by owner.
The status
flag is used to set the confirmation of buyer.
Status | Description |
---|---|
registry_buyer_confirmed |
Buyer details are correct and approved |
registry_buyer_confirmed |
Buyer details are incorrect and rejected |
HTTP Request
POST http://localhost:8001/confirmBuyer
A typical confirm buyer JSON structured request looks like this:
curl -X POST
http://localhost:8001/confirmBuyer
-H 'cache-control: no-cache'
-H 'content-type: application/json'
-d '{
"registryId" : "3d69be4d-6976-47ac-9206-cd7de90f04a1",
"status" : "registry_buyer_confirmed"
}'
The above command returns JSON structured like this:
{
"status" : true
}
Add Buyer Financer
This endpoint enables buyer to add owner financer to the registry record. If there is no financer involved or owner can skip adding financer using the same api endpoint.
HTTP Request
POST http://localhost:8001/addBuyerFinancer
A typical JSON structured request looks like this:
curl -X POST
http://localhost:8001/addBuyerFinancer
-H 'cache-control: no-cache'
-H 'content-type: application/json'
-d '{
"registryId" : "3d69be4d-6976-47ac-9206-cd7de90f04a1",
"buyerFinancer" : {
"email" : "[email protected]",
"financeAmount" : 500000
}
}'
The above command returns JSON structured like this:
{
"status" : true
}
Pay Token Amount
This enpoint transfers token amount from buyers wallet to Owners wallet. Returns error if there is no enough balance in buyers account.
HTTP Request
POST http://localhost:8001/payTokenAmount
A typical JSON structured request looks like this:
curl -X POST
http://localhost:8001/payTokenAmount
-H 'cache-control: no-cache'
-H 'content-type: application/json'
-d '{
"registryId" : "3d69be4d-6976-47ac-9206-cd7de90f04a1"
}'
The above command returns JSON structured like this:
{
"status" : true
}
Financer Payment
This enpoint transfers Finance amount from Financers wallet to Owner and/or Ownerfinancer's wallet. Returns error if there is no enough balance in financers account.
HTTP Request
POST http://localhost:8001/financerPayment
A typical JSON structured request looks like this:
curl -X POST
http://localhost:8001/financerPayment
-H 'cache-control: no-cache'
-H 'content-type: application/json'
-d '{
registryId : "3d69be4d-6976-47ac-9206-cd7de90f04a1",
}'
The above command returns JSON structured like this:
{
"status" : true
}
Buyer Payment
This enpoint transfers Remaining amount from Buyers wallet to Owner and/or Ownerfinancer's wallet. Returns error if there is no enough balance in buyers account.
HTTP Request
POST http://localhost:8001/buyerPayment
A typical JSON structured request looks like this:
curl -X POST
http://localhost:8001/buyerPayment
-H 'cache-control: no-cache'
-H 'content-type: application/json'
-d '{
registryId : "3d69be4d-6976-47ac-9206-cd7de90f04a1"
}'
The above command returns JSON structured like this:
{
"status" : true
}
Pay Stamp Duty
This enpoint transfers Stamp duty amount from Owners wallet to IGR(admin). Returns error if there is no enough balance in owners account.
HTTP Request
POST http://localhost:8001/payStampDuty
A typical JSON structured request looks like this:
curl -X POST
http://localhost:8001/payStampDuty
-H 'cache-control: no-cache'
-H 'content-type: application/json'
-d '{
registryId : "3d69be4d-6976-47ac-9206-cd7de90f04a1"
}'
The above command returns JSON structured like this:
{
"status" : true
}
Get Property Data
Returns complete registry/property Data.
A typical completed registry record containes following key objects.
key | Description |
---|---|
propertyId |
Property ID |
registryId |
Registry ID |
status |
Registry Status |
propertyDetails |
Property Details |
owner |
Owner Details |
ownerFinancer |
Owner Financers Details |
buyer |
Buyer Details |
buyerFinancer |
Buyer FInancers Details |
sellPrice |
Sell Price |
tokenAmount |
Token Amount |
stampDuty |
Stamp Duty Amount |
HTTP Request
GET http://localhost:8001/getPropertyData
A typical JSON structured request looks like this:
curl -X GET -i http://localhost:8001/getPropertyData?registryId=5447763e-3a97-48c5-a114-8d33069737a3'
The above command returns JSON structured like this:
{
"status" : true,
"data" : {
"propertyId" : "5447763e-3a97-48c5-a114-8d33069737a3",
"registryId" : "3d69be4d-6976-47ac-9206-cd7de90f04a1",
"status" : "registry_owner_financer",
"propertyDetails" : {},
"owner" : {},
"ownerFinancer" : {},
"buyer" : {},
"buyerFinancer" : {},
"sellPrice" : 1000000,
"tokenAmount" : 50000,
"stampDuty" : 35000,
"created" : 1545120324,
"modified" : 1545120324
}
}
Dashboard
Returns user specific property/registry records.
Depends on user role, different records will be fetched.
Role | Record restrictions |
---|---|
Individual | Owner or Buyer of property/registry record |
Corporation | All property records |
Financer | Owner Financer or Buyer Financer of property/registry record |
IGR | All property and registry records |
HTTP Request
POST http://localhost:8001/getDashboard
A typical JSON structured request looks like this:
curl -X POST
http://localhost:8001/getDashboard
-H 'cache-control: no-cache'
-H 'content-type: application/json'
-d '{
"email" : "[email protected]",
"role" : "individual"
}'
The above command returns JSON structured like this:
{
"status" : true,
"data" : {}
}
Events
Returns property/registry specific blockchain events.
The following events are defined on property/registry records which are emitetd at different api endpoints.
Event | Description |
---|---|
AddProperty |
Add new Property Record |
SetStatus |
Set Property/Registry Status |
AddOwner |
Ownership Transfer |
AddRegistryRecord |
Add new Registry Record |
AddBuyer |
Add Buyer Information to Registry Record |
AddOwnerFinancer |
Add Owner Financer Information to Registry Record |
AddBuyerFinancer |
Add Buyer Financer Information to Registry Record |
TransferTokens |
Transfer Tokens |
HTTP Request
POST http://localhost:8001/getExplorer
A typical JSON structured request looks like this:
curl -X POST
http://localhost:8001/getExplorer
-H 'cache-control: no-cache'
-H 'content-type: application/json'
-d '{
"registryId" : "jhgygu657",
"propertyId" : "htyytyt6123"
}'
The above command returns JSON structured like this:
{
"status" : true,
"data" : {}
}
Errors
The Land Registry API uses the following error codes:
Error Code | Status Code | Error Message |
---|---|---|
400 | 1001 | The request was unacceptable, often due to missing a required parameter |
400 | 1002 | No value provided for mandatory resource |
400 | 1003 | The specified resource type does not match the required type |
404 | 1004 | The specified resource does not exist |
400 | 1005 | The resource exceeds the maximum allowed value of {{MAX}} |
400 | 1006 | The resource does not meet minimum required value of {{MIN}} |
400 | 1007 | The resource does not match required size of {{SIZE}} |
409 | 1008 | Invalid email |
409 | 1008 | Buyer can not be same as owner |
409 | 1008 | Token amount can not be greater than Sell Price |
409 | 1008 | Loan amount can not be greater than sell price |
409 | 1008 | Outstanding loan can not be greater than loan amount |
409 | 1008 | Finance amount can not be greater than Sell Price |
400 | 1009 | Invalid date format |
400 | 1010 | Invalid XDC address |
400 | 1011 | The specified resource is out of range |
409 | 1012 | Invalid value |
401 | 1101 | No valid API key provided |
429 | 1102 | Rate limit exceeded |
409 | 1103 | User already exists |
403 | 1104 | Server failed to authenticate the request |
500 | 1105 | Internal Error |
500 | 1106 | DB Error |
500 | 1107 | Cannot send activation email to the user |
500 | 1108 | Cannot unlock account. |
500 | 1109 | Cannot create new account. |
500 | 1110 | Cannot send forgot password/reset email to the user |
404 | 1111 | Given email id does not exist |
404 | 1112 | Reset Link Expired |
400 | 1113 | Cannot change password. Enter correct details |
500 | 1115 | Something went wrong. Cannot process the request |
400 | 1117 | Account is invalid |
400 | 1118 | Incorrect Password |
400 | 1120 | Cannot setup new account |
404 | 1121 | Account does not exists |
400 | 1123 | API Key is invalid |
400 | 1126 | Not accessible |
409 | 1008 | Invalid Phone Number |
409 | 1008 | Invalid value |
409 | 1008 | Resource crossed maximum allowed length |
409 | 1008 | Invalid PAN No |
409 | 1008 | Invalid Pincode |
400 | 1119 | Incorrect Email or Password |