Getting Started Edit
Welcome to sprove! Here you’ll find comprehensive information for integrating with our straightforward API. We’ve tried to make this documentation user-friendly and example-filled, but if you have any questions, please don’t hesitate to drop us a line.
Our API is in beta now and available in sandbox mode, so you need to contact us to get your API credentials. We’re working hard on making Quick start guide, which walks through your entire sprove integration step-by-step. It’ll help if you drop us a line with your favorite framework.
This is what you’ll get if everything went great.
Here’s some useful information.
Something may not happen if you try and do this.
Something bad will happen if you do this.
API keys and access Edit
To gain access to the sprove API, please reach out to us directly. Once you’ve completed the sign up process with us and acknowledged our terms, we’ll provide you client_id and secret_key to start using the APIs.
We’d love to have a kick-off call before the Production launch.
API hosts Edit
We have a Sandbox environment for you to play with and setup integration with your service. When you’re ready, just change the endpoint to the Production.
Current version: 1.0
Name | Endpoint |
---|---|
Sandbox | https://demo.sprove.me/api/[version] |
Production | https://app.sprove.me/api/[version] |
Don’t forget to reach out to us to get your Production credentials
Authentication Edit
/auth
Headers
- Client-ID
- client_id you've got from us
- Secret-Key
- secret_key you've got from us
You need to be authenticated to make API calls. Please, reach out to us to get credentials to try APIs.
You can generate a token using this request.
Please, keep in mind that token is valid for a limited time
Nothing will work unless you generate an API token
$.ajax({
url: 'https://demo.sprove.me/api/1.0/auth',
headers: {
'Client-ID': '<client_id>',
'Secret-Key': '<secret_key>',
'Content-Type': 'application/json'
},
method: 'POST',
dataType: 'json',
success: function(data){
console.log('succes: ' + data);
}
});
curl -X POST -i -H "Content-Type: application/json" -H "Client-ID: <client_id>" -H "Secret-Key: <secret_key>" https://demo.sprove.me/api/1.0/auth
Errors Edit
Code | Name | Description |
---|---|---|
200 | OK | Success |
201 | Created | Creation Successful |
400 | Bad Request | We could not process that action |
401 | Unauthorized | Something wrong with the credentials |
403 | Forbidden | We couldn’t authenticate you |
404 | Not Found | This path is not available or requested data not found |
All errors will return JSON in the following format:
{
"error": "error message here"
}
/properties Edit
List all properties
Parameter
- page
- (number) Page number. If not specified, first page is displayed.
- per_page
- (number) Page limit. Define how many items to display.
- active
- (boolean, string) Show only active properties
This call will return a maximum of 100 properties
Lists all the properties you have access to. You can paginate by using the parameters listed above.
$.ajax({
url: 'https://demo.sprove.me/api/1.0/properties',
data: {
page: 2,
per_page: 50
}
headers: {
'Authorization': 'Bearer <token>',
'Content-Type': 'application/json'
},
method: 'GET',
dataType: 'json',
success: function(data){
console.log('succes: ' + data);
}
});
r = requests.get("https://demo.sprove.me/api/1.0/properties", headers={ "Authorization": "Bearer <token>", "Content-Type": "application/json" })
print r.text
var request = require("request");
function callback (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body);
}
}
request({ url: "https://demo.sprove.me/api/1.0/properties", qs: { page: 2, per_page: 50 }, headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" }}, callback)
curl -i -H "Content-Type: application/json" -H "Authorization: Bearer <token>" https://demo.sprove.me/api/1.0/properties?page=2&per_page=50&active=true
{
"properties": [
{
"id": "b685e471-b546-49a7-9fbc-30e3303c46b6",
"name": "Olav kyres gate 1",
"active": true,
"rent_cents": 750000,
"rent_currency": "NOK",
"deposit_cents": 1500000,
"deposit_currency": "NOK",
"verification_url": "https://demo.sprove.me/properties/b685e471-b546-49a7-9fbc-30e3303c46b6"
}
],
"page": 1,
"per_page": 10
}
/properties Edit
Create a new property
Parameter
- name
- (string) Give property a name.
- address
- (string) Full or part of the property address. Please, make it easy to tenant to see what property they apply to.
- rent
- (number) Rental monthly payment.
- rent_currency
- (string) Currency code: 3-letter following ISO-4217
- deposit
- (number) Deposit amount in currency (optional)
- deposit_currency
- (string) Currency code: 3-letter following ISO-4217 (optional)
Please, note that all fields should be put under the ‘property’ key
Add a new property to the account
Note that name and address will be visible to a potential tenant.
$.ajax({
url: 'https://demo.sprove.me/api/1.0/properties',
data: {
property: {
name: "1-bedroom apartment",
address: "Lars Hilles gate 30, 5008 Bergen",
rent: 7500,
rent_currency: "NOK",
}
}
headers: {
'Authorization': 'Bearer <token>',
'Content-Type': 'application/json'
},
method: 'POST',
dataType: 'json',
success: function(data){
console.log('succes: ' + data);
}
});
data = {
'property': {
'name': "1-bedroom apartment",
'address': "Lars Hilles gate 30, 5008 Bergen",
'rent': 7500,
'rent_currency': "NOK",
}
}
r = requests.post(url="https://demo.sprove.me/api/1.0/properties", data=data, headers={ "Authorization": "Bearer <token>", "Content-Type": "application/json" })
print r.text
var request = require("request");
function callback (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body);
}
}
request.post({ url: "https://demo.sprove.me/api/1.0/properties", json: { property: { name: "1-bedroom apartment", address: "Lars Hilles gate 30, 5008 Bergen", rent: 7500, rent_currency: "NOK" } }, headers: { "Authorization": "Bearer <token>" }}, callback)
curl -i -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <token>" https://demo.sprove.me/api/1.0/properties -d '{ "property": { "name": "Blekenberg 20", "address":"Blekenberg 20", "rent": 7500, "rent_currency": "NOK" } }'
{
"property": {
"id": "0183c015-d5da-44fb-8228-db50bc6a8380",
"name": "1-bedroom apartment",
"address": "Lars Hilles gate 30, 5008 Bergen",
"rent": 7500,
"rent_currency": "NOK",
"deposit": 0,
"deposit_currency": "NOK",
"verification_url": "https://demo.sprove.me/properties/0183c015-d5da-44fb-8228-db50bc6a8380"
}
}
/properties/:id Edit
Get property information
Parameter
- id
- (string) Property ID to retrieve.
Return property information by ID
var settings = {
"url": "https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8",
"method": "GET",
"timeout": 0,
"headers": {
"Content-Type": "application/json"
},
};
$.ajax(settings).done(function (response) {
console.log(response);
});
import requests
url = "https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8"
payload = {}
headers = {
'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers, data = payload)
print(response.text.encode('utf8'))
var request = require('request');
var options = {
'method': 'GET',
'url': 'https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8',
'headers': {
'Content-Type': 'application/json'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
curl --location --request GET 'https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8' \
--header 'Content-Type: application/json'
{
"property": {
"id": "0183c015-d5da-44fb-8228-db50bc6a8380",
"name": "1-bedroom apartment",
"address": "Lars Hilles gate 30, 5008 Bergen",
"rent": 7500,
"rent_currency": "NOK",
"deposit": 0,
"deposit_currency": "NOK",
"verification_url": "https://demo.sprove.me/properties/0183c015-d5da-44fb-8228-db50bc6a8380"
}
}
/properties/:id Edit
Update a property with defined ID
Parameter
- name
- (string) Update a name.
- address
- (string) Full or part of the property address. Please, make it easy to tenant to see what property they apply to.
- rent
- (number) Rental monthly payment.
- rent_currency
- (string) Currency code: 3-letter following ISO-4217.
- deposit
- (number) Deposit amount in currency/
- deposit_currency
- (string) Currency code: 3-letter following ISO-4217.
Please, note that at least one field should be set under the ‘property’ key
Update the property by the ID.
You can also use PATCH request type for this request
Note that name and address will be visible to a potential tenant.
var settings = {
"url": "https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8",
"method": "PUT",
"timeout": 0,
"headers": {
"Content-Type": "application/json"
},
"data": JSON.stringify({"property":{"name":"My secret spot","address":"Norway","rent":100000,"rent_currency":"NOK"}}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
import requests
url = "https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8"
payload = {
"property": {
"name": "2-bedroom apartment",
"address": "Daniel Hilsens gate 20, 5008 Bergen",
"rent": 12000,
"rent_currency": "NOK"
}
}
headers = {
'Content-Type': 'application/json'
}
response = requests.request("PUT", url, headers=headers, data = payload)
print(response.text.encode('utf8'))
var request = require('request');
var options = {
'method': 'PUT',
'url': 'https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8',
'headers': {
'Content-Type': 'application/json'
},
body: JSON.stringify({"property":{"name":"2-bedroom apartment","address":"Daniel Hilsens gate 20, 5008 Bergen","rent":12000,"rent_currency":"NOK"}})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
curl --location --request PUT 'https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8' \
--header 'Content-Type: application/json' \
--data-raw '{
"property": {
"name": "2-bedroom apartment",
"address":"Daniel Hilsens gate 20, 5008 Bergen",
"rent": 12000,
"rent_currency": "NOK"
}
}'
No content
/properties/:id Edit
Remove a property with defined ID
Remove the property by the ID.
Note that there is still possible to get usage statistics after property has been deleted.
var settings = {
"url": "https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8",
"method": "DELETE",
"headers": {
"Content-Type": "application/json"
},
};
$.ajax(settings).done(function (response) {
console.log(response);
});
import requests
url = "https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8"
payload = {}
headers = {
'Content-Type': 'application/json'
}
response = requests.request("DELETE", url, headers=headers, data = payload)
print(response.text.encode('utf8'))
var request = require('request');
var options = {
'method': 'DELETE',
'url': 'https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8',
'headers': {
'Content-Type': 'application/json'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
curl --location --request DELETE 'https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8' \
--header 'Content-Type: application/json'
No content
/properties/:property_id/checks Edit
List all verifications completed for the property
Response data
- tenant_name
- (string) Tenant name collected during the verification process.
- approved
- (boolean) Verification result.
- valid_until
- (number) Timetamp while the verification result is valid (in seconds).
No limit on number of the values returned
List all verifications completed for the selected property
var settings = {
"url": "https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8/checks",
"method": "GET",
"headers": {
"Content-Type": "application/json"
},
};
$.ajax(settings).done(function (response) {
console.log(response);
});
import requests
url = "https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8/checks"
payload = {}
headers = {
'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers, data = payload)
print(response.text.encode('utf8'))
var request = require('request');
var options = {
'method': 'GET',
'url': 'https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8/checks',
'headers': {
'Content-Type': 'application/json'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
curl --location --request GET 'https://demo.sprove.me/api/1.0//properties/c639a690-5650-4a0b-a91c-cb60d6eca1a8/checks' \
--header 'Content-Type: application/json'
{
"checks": [
{
"tenant_name": "John Doe",
"approved": true,
"valid_until": 1579357302,
"max_rent": 10000,
"avg_wage": 25000,
"current_rent": 8000
},
{
"tenant_name": "Jane Doe",
"approved": false,
"valid_until": null,
"max_rent": 5000,
"avg_wage": 15000,
"current_rent": 3500
},
{
"tenant_name": "Olav Nordmann",
"approved": true,
"valid_until": 1599357302,
"max_rent": 18000,
"avg_wage": 35000,
"current_rent": 12000
}
],
"property_id": "c639a690-5650-4a0b-a91c-cb60d6eca1a8"
}