ID, morada, elegibilidade para arrendamento — num único fluxo de inquilino.

You are integrating Didit into a residential-leasing platform (PropTech / build-to-rent / letting-agent archetype). You owe the landlord (or your platform owes the landlord) an evidence pack on every applicant before the keys come off the hook.

Four obligations on every application:

  1. Verify the applicant's identity — government ID + liveness + face match.
  2. Validate the current address — utility, bank, or registry-issued letter, cross-checked against the ID.
  3. Confirm lease eligibility — Right to Rent (UK) / state-of-residence (US) / residency document (EU) / national tax id (LatAm).
  4. Screen the applicant against sanctions, Politically Exposed Persons (PEP), and adverse-media lists.

Optional: run the same flow against a guarantor and stitch both back to the lease record.

Pricing (verified live):
  - Tenant KYC bundle: $0.33 per applicant (ID + Liveness + Face Match + IP + AML)
  - Proof of Address: $0.20 per check
  - Database Validation (right-to-rent / national id): variable, per-jurisdiction
  - Linked guarantor KYC: $0.33 per guarantor
  - First 500 KYC verifications free every month, forever

PRE-REQUISITES
  - Production API key from https://business.didit.me (sandbox key in 60s, no card).
  - Webhook endpoint with HMAC SHA-256 verification using the X-Signature-V2 header and your webhook secret.
  - A workflow_id from the Workflow Builder that bundles ID Verification + Passive Liveness + Face Match 1:1 + Proof of Address + AML Screening + the jurisdiction-specific Database Validation node.
  - Optional: a separate KYC workflow_id for the guarantor.

STEP 1 — Create the tenant session

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<your tenant-screening workflow id>",
      "vendor_data": "<your applicant id, max 256 chars>",
      "callback_url": "https://<your-app>/applications/kyc/callback",
      "expected_country": "GB",
      "metadata": {
        "application_id": "<your internal id>",
        "property_id": "<unit reference>"
      }
    }

  Response: 201 Created with the hosted session URL. SMS or email the URL to the applicant; they complete everything on their phone in under five minutes.

STEP 2 — Read the signed webhook on KYC completion

  Didit POSTs to your callback. Session statuses are Title Case With Spaces:

  Body (excerpted):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your applicant id>",
      "status": "Approved",
      "id_verification": { "status": "Approved", "document_type": "passport", "country_code": "GB" },
      "liveness": { "status": "Approved" },
      "face": { "status": "Approved", "similarity_score": 0.94 },
      "proof_of_address": { "status": "Approved", "document_type": "utility_bill", "address": { "line1": "10 Long Acre", "city": "London", "postal_code": "WC2E 9LH", "country": "GB" } },
      "aml": { "status": "Approved", "hits": [] },
      "database_validation": { "status": "Approved", "service": "uk_right_to_rent", "result": { "share_code_status": "valid", "expiry_date": "2027-08-12" } }
    }

  Session status enum (exact case):
    Approved | Declined | In Review | Resubmitted | Expired | Not Finished | Kyc Expired | Abandoned

  Verify the X-Signature-V2 header BEFORE reading the body — HMAC SHA-256 of the raw bytes with your webhook secret.

STEP 3 — (Optional) Spawn a guarantor session

  If the workflow declares a guarantor step, the parent session returns a guarantor_session_url inside the decision payload. Email it to the guarantor and they run the same KYC flow on their phone. The result threads back to the parent tenant record automatically.

  Alternatively, fire a second POST /v3/session/ with a separate guarantor workflow_id and stitch the two together by setting metadata.tenant_session_id on the guarantor call.

STEP 4 — Retrieve the full evidence pack

  GET https://verification.didit.me/v3/session/{sessionId}/decision/
  Headers:
    x-api-key: <your api key>

  Returns the full decision payload — ID block, liveness block, face match, proof-of-address result with the canonical address fields, AML hits, database-validation outcome. Use this for audit-pack export and for rendering the applicant status in your letting-agent dashboard.

STEP 5 — Decide

  Branch logic:
    Approved    → forward the pack to the landlord, advance to lease signing.
    In Review   → hold the application, wait for analyst webhook update.
    Declined    → refuse the application, log the decline reason.
    Resubmitted → applicant updated something; re-read the decision.

  For Database Validation specifically — if the result indicates an expired Right to Rent share code, ask the applicant for a fresh one before moving forward.

STEP 6 — Ongoing monitoring (long leases)

  For multi-year tenancies, enable Ongoing AML at $0.07/user/year. The session status updates automatically when the tenant lands on a new sanctions list or document expirations approach (passport, visa, residency permit). Your webhook fires on every state change.

  No separate endpoint to call — the same workflow drives it.

WEBHOOK EVENT NAMES
  - status.updated — session status changed.
  - data.updated — session data changed (resubmission, expiry, ongoing AML hit).

  Verify X-Signature-V2 on every payload. The webhook secret is per-environment — sandbox key is separate from production.

CONSTRAINTS
  - Session statuses use Title Case With Spaces (Approved, In Review).
  - Default record retention is 5 years per tenant per the EU AML package; UK Right to Rent requires document copies for the tenancy duration + one year.
  - The address on the Proof of Address document MUST match the address on the underlying ID for an Approved outcome; if they differ, the session flips to In Review.

Read the docs:
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/sessions-api/retrieve-session
  - https://docs.didit.me/core-technology/proof-of-address/overview
  - https://docs.didit.me/core-technology/aml-screening/overview
  - https://docs.didit.me/integration/webhooks

Start free at https://business.didit.me — sandbox key in 60 seconds, 500 verifications free every month, no credit card.