Key concepts

Candidate

A person interested in renting one of your listings. You send Vivara the data you have about each candidate to get their score. When you choose a candidate after the visits, they become the tenant on the insurance request.

Tenant score

The tenant score has two independent results:

Result	What it tells you	What it needs
Solvency	Whether the candidate’s income can cover the rent, based on the effort rate (the share of income that goes to rent)	Monthly income and the listing’s rent
Delinquency	Whether the candidate appears in a delinquency register	ID number (DNI or NIE) and postal code

Each result is reported on its own. Vivara does not combine them into a single verdict, so you decide how to weigh them.

Confidence tiers

Every score comes with a confidence tier. The tier tells you how reliable the data behind the score is, not how good the candidate is.

Tier	ID number	Income	Documents	What is calculated
Basic	Not provided	Declared	None	Solvency only. Delinquency cannot be checked without the ID number
Declared	Declared	Declared	None	Solvency and delinquency
Accredited	Provided	Provided	All required	Solvency and delinquency

A candidate with no income cannot be scored.
Tiers are not steps you must go through in order. You can send documents at any time, and the tier updates when you do.
A score is Accredited only when every value behind it is backed by a document. If any document is missing, the score stays Declared.

Today, a document counts as accrediting its value when it is present. Vivara does not yet check the content of the document against the declared data. See Coming soon.

Case

Everything you do to insure one rental happens on a case. You create it by choosing its id, a UUID v4, when you open it. It is the correlation id from your request to the insurer, and an id that was already used answers 409.

Quote

The price the insurer offers for a non-payment insurance policy, calculated from the tenant, landlord, property and contract data you send. The quote comes back as the case, and includes:

The offer: the annual premium, before and after taxes, and the installments
The reasons, when the offer is conditioned or cannot be contracted, each with a code and a description
The documents the insurer requires

A quote is not a policy. Documents do not change the quote: they are stored and sent to the insurer when you issue the policy.

Policy request

The request you make to the insurer once the case is ready-to-issue. The policy is taken out for the landlord’s property, and the insurer reviews the tenants, the landlord and the property before it issues the policy.

Case statuses

Status	Meaning
`pending-documentation`	The offer is priced. Upload the documents in `documentation.missing`
`ready-to-issue`	Every required document is uploaded. You can issue the policy
`rejected`	The insurer will not cover the contract. This status is final
`policy-requested`	The issuance has been requested and the insurer is finishing it
`policy-issued`	The policy is in force and has a policy number. This status is final
`failed`	Vivara could not complete the last step with the insurer. Vivara is notified and retries

Once the issuance is requested, the case cannot be changed or cancelled: wait for the insurer’s decision. Any change after that point, such as a different tenant or a new rent, needs a new case.

Errors

Every error the API answers has the same body:

{
  "status": "Conflict",
  "statusCode": 409,
  "code": "case-already-exists",
  "message": "Case 3f9c2a7e-58b1-4d0a-9a51-0c6e2f1b7d42 already exists."
}

Use code to decide what to do: it is stable. The message is for people and names the fields or the documents behind the error.

Status	Code	Answered by	When
400	`validation-error`	Shared	The request does not match the expected shape, or a value is not valid
401	`invalid-api-key`	Shared	The `X-API-Key` header is missing or wrong
403	`forbidden`	Shared	Your API client has no access to this API
404	`not-found`	Shared	The path does not exist
404	`case-not-found`	Non-payment insurance	The case does not exist for your API client
404	`document-not-found`	Non-payment insurance	The document is not in the case
404	`scoring-not-found`	Scoring	The scoring does not exist for your API client
409	`case-already-exists`	Non-payment insurance	The case id was already used, whatever the data
409	`invalid-case-status`	Non-payment insurance	The status of the case does not allow the action
409	`scoring-already-exists`	Scoring	The scoring id was already used
413	`file-too-large`	Shared	The file is over 10 MB
422	`documentation-incomplete`	Non-payment insurance	Documents are missing when issuing the policy; the message names them
422	`owner-data-incomplete`	Non-payment insurance	The insurer needs more data about the landlord to issue the policy
422	`unreadable-document`	Non-payment insurance	A stored document cannot be read
422	`documentation-too-large`	Non-payment insurance	The documents of the case are too large to send to the insurer
422	`scoring-has-duplicated-member`	Scoring	A personal id is repeated within the scoring
422	`immutable-field-changed`	Scoring	A field that is fixed at creation was changed
500	`internal-error`	Shared	Something went wrong on our side
502	`insurer-unavailable`	Non-payment insurance	The insurer did not answer. Safe to retry with the same case id

The 429 answer, and the 403 of a request blocked by the firewall, come from the firewall in front of the API, so they have no code. A 403 with code: forbidden comes from the API.

Get started

Tenant scoring

Non-payment insurance

Resources

Candidate

Tenant score

Confidence tiers

Case

Quote

Policy request

Case statuses

Errors