Create a scoring
curl --request POST \
--url https://api.vivara.io/v1/scorings \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"id": "6d1f0c3e-5b8a-4c1e-9f2a-3b7e8d4a1c90",
"postalCode": "08001",
"monthlyPaymentAmountInEuros": 1200,
"candidatures": [
{
"externalReference": "cand-001",
"members": [
{
"personalId": "12345678Z",
"workingStatus": "employed",
"netAnnualIncomeAmountInEuros": 25200
},
{
"personalId": "X1234567L",
"workingStatus": "retired",
"netAnnualIncomeAmountInEuros": 21000
}
]
},
{
"externalReference": "cand-002",
"members": [
{
"netAnnualIncomeAmountInEuros": 30000
}
]
},
{
"externalReference": "cand-003",
"members": [
{
"personalId": "87654321X",
"workingStatus": "self-employed",
"form100": {
"netIncomeAmountInEuros": 44000
},
"form130": {
"netIncomeAmountInEuros": 28800
}
}
]
}
]
}
'import requests
url = "https://api.vivara.io/v1/scorings"
payload = {
"id": "6d1f0c3e-5b8a-4c1e-9f2a-3b7e8d4a1c90",
"postalCode": "08001",
"monthlyPaymentAmountInEuros": 1200,
"candidatures": [
{
"externalReference": "cand-001",
"members": [
{
"personalId": "12345678Z",
"workingStatus": "employed",
"netAnnualIncomeAmountInEuros": 25200
},
{
"personalId": "X1234567L",
"workingStatus": "retired",
"netAnnualIncomeAmountInEuros": 21000
}
]
},
{
"externalReference": "cand-002",
"members": [{ "netAnnualIncomeAmountInEuros": 30000 }]
},
{
"externalReference": "cand-003",
"members": [
{
"personalId": "87654321X",
"workingStatus": "self-employed",
"form100": { "netIncomeAmountInEuros": 44000 },
"form130": { "netIncomeAmountInEuros": 28800 }
}
]
}
]
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
id: '6d1f0c3e-5b8a-4c1e-9f2a-3b7e8d4a1c90',
postalCode: '08001',
monthlyPaymentAmountInEuros: 1200,
candidatures: [
{
externalReference: 'cand-001',
members: [
{
personalId: '12345678Z',
workingStatus: 'employed',
netAnnualIncomeAmountInEuros: 25200
},
{
personalId: 'X1234567L',
workingStatus: 'retired',
netAnnualIncomeAmountInEuros: 21000
}
]
},
{
externalReference: 'cand-002',
members: [{netAnnualIncomeAmountInEuros: 30000}]
},
{
externalReference: 'cand-003',
members: [
{
personalId: '87654321X',
workingStatus: 'self-employed',
form100: {netIncomeAmountInEuros: 44000},
form130: {netIncomeAmountInEuros: 28800}
}
]
}
]
})
};
fetch('https://api.vivara.io/v1/scorings', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vivara.io/v1/scorings",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'id' => '6d1f0c3e-5b8a-4c1e-9f2a-3b7e8d4a1c90',
'postalCode' => '08001',
'monthlyPaymentAmountInEuros' => 1200,
'candidatures' => [
[
'externalReference' => 'cand-001',
'members' => [
[
'personalId' => '12345678Z',
'workingStatus' => 'employed',
'netAnnualIncomeAmountInEuros' => 25200
],
[
'personalId' => 'X1234567L',
'workingStatus' => 'retired',
'netAnnualIncomeAmountInEuros' => 21000
]
]
],
[
'externalReference' => 'cand-002',
'members' => [
[
'netAnnualIncomeAmountInEuros' => 30000
]
]
],
[
'externalReference' => 'cand-003',
'members' => [
[
'personalId' => '87654321X',
'workingStatus' => 'self-employed',
'form100' => [
'netIncomeAmountInEuros' => 44000
],
'form130' => [
'netIncomeAmountInEuros' => 28800
]
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vivara.io/v1/scorings"
payload := strings.NewReader("{\n \"id\": \"6d1f0c3e-5b8a-4c1e-9f2a-3b7e8d4a1c90\",\n \"postalCode\": \"08001\",\n \"monthlyPaymentAmountInEuros\": 1200,\n \"candidatures\": [\n {\n \"externalReference\": \"cand-001\",\n \"members\": [\n {\n \"personalId\": \"12345678Z\",\n \"workingStatus\": \"employed\",\n \"netAnnualIncomeAmountInEuros\": 25200\n },\n {\n \"personalId\": \"X1234567L\",\n \"workingStatus\": \"retired\",\n \"netAnnualIncomeAmountInEuros\": 21000\n }\n ]\n },\n {\n \"externalReference\": \"cand-002\",\n \"members\": [\n {\n \"netAnnualIncomeAmountInEuros\": 30000\n }\n ]\n },\n {\n \"externalReference\": \"cand-003\",\n \"members\": [\n {\n \"personalId\": \"87654321X\",\n \"workingStatus\": \"self-employed\",\n \"form100\": {\n \"netIncomeAmountInEuros\": 44000\n },\n \"form130\": {\n \"netIncomeAmountInEuros\": 28800\n }\n }\n ]\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.vivara.io/v1/scorings")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"id\": \"6d1f0c3e-5b8a-4c1e-9f2a-3b7e8d4a1c90\",\n \"postalCode\": \"08001\",\n \"monthlyPaymentAmountInEuros\": 1200,\n \"candidatures\": [\n {\n \"externalReference\": \"cand-001\",\n \"members\": [\n {\n \"personalId\": \"12345678Z\",\n \"workingStatus\": \"employed\",\n \"netAnnualIncomeAmountInEuros\": 25200\n },\n {\n \"personalId\": \"X1234567L\",\n \"workingStatus\": \"retired\",\n \"netAnnualIncomeAmountInEuros\": 21000\n }\n ]\n },\n {\n \"externalReference\": \"cand-002\",\n \"members\": [\n {\n \"netAnnualIncomeAmountInEuros\": 30000\n }\n ]\n },\n {\n \"externalReference\": \"cand-003\",\n \"members\": [\n {\n \"personalId\": \"87654321X\",\n \"workingStatus\": \"self-employed\",\n \"form100\": {\n \"netIncomeAmountInEuros\": 44000\n },\n \"form130\": {\n \"netIncomeAmountInEuros\": 28800\n }\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.vivara.io/v1/scorings")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"id\": \"6d1f0c3e-5b8a-4c1e-9f2a-3b7e8d4a1c90\",\n \"postalCode\": \"08001\",\n \"monthlyPaymentAmountInEuros\": 1200,\n \"candidatures\": [\n {\n \"externalReference\": \"cand-001\",\n \"members\": [\n {\n \"personalId\": \"12345678Z\",\n \"workingStatus\": \"employed\",\n \"netAnnualIncomeAmountInEuros\": 25200\n },\n {\n \"personalId\": \"X1234567L\",\n \"workingStatus\": \"retired\",\n \"netAnnualIncomeAmountInEuros\": 21000\n }\n ]\n },\n {\n \"externalReference\": \"cand-002\",\n \"members\": [\n {\n \"netAnnualIncomeAmountInEuros\": 30000\n }\n ]\n },\n {\n \"externalReference\": \"cand-003\",\n \"members\": [\n {\n \"personalId\": \"87654321X\",\n \"workingStatus\": \"self-employed\",\n \"form100\": {\n \"netIncomeAmountInEuros\": 44000\n },\n \"form130\": {\n \"netIncomeAmountInEuros\": 28800\n }\n }\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_bodyScorings
Create a scoring
Creates a scoring for one property and evaluates every candidature in the request.
For each candidature, Vivara calculates:
- Solvency — whether the group’s income can cover the rent (effort rate).
- Delinquency — whether any member appears in a delinquency register, when every member has an ID number.
- Rank — visit-prioritization order among candidatures in this scoring.
Solvency and delinquency are independent results.
Optional fields. Omit personalId and workingStatus when they are unknown. Explicit null is also accepted and has the same meaning as omission. Both forms are normalized to null. When employment is unknown, send netAnnualIncomeAmountInEuros for solvency. Self-employed members must set workingStatus to self-employed and send form100 and form130.
Confidence tier. basic when any member omits personalId or workingStatus; declared when every member provides both.
Response. 201 with no body and a Location header. Call GET on that URL to read the results.
Partial failures. If a delinquency check cannot be completed, the candidature is failed with reason service-unavailable. The scoring is still created.
Errors.
400— invalid types, unknown fields, unsupported working statuses, or missing or incompatible income fields.422— invalid domain values, duplicated references or personal ids, or more than 20 candidatures or 6 members per candidature.409— the scoring id was already used by this API client (other clients may reuse the same id).
POST
/
scorings
Create a scoring
curl --request POST \
--url https://api.vivara.io/v1/scorings \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"id": "6d1f0c3e-5b8a-4c1e-9f2a-3b7e8d4a1c90",
"postalCode": "08001",
"monthlyPaymentAmountInEuros": 1200,
"candidatures": [
{
"externalReference": "cand-001",
"members": [
{
"personalId": "12345678Z",
"workingStatus": "employed",
"netAnnualIncomeAmountInEuros": 25200
},
{
"personalId": "X1234567L",
"workingStatus": "retired",
"netAnnualIncomeAmountInEuros": 21000
}
]
},
{
"externalReference": "cand-002",
"members": [
{
"netAnnualIncomeAmountInEuros": 30000
}
]
},
{
"externalReference": "cand-003",
"members": [
{
"personalId": "87654321X",
"workingStatus": "self-employed",
"form100": {
"netIncomeAmountInEuros": 44000
},
"form130": {
"netIncomeAmountInEuros": 28800
}
}
]
}
]
}
'import requests
url = "https://api.vivara.io/v1/scorings"
payload = {
"id": "6d1f0c3e-5b8a-4c1e-9f2a-3b7e8d4a1c90",
"postalCode": "08001",
"monthlyPaymentAmountInEuros": 1200,
"candidatures": [
{
"externalReference": "cand-001",
"members": [
{
"personalId": "12345678Z",
"workingStatus": "employed",
"netAnnualIncomeAmountInEuros": 25200
},
{
"personalId": "X1234567L",
"workingStatus": "retired",
"netAnnualIncomeAmountInEuros": 21000
}
]
},
{
"externalReference": "cand-002",
"members": [{ "netAnnualIncomeAmountInEuros": 30000 }]
},
{
"externalReference": "cand-003",
"members": [
{
"personalId": "87654321X",
"workingStatus": "self-employed",
"form100": { "netIncomeAmountInEuros": 44000 },
"form130": { "netIncomeAmountInEuros": 28800 }
}
]
}
]
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
id: '6d1f0c3e-5b8a-4c1e-9f2a-3b7e8d4a1c90',
postalCode: '08001',
monthlyPaymentAmountInEuros: 1200,
candidatures: [
{
externalReference: 'cand-001',
members: [
{
personalId: '12345678Z',
workingStatus: 'employed',
netAnnualIncomeAmountInEuros: 25200
},
{
personalId: 'X1234567L',
workingStatus: 'retired',
netAnnualIncomeAmountInEuros: 21000
}
]
},
{
externalReference: 'cand-002',
members: [{netAnnualIncomeAmountInEuros: 30000}]
},
{
externalReference: 'cand-003',
members: [
{
personalId: '87654321X',
workingStatus: 'self-employed',
form100: {netIncomeAmountInEuros: 44000},
form130: {netIncomeAmountInEuros: 28800}
}
]
}
]
})
};
fetch('https://api.vivara.io/v1/scorings', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vivara.io/v1/scorings",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'id' => '6d1f0c3e-5b8a-4c1e-9f2a-3b7e8d4a1c90',
'postalCode' => '08001',
'monthlyPaymentAmountInEuros' => 1200,
'candidatures' => [
[
'externalReference' => 'cand-001',
'members' => [
[
'personalId' => '12345678Z',
'workingStatus' => 'employed',
'netAnnualIncomeAmountInEuros' => 25200
],
[
'personalId' => 'X1234567L',
'workingStatus' => 'retired',
'netAnnualIncomeAmountInEuros' => 21000
]
]
],
[
'externalReference' => 'cand-002',
'members' => [
[
'netAnnualIncomeAmountInEuros' => 30000
]
]
],
[
'externalReference' => 'cand-003',
'members' => [
[
'personalId' => '87654321X',
'workingStatus' => 'self-employed',
'form100' => [
'netIncomeAmountInEuros' => 44000
],
'form130' => [
'netIncomeAmountInEuros' => 28800
]
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vivara.io/v1/scorings"
payload := strings.NewReader("{\n \"id\": \"6d1f0c3e-5b8a-4c1e-9f2a-3b7e8d4a1c90\",\n \"postalCode\": \"08001\",\n \"monthlyPaymentAmountInEuros\": 1200,\n \"candidatures\": [\n {\n \"externalReference\": \"cand-001\",\n \"members\": [\n {\n \"personalId\": \"12345678Z\",\n \"workingStatus\": \"employed\",\n \"netAnnualIncomeAmountInEuros\": 25200\n },\n {\n \"personalId\": \"X1234567L\",\n \"workingStatus\": \"retired\",\n \"netAnnualIncomeAmountInEuros\": 21000\n }\n ]\n },\n {\n \"externalReference\": \"cand-002\",\n \"members\": [\n {\n \"netAnnualIncomeAmountInEuros\": 30000\n }\n ]\n },\n {\n \"externalReference\": \"cand-003\",\n \"members\": [\n {\n \"personalId\": \"87654321X\",\n \"workingStatus\": \"self-employed\",\n \"form100\": {\n \"netIncomeAmountInEuros\": 44000\n },\n \"form130\": {\n \"netIncomeAmountInEuros\": 28800\n }\n }\n ]\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.vivara.io/v1/scorings")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"id\": \"6d1f0c3e-5b8a-4c1e-9f2a-3b7e8d4a1c90\",\n \"postalCode\": \"08001\",\n \"monthlyPaymentAmountInEuros\": 1200,\n \"candidatures\": [\n {\n \"externalReference\": \"cand-001\",\n \"members\": [\n {\n \"personalId\": \"12345678Z\",\n \"workingStatus\": \"employed\",\n \"netAnnualIncomeAmountInEuros\": 25200\n },\n {\n \"personalId\": \"X1234567L\",\n \"workingStatus\": \"retired\",\n \"netAnnualIncomeAmountInEuros\": 21000\n }\n ]\n },\n {\n \"externalReference\": \"cand-002\",\n \"members\": [\n {\n \"netAnnualIncomeAmountInEuros\": 30000\n }\n ]\n },\n {\n \"externalReference\": \"cand-003\",\n \"members\": [\n {\n \"personalId\": \"87654321X\",\n \"workingStatus\": \"self-employed\",\n \"form100\": {\n \"netIncomeAmountInEuros\": 44000\n },\n \"form130\": {\n \"netIncomeAmountInEuros\": 28800\n }\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.vivara.io/v1/scorings")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"id\": \"6d1f0c3e-5b8a-4c1e-9f2a-3b7e8d4a1c90\",\n \"postalCode\": \"08001\",\n \"monthlyPaymentAmountInEuros\": 1200,\n \"candidatures\": [\n {\n \"externalReference\": \"cand-001\",\n \"members\": [\n {\n \"personalId\": \"12345678Z\",\n \"workingStatus\": \"employed\",\n \"netAnnualIncomeAmountInEuros\": 25200\n },\n {\n \"personalId\": \"X1234567L\",\n \"workingStatus\": \"retired\",\n \"netAnnualIncomeAmountInEuros\": 21000\n }\n ]\n },\n {\n \"externalReference\": \"cand-002\",\n \"members\": [\n {\n \"netAnnualIncomeAmountInEuros\": 30000\n }\n ]\n },\n {\n \"externalReference\": \"cand-003\",\n \"members\": [\n {\n \"personalId\": \"87654321X\",\n \"workingStatus\": \"self-employed\",\n \"form100\": {\n \"netIncomeAmountInEuros\": 44000\n },\n \"form130\": {\n \"netIncomeAmountInEuros\": 28800\n }\n }\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_bodyBody
application/json
Response
Scoring created and evaluated.