> ## Documentation Index > Fetch the complete documentation index at: https://developers.vivara.io/llms.txt > Use this file to discover all available pages before exploring further. # Get case status and missing documents > Returns the current state of a case: its status, the offer, the documents still missing and, once issued, the policy. Designed for polling: poll with exponential backoff (at least 30 s between calls) until `status` is `policy-issued` or `rejected`. `documentation.missing` lists every requirement still unmet; the policy can only be issued once it is empty. ## OpenAPI ````yaml /openapi/arco-partner-api.json get /non-payment-insurance/cases/{caseId} openapi: 3.1.0 info: title: Vivara Partner API version: 1.0.0 description: > Vivara's external API for tenant scoring and non-payment insurance. ## Authentication Every request must include the `X-API-Key` header with the API key issued to the integration. Keys are scoped per API client: scorings and cases created with one key are not visible to other clients. ## Conventions - Money is always a number in euros with up to two decimals (`1250.5` = 1,250.50 €). - Dates are `YYYY-MM-DD`; timestamps are ISO 8601 in UTC. - Every answer that carries a resource wraps it in `data`. - Every error has the same body: `status`, `statusCode`, `code` and `message`. Use `code`, which is stable, to decide what to do. The catalog of codes is in the guides. ## Processing model **Scorings.** Creating or updating a scoring evaluates every candidature synchronously and returns no body. Read the results with `GET /scorings/{scoringId}`. In this release, evaluation finishes during create or update and `status` is `completed`. Document upload and asynchronous evaluation will arrive in a later release (`processing` and candidature status `pending`). **Non-payment insurance.** You generate the id of the case (a UUID v4) and open it with `POST /non-payment-insurance/cases`, which prices the offer synchronously and answers `201` with a `Location` header and no body. A case id that was already used answers `409`, whatever the data. Read the case, with its offer and the documents it requires, with `GET /non-payment-insurance/cases/{caseId}`. Upload the documents, issue the policy with `POST /non-payment-insurance/cases/{caseId}/policy`, and poll the case with exponential backoff (at least 30 s between calls) until it is `policy-issued` or `rejected`. ## Edge, routing and rate limiting Traffic is served through Azure Front Door, which terminates TLS at `https://api.vivara.io/v1/*` and forwards requests to the partner API. The Front Door web application firewall enforces rate limits per client IP. When a limit is exceeded it returns `429 Too Many Requests`; requests blocked by firewall rules return `403 Forbidden`. Those two answers come from the firewall and have no `code`. A `403` with `code: forbidden` comes from the API, when the API client has no access to it. Rate limit values are shared during onboarding. ## Data protection Requests contain personal data (DNI or NIE, income, and the documents of the people on a rental contract). Delete a scoring with `DELETE /scorings/{scoringId}` once it is no longer needed. Remove a document uploaded by mistake with `DELETE /non-payment-insurance/cases/{caseId}/documents/{documentId}` while the case is `pending-documentation` or `ready-to-issue`. Cases cannot be deleted. servers: - url: https://api.vivara.io/v1 description: Production - url: https://api-stg.vivara.io/v1 description: Staging security: - apiKeyAuth: [] tags: - name: Scorings description: >- Score candidates for a property and prioritize who to offer a visit to first - name: Non-payment insurance description: >- Quote, document upload and policy issuance for rental non-payment insurance cases paths: /non-payment-insurance/cases/{caseId}: get: tags: - Non-payment insurance summary: Get case status and missing documents description: > Returns the current state of a case: its status, the offer, the documents still missing and, once issued, the policy. Designed for polling: poll with exponential backoff (at least 30 s between calls) until `status` is `policy-issued` or `rejected`. `documentation.missing` lists every requirement still unmet; the policy can only be issued once it is empty. operationId: getCase parameters: - $ref: '#/components/parameters/CaseId' responses: '200': description: The case content: application/json: schema: $ref: '#/components/schemas/CaseResponse' examples: pendingDocumentation: $ref: '#/components/examples/PendingDocumentationCase' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '429': $ref: '#/components/responses/TooManyRequestsError' '500': $ref: '#/components/responses/InternalServerError' components: parameters: CaseId: name: caseId in: path required: true description: The case id, a UUID v4 you generate before quoting. schema: type: string format: uuid example: 3f9c2a7e-58b1-4d0a-9a51-0c6e2f1b7d42 schemas: CaseResponse: type: object description: The case, wrapped in `data`. required: - data properties: data: $ref: '#/components/schemas/Case' Case: type: object description: A rental contract being insured, from its quote to the issued policy. required: - id - status - effectiveDate - contractDurationMonths - rentalAmountInEuros - tenants - documentation - allowedActions - createdAt - updatedAt properties: id: type: string description: The case id you generated when asking for the quote. format: uuid example: 3f9c2a7e-58b1-4d0a-9a51-0c6e2f1b7d42 externalReference: type: string description: Your own identifier for the rental contract, as sent in the quote. example: CONTRACT-2026-004521 status: $ref: '#/components/schemas/CaseStatus' statusReason: type: string description: Human-readable explanation of the current status, in Spanish. example: Faltan 3 documentos para poder emitir la póliza. effectiveDate: type: string description: Start date of the policy, `YYYY-MM-DD`. format: date example: '2026-11-01' contractDurationMonths: type: integer description: Duration of the rental contract covered by the policy, in months. example: 12 rentalAmountInEuros: type: number description: Monthly rental amount in euros (rent plus monthly expenses). example: 1250 tenants: type: array description: Every person on the rental contract. items: $ref: '#/components/schemas/CaseTenant' offer: $ref: '#/components/schemas/Offer' documentation: $ref: '#/components/schemas/Documentation' policy: $ref: '#/components/schemas/Policy' allowedActions: type: array description: What you can do with the case right now. items: $ref: '#/components/schemas/CaseAction' example: - upload-document createdAt: type: string description: When the case was opened. format: date-time example: '2026-10-26T09:14:03Z' updatedAt: type: string description: When the case last changed. format: date-time example: '2026-10-26T09:14:05Z' Error: type: object required: - status - statusCode - code - message properties: status: type: string description: HTTP reason phrase. statusCode: type: integer description: HTTP status code. code: type: string description: >- Stable, machine-readable error code in kebab-case. Use it, not the message, to decide what to do. The full list is in the error catalog of the guides (Key concepts, Errors). message: type: string description: >- Human-readable explanation, in English. It names the fields or the documents behind the error. CaseStatus: type: string enum: - pending-documentation - ready-to-issue - rejected - policy-requested - policy-issued - failed description: > - `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. Final. - `policy-requested`: the documents and the issuance have been sent; the insurer is issuing the policy. - `policy-issued`: the policy is in force. Final. - `failed`: Vivara could not complete the last step with the insurer. It can appear from any status and it is not final: Vivara is notified and retries, and the case leaves it once the step completes. Keep polling; contact support if it persists. example: pending-documentation CaseTenant: type: object description: A person on the rental contract, with the id Vivara assigned. required: - id - role - personalId properties: id: type: string format: uuid description: Use it as `tenantId` when uploading this tenant's documents. example: 6b1e0d44-2c3f-4b8e-a0f2-91d7e5c3a810 externalReference: type: string description: Your own identifier for this person, as sent in the quote. example: TENANT-88412 role: $ref: '#/components/schemas/TenantRole' personalId: type: string description: >- Identification number of the person, as sent when the case was opened. example: X1234567L Offer: type: object description: The priced offer. Present once the insurer has answered. required: - code - description - contractable - coverages - exceptions - exclusions properties: code: type: integer description: Code of the offer at the insurer. example: 16 description: type: string description: Name of the offer, in Spanish. example: Protección Jurídica Familiar - Impago de alquiler contractable: type: boolean description: Whether the offer can be issued as it stands. example: true netPremiumInEuros: type: - number - 'null' description: Annual premium before taxes, in euros. example: 423.5 totalPremiumInEuros: type: - number - 'null' description: Annual premium including taxes. example: 451.2 firstInstallmentInEuros: type: - number - 'null' description: Amount of the first installment, in euros. example: 451.2 remainingInstallmentsInEuros: type: - number - 'null' description: Amount of each remaining installment, in euros. example: 0 conditionsPdfUrl: type: string format: uri description: The insurer's offer document. example: https://files.vivara.es/npi/3f9c2a7e/offer.pdf coverages: type: array description: The coverages the offer includes. items: $ref: '#/components/schemas/Coverage' exceptions: type: array description: >- Reasons the offer is conditioned. The insurer reviews them against the documentation after the issuance request. items: $ref: '#/components/schemas/InsurerNotice' exclusions: type: array description: Reasons the offer cannot be contracted. items: $ref: '#/components/schemas/InsurerNotice' Documentation: type: object description: >- The documentation of the case: what is required, what is missing and what was uploaded. required: - complete - missing - documents properties: complete: type: boolean description: Every requirement is met, so the policy can be issued. example: false sentToInsurerAt: type: - string - 'null' format: date-time description: >- When the documents were merged and sent to the insurer, as part of the issuance. `null` until then. example: null missing: type: array description: Requirements still unmet. Empty once everything is uploaded. items: $ref: '#/components/schemas/DocumentRequirement' documents: type: array description: Documents uploaded so far. items: $ref: '#/components/schemas/UploadedDocument' Policy: type: object description: Present once issuance has been requested. required: - status properties: status: type: string enum: - pending-signature - pending-insurer - issued description: > - `pending-signature`: the landlord must sign the policy electronically (the insurer emails them). - `pending-insurer`: the insurer is finishing the issuance. - `issued`: the policy is in force. example: issued policyNumber: type: string description: The policy number, once the insurer assigns it. example: '0471203398' requestedAt: type: string description: When the issuance was requested. format: date-time example: '2026-10-26T11:30:00Z' issuedAt: type: string description: When the policy was issued. format: date-time example: '2026-10-26T11:30:04Z' documents: type: array description: Documents of the policy. items: $ref: '#/components/schemas/PolicyDocument' CaseAction: type: string description: An action the partner can take on the case in its current status. enum: - upload-document - issue-policy TenantRole: type: string description: Whether the person is a tenant or a guarantor. enum: - tenant - guarantor example: tenant Coverage: type: object description: A coverage included in the offer. required: - code - sumInsuredInEuros properties: code: type: integer description: Code of the coverage at the insurer. example: 101 sumInsuredInEuros: type: number description: Maximum amount the coverage pays, in euros. example: 15000 InsurerNotice: type: object description: A reason the insurer gives about the offer, with its own code. required: - code - description properties: code: type: string description: Code of the notice at the insurer. example: EX-214 description: type: string description: What the insurer says, in Spanish. example: Ratio renta/ingresos superior al permitido DocumentRequirement: type: object description: A requirement the uploaded documents must still meet. required: - anyOf - minFiles - uploadedFiles properties: tenantId: type: string format: uuid description: The tenant the requirement is for. Absent for case requirements. example: 6b1e0d44-2c3f-4b8e-a0f2-91d7e5c3a810 anyOf: type: array description: Any of these document types satisfies the requirement. items: $ref: '#/components/schemas/DocumentType' example: - employment-contract - work-history-report minFiles: type: integer description: How many files the requirement needs. example: 1 uploadedFiles: type: integer description: How many files were uploaded for it so far. example: 0 templateUrl: type: string format: uri description: >- A template to fill in and sign, when the document is one Vivara provides. example: https://files.vivara.es/npi/templates/anexo-lopd.pdf UploadedDocument: type: object required: - id - type - fileName - uploadedAt properties: id: type: string description: The document id. Use it to remove the document. format: uuid example: c41a8e93-7d2b-4f6a-b5e1-2a9f0c8d3e17 type: $ref: '#/components/schemas/DocumentType' tenantId: type: string description: The tenant the document belongs to. Absent for case documents. format: uuid example: 6b1e0d44-2c3f-4b8e-a0f2-91d7e5c3a810 fileName: type: string description: Name of the uploaded file. example: nomina-septiembre.pdf uploadedAt: type: string description: When the document was stored. format: date-time example: '2026-10-26T10:02:41Z' PolicyDocument: type: object description: A document of the issued policy. required: - type - url properties: type: type: string description: Kind of document. enum: - policy - certificate - direct-debit-mandate example: policy url: type: string description: Where to download it. format: uri example: https://files.vivara.es/npi/3f9c2a7e/policy.pdf DocumentType: type: string enum: - data-protection-consent - identity-document - employment-contract - work-history-report - payslip - income-tax-return - quarterly-tax-return - pension-certificate - company-tax-id-card - corporate-income-tax-return - power-of-attorney - guarantor-identity-document - guarantor-income-proof - military-commitment description: > `data-protection-consent` is the signed data protection annex (Anexo LOPD), a case document signed by the landlord and every tenant. Every other type is a tenant document. example: payslip examples: PendingDocumentationCase: summary: A priced case that still needs documents value: data: id: 3f9c2a7e-58b1-4d0a-9a51-0c6e2f1b7d42 externalReference: CONTRACT-2026-004521 status: pending-documentation effectiveDate: '2026-11-01' contractDurationMonths: 12 rentalAmountInEuros: 1250 tenants: - id: 6b1e0d44-2c3f-4b8e-a0f2-91d7e5c3a810 externalReference: TENANT-88412 role: tenant personalId: 87654321X offer: code: 16 description: Protección Jurídica Familiar - Impago de alquiler contractable: true netPremiumInEuros: 423.5 totalPremiumInEuros: 451.2 firstInstallmentInEuros: 451.2 remainingInstallmentsInEuros: 0 coverages: - code: 101 sumInsuredInEuros: 15000 exceptions: [] exclusions: [] documentation: complete: false sentToInsurerAt: null missing: - anyOf: - data-protection-consent minFiles: 1 uploadedFiles: 0 - tenantId: 6b1e0d44-2c3f-4b8e-a0f2-91d7e5c3a810 anyOf: - identity-document minFiles: 1 uploadedFiles: 0 documents: [] allowedActions: - upload-document createdAt: '2026-10-26T10:15:00Z' updatedAt: '2026-10-26T10:15:04Z' responses: UnauthorizedError: description: >- Unauthorized. The X-API-Key header is missing or the API key is not valid. content: application/json: schema: $ref: '#/components/schemas/Error' example: status: Unauthorized statusCode: 401 code: invalid-api-key message: Invalid API key ForbiddenError: description: >- Forbidden. The API client has no access to this API, or the request was blocked by the edge firewall. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - 179b90ba-7311-450d-aaec-7de48cb6a4fb examples: forbidden: summary: The API client has no access to this API value: status: Forbidden statusCode: 403 code: forbidden message: The API client has no access to this API firewall: summary: Blocked by the edge firewall value: status: Forbidden statusCode: 403 message: Request blocked by the firewall NotFoundError: description: >- Not found. The scoring, the case or the document does not exist for the authenticated API client. content: application/json: schema: $ref: '#/components/schemas/Error' examples: scoringNotFound: summary: Scoring not found value: status: Not Found statusCode: 404 code: scoring-not-found message: Scoring 6d1f0c3e-5b8a-4c1e-9f2a-3b7e8d4a1c90 not found caseNotFound: summary: Case not found value: status: Not Found statusCode: 404 code: case-not-found message: No case exists with id 3f9c2a7e-58b1-4d0a-9a51-0c6e2f1b7d42. documentNotFound: summary: Document not found in the case value: status: Not Found statusCode: 404 code: document-not-found message: >- No document exists with id c41a8e93-7d2b-4f6a-b5e1-2a9f0c8d3e17 in case 3f9c2a7e-58b1-4d0a-9a51-0c6e2f1b7d42. pathNotFound: summary: The path does not exist value: status: Not Found statusCode: 404 code: not-found message: Cannot GET /non-payment-insurance/unknown TooManyRequestsError: description: >- Too many requests. The rate limit enforced by Azure Front Door was exceeded. Retry with exponential backoff. content: application/json: schema: type: object description: >- Error answered by the edge firewall (Azure Front Door), before the request reaches the API. It has no `code`. required: - status - statusCode - message properties: status: type: string description: HTTP reason phrase. statusCode: type: integer description: HTTP status code. message: type: string description: Human-readable explanation. example: status: Too Many Requests statusCode: 429 message: Rate limit exceeded InternalServerError: description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/Error' example: status: Internal Server Error statusCode: 500 code: internal-error message: Something went wrong securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-Key description: API key issued per external API client. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.