sprove for developers logo

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"
}