Skip to main content
You send Vivara whatever you know about a candidate. Only the income is required. Everything else is optional, and each extra piece unlocks part of the score or raises its confidence tier.

Data

If several people rent together, send the data of each co-tenant in the same application. See Candidates who rent together.
The API accepts more fields than the score uses today, such as the employment regime and the documents. You can send them now: Vivara will use them as the score evolves, without you changing your integration. See Coming soon.

Unknown employment situation

Omit workingStatus when you do not know the candidate’s employment situation. Send their annual net income in netAnnualIncomeAmountInEuros:
You can still send personalId if you know it. If you do not, omit it too. Explicit null is also accepted for both fields and means the same as omission. The API normalizes missing values to null; the GET response includes both personalId and workingStatus, with null when not declared. For self-employed candidates, explicitly send workingStatus: "self-employed" with form100 and form130, instead of netAnnualIncomeAmountInEuros. These rules apply to both POST and PUT. PUT replaces all candidatures and members: if a member previously had a working status and you now omit it or send null, the new declaration has no working status. It does not keep the previous value. Send every candidature and member you want to retain, including all known data.

Documents

Documents are optional. Send them when you have them to move the candidate to the Accredited tier:
  • The ID document, to accredit the ID number
  • The income documents for the candidate’s employment situation, to accredit the income
See Which documents accredit income.

Adding data later

You do not need everything at once. A common sequence is:
  1. Score all the candidates for a listing with their declared income.
  2. Call the most promising ones and ask for their ID number.
  3. Collect documents from the candidates you are about to choose.
Each time you send new data, the score and the tier update. If you change the income or the ID number, the score is recalculated.

If you plan to insure the property

A quote for non-payment insurance needs more data than the score, such as the candidate’s date of birth and employment start date. If you expect to request a policy, collecting that data while you score saves you a second round with the tenant. See Get a quote.