Product-Specific Terms

API Terms & Developer Policy — postal.ID

These terms govern use of postal.ID APIs.

1. API keys and security

API keys are confidential credentials.
Customer must rotate compromised keys and notify postal.ID.
Use IP allowlisting where available.

2. Rate limits and fair use

We may impose rate limits to protect service availability. Excessive use or abuse may result in throttling or suspension.

3. Webhooks

Customer is responsible for verifying webhook signatures and securing webhook endpoints.

4. Prohibited use

No scraping, enumeration, or unauthorized security testing without written permission.

5. Changes and deprecation

We will provide reasonable notice for breaking changes and deprecations.

6. Logging

API requests may be logged for security and troubleshooting, subject to retention.

Legale

Guida di Riferimento

82 voci disponibile

Dashboard Overview

Total Cases

Descrizione

The total number of verification cases created across all statuses. Includes active, completed, failed, and expired cases.

Impatto

Tracks overall verification volume and platform adoption. Spikes may indicate batch uploads or new client onboarding.

Esempio

Displayed as a number, e.g. "247". Includes all cases regardless of status (active, completed, failed, expired).

Benchmark

Typical tenants process 50-500 cases/month depending on plan.

Suggerimenti Pro

• Use batch CSV upload for high-volume onboarding periods.
• Monitor for unexpected spikes which may indicate API misuse.

Completed

Descrizione

Cases that have reached the COMPLETE terminal state — all required verification layers passed successfully.

Impatto

Directly measures successful verifications. A low completed count relative to total cases suggests drop-off in the verification funnel.

Esempio

Displayed as a number, e.g. "189". Only counts cases with status = COMPLETE.

Benchmark

Healthy completion rates are 70-85% of total cases.

Formula

Count of cases where status = COMPLETE

Suggerimenti Pro

• Send reminders to subjects with pending verifications.
• Review failed cases to identify common blockers.

In Transit

Descrizione

Cases where a postal letter has been dispatched but not yet delivered or verified. Status is POSTAL_DISPATCHED.

Impatto

High in-transit counts may indicate postal delays or delivery issues in certain regions.

Esempio

Displayed as a number, e.g. "34". Counts cases with status = POSTAL_DISPATCHED.

Benchmark

UK letters: 1-3 business days. EU/US: 3-7 business days.

Letters in transit for more than 10 business days may indicate delivery failure.

Suggerimenti Pro

• Check delivery tracking for stuck letters.
• Consider re-dispatching if beyond expected delivery window.

Success Rate

Descrizione

Percentage of cases that reached COMPLETE status out of all cases that have reached a terminal state (COMPLETE, FAILED, or EXPIRED).

Impatto

The primary health metric for your verification process. Low success rates may indicate issues with subject engagement, postal delivery, or bundle configuration.

Esempio

Displayed as a percentage, e.g. "82.5%". If 165 of 200 terminal cases completed, rate = 82.5%.

Benchmark

75-90% is healthy. Below 60% warrants investigation.

Formula

COMPLETE / (COMPLETE + FAILED + EXPIRED) x 100

Success rate excludes in-progress cases. A high total with low terminal count means most cases are still active.

Suggerimenti Pro

• Enable automated reminders to improve completion.
• Review expired cases — shorter TTLs increase expiry rates.

Case Lifecycle

CREATED

Descrizione

Initial state when a case is first created. No verification actions have been taken yet.

Impatto

Cases should move out of CREATED quickly. A backlog here means digital verification or letter dispatch is delayed.

Esempio

Input: Subject name "Jane Smith", address "12 Baker Street, London, NW1 6XE, GB", email "jane@example.com". Output: Case created with status CREATED.

Suggerimenti Pro

• Automate dispatch to avoid cases sitting in CREATED.

DIGITAL_PENDING

Descrizione

Email and/or SMS OTP has been sent to the subject. Waiting for them to enter the code.

Impatto

Long dwell times suggest the subject did not receive the OTP or is not engaging.

Esempio

Email OTP sent: "A3K9X2MF" (8 characters). SMS OTP sent: "482917" (6 digits). Subject enters the code on the verification page.

Benchmark

Most digital verifications complete within 5 minutes of sending.

Suggerimenti Pro

• Check for disposable email addresses causing delivery failures.
• SMS delivery rates vary by carrier — monitor bounce rates.

DIGITAL_VERIFIED

Descrizione

Subject has successfully entered the correct email/SMS OTP. Digital layer is complete.

Impatto

If the bundle includes postal verification, the case will transition to POSTAL_DISPATCHED next.

Esempio

Subject entered "A3K9X2MF" correctly. Status transitions from DIGITAL_PENDING to DIGITAL_VERIFIED.

POSTAL_DISPATCHED

Descrizione

A physical letter with a unique 10-character OTP and QR code has been printed and dispatched via the postal provider.

Impatto

Delivery tracking is available for UK and US/Canada (tracked delivery).

Esempio

Letter dispatched with postal OTP "K7M2X9P4LR" (10 characters) and QR code linking to verification URL. Tracking reference: "TRK12345678".

Benchmark

UK: 1-3 days. EU/US: 3-7 days.

POSTAL_PENDING

Descrizione

Letter has been confirmed delivered (via tracking) but the subject has not yet entered the postal OTP.

Impatto

The subject has the letter but has not acted. A reminder may help.

Esempio

Tracking shows "Delivered" on 2026-02-20. Subject has not yet entered OTP "K7M2X9P4LR". Reminder email scheduled.

Suggerimenti Pro

• Enable automated reminders for postal-pending cases.
• QR code on the letter makes verification faster — mention this to subjects.

POSTAL_VERIFIED

Descrizione

Subject has entered the correct postal OTP. Physical address possession is confirmed.

Impatto

The case will now transition to COMPLETE (assuming all required layers are verified).

Esempio

Subject entered "K7M2X9P4LR" correctly via QR scan or manual entry. Address possession confirmed.

COMPLETE

Descrizione

All required verification layers have been successfully completed. Evidence pack is sealed with SHA-256 hash chain.

Impatto

Terminal state. The evidence pack is now available for download and webhook delivery.

Esempio

Case completed with assurance level "Verified (Digital + Postal)". Evidence pack PDF available for download. Webhook "case.completed" fired.

Completed cases cannot be re-opened. Create a new case if re-verification is needed.

FAILED

Descrizione

Case failed due to max OTP attempts exceeded, fraud detection, or manual rejection by a caseworker.

Impatto

Terminal state. Review the case timeline for the specific failure reason.

Esempio

Reason: "Max OTP attempts exceeded (5/5 for postal layer)". Or: "Caseworker rejected — ghost address confirmed".

Failed cases count against your verification quota.

Suggerimenti Pro

• Check risk signals — disposable emails and ghost addresses are common causes.
• Cases can be failed manually from MANUAL_REVIEW status.

EXPIRED

Descrizione

Case exceeded its time-to-live (TTL) without completing all required verification layers.

Impatto

Terminal state. The subject did not complete verification within the allowed window.

Esempio

Case created 2026-01-15 with 30-day TTL. Expired on 2026-02-14 with status stuck at POSTAL_PENDING.

Benchmark

Default TTL is 30 days. Adjust per bundle if needed.

Suggerimenti Pro

• Increase TTL for international postal verifications.
• Send reminders before expiry to improve completion rates.

Assurance Levels

Verified (Digital)

Descrizione

Case completed using only digital verification (email and/or SMS OTP). No postal letter was required or sent.

Impatto

Fastest verification method. Suitable for lower-risk scenarios where regulatory requirements allow digital-only proof.

Esempio

Subject verified email ("A3K9X2MF") and SMS ("482917"). No postal letter sent. Assurance badge shows "Digital".

Digital-only does not prove physical address possession. Some regulators may not accept this level.

Verified (Postal)

Descrizione

Case completed using postal letter verification only. A physical letter was sent and the OTP was entered correctly.

Impatto

Proves physical possession of the address. Stronger than digital-only but lacks digital cross-reference.

Esempio

Subject received letter and entered OTP "K7M2X9P4LR". No email/SMS required. Assurance badge shows "Postal".

Verified (Digital + Postal)

Descrizione

Case completed using both digital (email/SMS) and postal letter verification. Highest assurance level.

Impatto

Maximum assurance — confirms both digital contact details and physical address. Meets the strictest FCA, SRA, and HMRC audit requirements.

Esempio

Subject verified email + SMS (digital), then received letter and entered postal OTP. Badge shows "Digital + Postal".

Benchmark

Recommended for regulated industries: law firms, financial services, accountancy.

Suggerimenti Pro

• Use the Enhanced or Maximum bundle to achieve this level automatically.

Risk & Fraud

Risk Score

Descrizione

Composite fraud risk score from 0-100 calculated at case creation. Higher scores indicate greater risk.

Impatto

Determines whether risk-based step-up is triggered. Cases above the threshold are automatically escalated from digital to postal verification.

Esempio

Score 15: Low risk (no signals). Score 45: Medium (disposable email detected). Score 75: High (ghost address + velocity + disposable email).

Benchmark

0-30: Low risk. 30-60: Medium risk. 60+: High risk (step-up likely).

Formula

Weighted sum of individual risk signals (disposable email, ghost address, address velocity, etc.)

Suggerimenti Pro

• Configure step-up threshold in tenant settings.
• Review high-risk cases manually even if they complete.

Disposable Email

Descrizione

Detected when the subject email address belongs to a known disposable/temporary email provider (e.g. Guerrilla Mail, Tempail).

Impatto

Strong fraud indicator. Disposable emails cannot receive follow-up communications and suggest intent to avoid accountability.

Esempio

Input email: "user@guerrillamail.com" or "temp@throwaway.email". Signal triggers: Disposable Email = true, +25 risk points.

Contributes 25 points to the risk score by default.

Suggerimenti Pro

• Consider requiring postal verification for all cases with disposable emails.

Ghost Address

Descrizione

Address matches a known mail forwarding service, virtual office, PO box farm, or serviced office address.

Impatto

The subject may not physically reside or operate at this address. Letters will be received but do not prove actual occupancy.

Esempio

Input address: "71-75 Shelton Street, London, WC2H 9JQ" (known virtual office). Signal triggers: Ghost Address = true.

Ghost addresses undermine the core promise of postal verification. Always investigate.

Suggerimenti Pro

• Cross-reference with business registration records.
• Consider requiring in-person verification for ghost addresses.

Mail Forwarding

Descrizione

Address is associated with a mail forwarding or redirection service (e.g. postal redirection service, PO Box).

Impatto

Mail forwarding means the letter could be received at a different physical location than the claimed address.

Esempio

Input address: "PO Box 4521, Manchester, M60 3AT" or an address with an active postal redirect. Signal: Mail Forwarding = true.

Forwarded mail breaks the proof-of-address chain. The letter arrives but not necessarily at the claimed address.

Address Velocity

Descrizione

Multiple cases for different subjects have been submitted with the same address within a rolling time window.

Impatto

Could indicate a legitimate shared address (e.g. office building) or a fraud pattern where one address is used for multiple fake identities.

Esempio

5 different subjects verified at "42 High Street, Bristol, BS1 2AW" in the past 7 days. Velocity signal triggered.

Benchmark

1-2 cases per address per month is normal. 5+ within a week is suspicious.

Suggerimenti Pro

• Cross-reference with subject names to identify legitimate shared offices.
• Set velocity thresholds in fraud configuration.

Cross-Tenant

Descrizione

The same address has appeared in verification cases across different tenants on the platform.

Impatto

May indicate an address being used to fraudulently verify across multiple regulated firms simultaneously.

Esempio

"10 Downing Street, London" verified by 3 different tenants in the past 30 days. Cross-tenant signal raised (tenant names anonymised).

Cross-tenant signals are anonymised — you see the signal but not the other tenant's details.

IP Mismatch

Descrizione

The IP address used during digital verification geolocates to a region significantly different from the claimed postal address.

Impatto

May indicate the subject is not near the claimed address. However, VPN usage can produce false positives.

Esempio

Claimed address: London, UK. Verification IP: 203.0.113.45 (geolocated to Lagos, Nigeria). Mismatch distance: 4,900 km.

IP geolocation is approximate — do not use as sole rejection criteria.

Suggerimenti Pro

• Combine with geo-location layer for stronger physical presence confirmation.

Step-Up

Descrizione

Automatic escalation from a digital-only verification bundle to include postal verification, triggered when the risk score exceeds the configured threshold.

Impatto

Ensures high-risk cases get physical address verification even when the original bundle was digital-only.

Esempio

Case created with "Basic" bundle (email only). Risk score = 72 (above threshold 60). Postal layer automatically added. Step-Up badge shown.

Benchmark

Default step-up threshold is 60 (configurable per tenant).

Suggerimenti Pro

• Monitor step-up rates — very high rates may mean your threshold is too low.
• Step-up adds postal cost; factor this into billing estimates.

Verification Bundles

Email Layer

Descrizione

Sends an 8-character OTP code to the subject's email address for verification.

Impatto

Fast digital verification — most subjects complete within minutes. Validates email ownership but not physical address.

Esempio

Input: subject email "jane.smith@lawfirm.co.uk". Output: OTP "A3K9X2MF" sent via configured email template.

Benchmark

Delivery rate: 98%+ for legitimate email addresses. Completion rate: 85-95%.

Suggerimenti Pro

• Customise the email template with your branding via Template Engine.
• Check bounce rates — high bounces suggest invalid email data.

SMS Layer

Descrizione

Sends a 6-digit OTP code via SMS to the subject's mobile number.

Impatto

Validates phone number ownership. Higher engagement than email due to push notification.

Esempio

Input: subject phone "+44 7700 900123". Output: SMS with OTP "482917" sent. Subject enters code on verification page.

Benchmark

Delivery rate: 95-99% depending on carrier. Completion rate: 90%+.

SMS costs are per-message and vary by country. International SMS is more expensive.

Suggerimenti Pro

• Use as a complement to email, not a replacement — some subjects prefer email.

Postal Layer

Descrizione

Dispatches a physical letter with a unique 10-character OTP and QR code to the subject's claimed address.

Impatto

The core Postal.id verification — proves physical possession of the address. Unfakeable by digital means.

Esempio

Input: "12 Baker Street, London, NW1 6XE". Letter printed with OTP "K7M2X9P4LR" + QR code. Dispatched via tracked post.

Benchmark

UK delivery: 1-3 days. Completion rate: 70-85% (dependent on subject engagement).

Postal verification is slower and more expensive than digital. Use for higher-assurance requirements.

Suggerimenti Pro

• Enable QR code scanning to simplify the subject experience.
• Customise the letter template with your branding.

Geo Layer

Descrizione

Captures GPS coordinates from the subject's device at the time of OTP entry. Compares with the claimed address location.

Impatto

Adds a physical presence confirmation. The subject must be near the claimed address when entering the postal OTP.

Esempio

Claimed address: 51.5074, -0.1278 (London). Subject GPS: 51.5081, -0.1290 (0.15 km away). Within 1 km radius: PASS.

Requires location permissions from the subject's browser. Some may decline.

Suggerimenti Pro

• Configure the acceptable radius (default: 1km) based on your needs.
• Urban areas may need a smaller radius; rural areas may need larger.

TTL (Time to Live)

Descrizione

Maximum number of days allowed for the subject to complete all required verification layers before the case expires.

Impatto

Shorter TTLs create urgency but increase expiry rates. Longer TTLs are more lenient but delay case resolution.

Esempio

Input: 30 (days). Case created 2026-02-01 will expire 2026-03-03 if not completed. Enter 7-60 depending on use case.

Benchmark

Default: 30 days. For urgent verifications, 7-14 days. For international postal, 45-60 days.

Suggerimenti Pro

• Match TTL to the expected postal delivery time in the target country.
• Send reminders at 50% and 80% of TTL elapsed.

Max Attempts

Descrizione

Maximum number of OTP entry attempts allowed per verification layer before the case is marked as failed.

Impatto

Prevents brute-force OTP guessing. Too few attempts frustrate legitimate subjects; too many weaken security.

Esempio

Input: 5. Subject enters wrong OTP 5 times → case fails. Enter 3-10 (recommended: 5 for standard, 3 for high security).

Benchmark

Default: 5 attempts. Security-sensitive: 3 attempts.

Formula

After max attempts exhausted → case status transitions to FAILED.

Each failed attempt is logged in the audit trail and may contribute to risk scoring.

Letter Format

Descrizione

The postal format used for dispatching verification letters. Options depend on the provider and destination country.

Impatto

Different formats have different costs, delivery speeds, and tracking capabilities.

Esempio

Options: "standard" (cheapest, no tracking), "tracked" (mid-range, delivery confirmation), "certified" (signature required).

Suggerimenti Pro

• Standard letter: cheapest, no tracking. Tracked letter: mid-range, delivery confirmation. Certified mail: most expensive, signature required.

Required vs Optional

Descrizione

Each verification layer in a bundle can be marked as required or optional. Required layers must be completed; optional layers enhance assurance if completed.

Impatto

Required layers determine the minimum assurance level. Optional layers provide additional confidence without blocking completion.

Esempio

Bundle config: Email = Required, SMS = Optional, Postal = Required, Geo = Optional. Subject must complete email + postal; SMS and geo are bonus.

Suggerimenti Pro

• Make postal required for regulated use cases.
• Make geo optional to avoid blocking subjects who decline location permissions.

Postal Delivery

Delivery Rate

Descrizione

Percentage of dispatched letters that were successfully delivered to the destination address.

Impatto

Low delivery rates may indicate address quality issues, incorrect postcodes, or regional postal problems.

Esempio

96 of 100 letters delivered = 96% delivery rate. Displayed as a percentage on the postal metrics card.

Benchmark

UK: 98%+. EU: 95-98%. US: 97%+.

Formula

Delivered / Dispatched x 100

Suggerimenti Pro

• Validate addresses before dispatching.
• Monitor delivery rates by country to identify regional issues.

Return Rate

Descrizione

Percentage of dispatched letters returned to sender (RTS) by the postal service.

Impatto

High return rates indicate invalid addresses, subjects who have moved, or incorrect address formatting.

Esempio

3 of 100 letters returned = 3% return rate. Common reasons: "addressee gone away", "insufficient address".

Benchmark

Healthy: below 3%. Above 5% warrants address validation review.

Formula

Returned / Dispatched x 100

Returns add cost (dispatch + return postage) with no verification value.

Avg Delivery Days

Descrizione

Average number of business days between letter dispatch and confirmed delivery (where tracking is available).

Impatto

Helps set realistic TTL values and subject expectations.

Esempio

Displayed as "1.8 days" for UK, "4.2 days" for EU. Based on tracked deliveries in your recent cases.

Benchmark

UK: 1.5 days. EU: 4-5 days. US: 3-4 days.

QR Scan Rate

Descrizione

Percentage of postal verifications completed by scanning the QR code on the letter versus manually typing the OTP.

Impatto

Higher QR scan rates indicate good subject experience — scanning is faster and less error-prone.

Esempio

55 of 100 postal verifications used QR scan = 55%. Remaining 45% typed the 10-character OTP manually.

Benchmark

Typical: 40-60% use QR scanning.

Suggerimenti Pro

• Mention QR scanning in subject communications to increase adoption.

Address Alerts

Address Velocity Signal

Descrizione

Alert triggered when an address receives more verification cases than the configured threshold within a time window.

Impatto

May indicate legitimate shared occupancy or potential fraud via address reuse.

Esempio

Alert: "42 High Street, Bristol" — 5 cases in 7 days (threshold: 3 per 30 days). Investigate shared office or fraud.

Benchmark

Default threshold: 3 cases per address per 30 days.

Suggerimenti Pro

• Acknowledge alerts after investigation to keep the list manageable.
• Adjust thresholds based on your client demographics.

Cross-Tenant Signal

Descrizione

Alert triggered when the same address is being verified across multiple different tenants on the platform.

Impatto

Could indicate a professional fraud attempt spanning multiple regulated firms.

Esempio

Alert: "10 Downing Street, London" appears in 3 different tenants within 30 days. Other tenant names are anonymised.

Cross-tenant details are anonymised for data protection. You see the signal, not the other tenant's case details.

Alert Score

Descrizione

Numerical severity score assigned to each address alert based on the type and frequency of signals detected.

Impatto

Higher scores warrant more urgent investigation. Used for prioritising the alert queue.

Esempio

Score 15 (low): single velocity signal. Score 45 (medium): velocity + ghost address. Score 80 (high): cross-tenant + velocity + forwarding.

Benchmark

1-30: Low priority. 30-60: Medium. 60+: High priority — investigate immediately.

Acknowledge

Descrizione

Mark an alert as reviewed after investigation. Acknowledged alerts are moved out of the active queue.

Impatto

Helps team members track which alerts have been investigated versus which need attention.

Esempio

Click "Acknowledge" on an alert → add a note like "Confirmed shared office building, legitimate usage". Alert moves to resolved queue.

Suggerimenti Pro

• Add a note when acknowledging to document your investigation findings.
• Acknowledged alerts remain in the audit trail permanently.

Webhooks

Webhook Events

Descrizione

Real-time HTTP POST notifications sent to your configured endpoint when case status changes occur.

Impatto

Enables automated workflows — update your CRM, trigger follow-up actions, or sync verification status with your systems.

Esempio

Events: case.created, case.digital_verified, case.postal_dispatched, case.postal_verified, case.completed, case.failed, case.expired, letter.dispatched, letter.delivered

Suggerimenti Pro

• Subscribe only to events you need to reduce noise.
• Use case.completed for most integration use cases.

HMAC-SHA256 Signature

Descrizione

Every webhook request includes an X-Postal-Id-Signature header containing an HMAC-SHA256 hash of the request body using your webhook secret.

Impatto

Verify this signature before processing to ensure the webhook came from Postal.id and was not tampered with.

Esempio

Header: "X-Postal-Id-Signature: sha256=a1b2c3d4e5...". Verify by computing HMAC-SHA256(your_secret, raw_body) and comparing.

Formula

HMAC-SHA256(webhook_secret, request_body)

Never process webhooks without verifying the signature — this is a critical security control.

Retry Behaviour

Descrizione

Failed webhook deliveries (non-2xx response or timeout) are retried with exponential backoff up to 5 attempts.

Impatto

Ensures temporary outages on your side do not cause missed events.

Esempio

Retry delays: ~30s, ~2min, ~8min, ~30min, ~2hr (exponential backoff with jitter)

After 5 failed attempts, the webhook is marked as failed. Check the webhook logs to identify persistent failures.

Billing & Usage

Plan Limit

Descrizione

Maximum number of verification cases included in your current subscription plan per billing period.

Impatto

Cases beyond the plan limit may incur overage charges or be blocked depending on your plan settings.

Esempio

Performance plan: "87 / 100 cases used this period". At 100, new case creation may be blocked until next period.

Benchmark

Essential: 25/month. Performance: 100/month. Enterprise: unlimited.

Suggerimenti Pro

• Monitor usage at 80% of limit to avoid disruptions.
• Upgrade plan before hitting limits for uninterrupted service.

Usage Period

Descrizione

The current billing cycle during which verification cases are counted against your plan limit.

Impatto

Case counts reset at the start of each billing period.

Esempio

Displayed as "1 Feb 2026 — 28 Feb 2026". Cases created within this window count toward the limit.

Plan Status

Descrizione

Current state of your subscription: active, past_due, cancelled, or trialing.

Impatto

Verification capabilities may be restricted for past_due or cancelled plans.

Esempio

Values: "active" (normal), "trialing" (free trial), "past_due" (payment failed), "cancelled" (subscription ended).

Past-due accounts have a grace period before case creation is blocked.

Verification Funnel

Funnel Overview

Descrizione

Visual breakdown of cases at each stage of the verification lifecycle, showing where subjects progress and where they drop off.

Impatto

Identify bottlenecks — if many cases stall at POSTAL_PENDING, subjects are receiving letters but not entering codes.

Esempio

Created: 100 → Digital Verified: 85 → Postal Dispatched: 80 → Postal Verified: 65 → Complete: 62 → Failed: 8 → Expired: 15.

Suggerimenti Pro

• Focus improvement efforts on the stage with the largest drop-off.
• Compare funnel shapes across different verification bundles.

Manual Review

Descrizione

Cases escalated from the automated flow for human review. Typically due to risk signals, edge cases, or caseworker discretion.

Impatto

Manual review cases require a caseworker to approve or reject. They do not auto-complete.

Esempio

Case escalated due to risk score 85 + ghost address. Caseworker reviews evidence, clicks "Approve" (→ COMPLETE) or "Reject" (→ FAILED).

Suggerimenti Pro

• Set up notifications for new manual review cases to reduce response time.
• Document review decisions in case notes for audit trail.

Batch Upload

Descrizione

Create multiple verification cases at once by uploading a CSV file. The system validates every row, flags errors, checks for duplicates, and processes valid rows in parallel.

Impatto

Enables bulk onboarding — process hundreds of verification cases from a single file upload instead of creating them one by one.

Esempio

Upload "clients_q1.csv" with 50 rows → Validate → 47 valid, 2 invalid, 1 duplicate → Upload 47 cases → Cases created and digital OTPs sent.

Suggerimenti Pro

• Always validate before uploading to catch errors early.
• Download the template CSV for the correct column format.

CSV Format

Descrizione

Your CSV must include these required columns: name (subject's full name), line1 (street address), city, postalCode, countryCode (2-letter ISO code e.g. GB, US, DE). Optional columns: email, phone (with country prefix e.g. +44), line2, region, reference (your internal ID), bundleId.

Impatto

Correct CSV formatting ensures maximum validation success. Missing required columns will cause row-level errors.

Esempio

Header row: name,email,phone,line1,line2,city,region,postalCode,countryCode,reference,bundleId Data row: Jane Smith,jane@example.com,+447700900123,12 Baker Street,,London,,NW1 6XE,GB,MATTER-001,bundle_enhanced

Using "UK" instead of "GB" is the most common error. The correct ISO code for United Kingdom is "GB".

Suggerimenti Pro

• Download the CSV template from the batch upload page for guaranteed correct format.
• Use 2-letter ISO country codes: GB (not UK), US, DE, FR, NL, IE, ES, IT, CA, AU.
• Phone numbers must include country prefix (e.g. +44 for UK, +1 for US).

CSV Validation

Descrizione

Before uploading, click "Preview & Validate" to check your file. The system checks: required fields present, valid email format, valid country codes, address completeness, and duplicate detection against existing cases.

Impatto

Validation catches errors before cases are created, saving time and avoiding wasted postal costs on invalid addresses.

Esempio

Validation results: Total Rows: 50, Valid: 47 (green), Invalid: 2 (red), Duplicates: 1 (amber). Country breakdown: GB: 30, US: 15, DE: 5.

Suggerimenti Pro

• Fix invalid rows and re-upload — only valid rows will be processed.
• Duplicates are detected by matching name + address against existing active cases.

Validation Errors

Descrizione

Common errors: "Missing required field" (name/line1/city/postalCode/countryCode is blank), "Invalid country code" (not a recognised 2-letter ISO code), "Invalid email format" (malformed email), "Duplicate" (same name+address already exists as an active case).

Impatto

Each error shows the row number, field name, and error message so you can fix the exact issue in your CSV.

Esempio

Row 15: postalCode — "Missing required field". Row 23: countryCode — "Invalid country code 'UK' (expected 'GB')". Row 31: name — "Duplicate of row 12 (Jane Smith, 12 Baker Street)".

Suggerimenti Pro

• Check postcode format matches the target country (UK: "SW1A 2AA", US: "10001" or "10001-1234").
• Remove duplicate rows before uploading.

Upload Results

Descrizione

After validation, you'll see: Total Rows (all rows in CSV), Valid (ready to upload), Invalid (have errors — fix and re-upload), Duplicates (match existing active cases — skipped). Only valid rows are processed when you click Upload.

Impatto

Invalid and duplicate rows are skipped. You can download a report of failed rows to fix and re-upload separately.

Esempio

Click "Upload 47 Cases" → system creates 47 verification cases in parallel. Each case gets digital OTPs sent immediately. Postal letters dispatched based on bundle config.

Batch Job Status

Descrizione

After upload, each batch job shows a status: Processing (still creating cases), Complete (all rows processed), Failed (system error during processing). The progress bar shows Succeeded/Failed/Remaining counts.

Impatto

Monitor batch progress in real-time. Most batches complete within minutes.

Esempio

Batch "clients_q1.csv": 47/47 processed, 45 succeeded, 2 failed. Click "View Errors" to see which rows failed.

Suggerimenti Pro

• Failed rows can be retried without re-uploading the entire file.
• Download the error report CSV for failed rows with detailed error messages.

Error Report

Descrizione

Click "View Errors" on a completed batch to see which rows failed and why. Click "Download Report" to get a CSV of failed rows with error details — fix the errors and re-upload just those rows. "Retry Failed" re-processes failed rows without re-uploading.

Impatto

Efficiently handle partial failures without re-processing the entire batch.

Esempio

Error report: Row 12 — "Address validation failed: undeliverable address". Row 38 — "Plan limit exceeded". Fix address in row 12, upgrade plan, then retry.

Quick Actions

New Case

Descrizione

Opens the case creation form where you enter the subject's details, address, and select a verification bundle. Once submitted, digital OTPs are sent immediately and a postal letter is dispatched (if the bundle includes postal verification).

Impatto

The primary way to start a single address verification. For bulk verifications, use Batch Upload instead.

Esempio

Click "New Case" → fill in name, email, address → select "Enhanced" bundle → click "Create Case" → email OTP sent within seconds, letter dispatched within 1 hour.

Suggerimenti Pro

• Use address autocomplete for faster, more accurate address entry.
• Select the right bundle upfront — changing it later requires creating a new case.

Recipients

Descrizione

View all subjects (people being verified) across all your cases. Search by name, email, phone, or address. Click any recipient to see their full verification history, risk signals, and address changes over time.

Impatto

Central directory of all people you've ever verified. Useful for re-verification, fraud investigation, and compliance audits.

Esempio

Search "Jane Smith" → see all cases for that person → click through to view detailed profile with verification history, risk signals, and address timeline.

Batch Upload

Descrizione

Create multiple verification cases at once by uploading a CSV file. The system validates every row, flags errors, checks for duplicates against existing cases, and processes valid rows in parallel.

Impatto

Essential for high-volume onboarding. Process hundreds of verifications from a single file instead of creating cases one by one.

Esempio

Prepare CSV with columns: name, line1, city, postalCode, countryCode (required) + email, phone, reference (optional) → Upload → Validate → Process.

Suggerimenti Pro

• Download the CSV template first for the correct column format.
• Always validate before uploading to catch formatting errors.

Verification Packages

Basic Package

Descrizione

Digital-only verification using email OTP. An 8-character OTP code is sent to the subject's email address. The subject enters the code to verify email ownership. Fastest completion time (~5 minutes).

Impatto

Assurance level: Verified (Digital). Suitable for low-risk onboarding where email confirmation is sufficient and postal proof is not required by regulation.

Esempio

Layers enabled: Email (required). Subject receives email with OTP "A3K9X2MF" → enters code → case completes with "Verified (Digital)" assurance.

Benchmark

Completion time: 2-5 minutes. Success rate: 85-95%. Cost: lowest (no postal dispatch).

Suggerimenti Pro

• Best for: initial client onboarding, newsletter signups, low-risk KYC.
• Can be stepped up to postal automatically if risk score is high.

Standard Package

Descrizione

Two-factor digital verification using both email OTP (8-character code) and SMS OTP (6-digit code). Both channels must be verified for the case to complete.

Impatto

Assurance level: Verified (Digital). Provides dual-channel digital confirmation. Stronger than Basic but still does not prove physical address possession.

Esempio

Layers enabled: Email (required), SMS (required). Subject receives email OTP "A3K9X2MF" + SMS OTP "482917" → enters both → case completes.

Benchmark

Completion time: 3-10 minutes. Success rate: 80-90%. Cost: low (email + SMS, no postal).

Suggerimenti Pro

• Best for: standard KYC, regulated onboarding where dual digital verification is acceptable.
• Requires valid phone number with country prefix (e.g. +44 for UK).

Enhanced Package

Descrizione

Full postal + digital verification. Sends email OTP and dispatches a tracked physical letter with a unique 10-character postal OTP and QR code. SMS is optional. The postal letter proves physical possession of the address.

Impatto

Assurance level: Verified (Digital + Postal). Meets the strictest FCA, SRA, and HMRC requirements for proof of address. The gold standard for regulated industries.

Esempio

Layers enabled: Email (required), SMS (optional), Postal (required). Subject verifies email → letter arrives in 1-7 days → subject enters postal OTP → case completes.

Benchmark

Completion time: 3-10 days (depends on postal delivery). Success rate: 70-85%. Cost: medium (includes postal dispatch).

Postal verification adds cost and time. Only use when regulatory requirements demand physical address proof.

Suggerimenti Pro

• Best for: law firms, financial services, accountancy firms, property transactions.
• The QR code on the letter allows subjects to scan and verify instantly.

Maximum Package

Descrizione

Highest assurance. All four verification layers: email OTP (8-char), SMS OTP (6-digit), postal letter (10-char OTP + QR code), AND GPS geo-location capture when entering the postal code. Proves both mail receipt AND physical presence at the address.

Impatto

Assurance level: Verified (Digital + Postal) with geo confirmation. The strongest possible proof that the subject physically resides at the claimed address.

Esempio

Layers: Email (required), SMS (required), Postal (required), Geo (required, 200m radius). Subject verifies email + SMS → receives letter → enters postal OTP while GPS confirms they're at the address.

Benchmark

Completion time: 3-10 days. Success rate: 60-75% (geo may fail if subject declines location). Cost: highest.

Some subjects may decline location permissions. Configure geo as optional if you don't want to block these cases.

Suggerimenti Pro

• Best for: high-risk cases, AML/CFT compliance, fraud-prone scenarios, high-value property transactions.
• Geo verification requires the subject to allow browser location access.

Default Package

Descrizione

The bundle marked as "Default" is automatically used when cases are created via the API without specifying a bundleId. Only one bundle can be the default at any time.

Impatto

Controls the verification flow for API-created cases and any cases where the caseworker doesn't explicitly select a bundle.

Esempio

Set "Enhanced" as default → all API-created cases automatically use email + postal verification. Change to "Basic" → API cases only use email.

Suggerimenti Pro

• Set the default to your most commonly used package.
• You can always override the default by specifying bundleId in the API request.

Platform Package

Descrizione

Pre-configured verification packages provided by Postal.id: Basic, Standard, Enhanced, and Maximum. These cannot be edited or deleted but can be set as the default.

Impatto

Platform packages cover the most common verification scenarios. Create custom packages only if you need non-standard layer combinations.

Esempio

Platform packages: Basic (email only), Standard (email + SMS), Enhanced (email + SMS + postal), Maximum (all 4 layers). All are always available.

Recipients

Recipient

Descrizione

A "recipient" (also called "subject") is the person whose address is being verified. Each recipient may have multiple verification cases if they've been verified at different addresses or re-verified over time.

Impatto

Click any recipient to view their full profile including verification history, risk signals, address changes, and verification method success rates.

Esempio

Recipient "Jane Smith" has 3 cases: 1 completed (London address), 1 active (Manchester address), 1 failed (disposable email detected).

Latest Status

Descrizione

Shows the status of the most recent verification case for this recipient. Reflects where they are in the verification flow right now.

Impatto

Quick indicator of whether the recipient's most recent verification is complete, in progress, or has issues.

Esempio

COMPLETE (green): latest case fully verified. POSTAL_DISPATCHED (amber): letter sent, awaiting delivery. FAILED (red): latest case failed.

Cases Count

Descrizione

Total number of verification cases ever created for this recipient across all addresses and time periods. Includes active, completed, failed, and expired cases.

Impatto

Multiple cases may exist if the recipient moved, if a previous case expired, or if periodic re-verification is required.

Esempio

3 cases: means this person has been through the verification process 3 separate times (possibly at different addresses).

Risk Score

Descrizione

Aggregated risk percentage based on all risk signals detected for this recipient across all their cases. Combines ghost address, mail forwarding, address velocity, disposable email, and cross-tenant signals.

Impatto

Red (>70%): High risk — investigate immediately. Amber (40-70%): Moderate risk — review recommended. Green (<40%): Low risk — no immediate action needed.

Esempio

15%: Low risk (no signals). 52%: Medium (disposable email detected). 85%: High (ghost address + cross-tenant + velocity).

Formula

Weighted average of all risk signals across all cases for this recipient.

Suggerimenti Pro

• Click through to the recipient profile for detailed signal breakdown.
• High-risk recipients should have their completed cases reviewed.

Recipient Search

Descrizione

Search across name, email, phone number, and address fields. Filter by case status to find recipients at a specific verification stage. Sort by newest, oldest, name alphabetically, or most cases.

Impatto

Quickly find specific recipients or identify groups of recipients in a particular state.

Esempio

Search "Manchester" → shows all recipients with Manchester addresses. Filter "FAILED" → shows recipients whose latest case failed.

Recipient Profile

Total Cases (Recipient)

Descrizione

All verification cases ever created for this person, regardless of outcome. Includes active cases in progress, successfully completed cases, failed cases, and expired cases.

Impatto

A high case count may indicate re-verifications (normal) or repeated failed attempts (investigate).

Esempio

5 total cases: 3 completed, 1 active, 1 expired.

Active Cases

Descrizione

Cases currently in progress — not yet reached a terminal state (COMPLETE, FAILED, or EXPIRED). These are cases where the subject still needs to complete one or more verification steps.

Impatto

Active cases require monitoring. If a case stays active for too long, the subject may need a reminder.

Esempio

2 active cases: one at DIGITAL_PENDING (email OTP sent, awaiting entry), one at POSTAL_DISPATCHED (letter sent, awaiting delivery).

Contact Details

Descrizione

The subject's name, email address, and phone number as provided when the case was created. "First Seen" shows when this person was first added to the system. "Latest Status" shows their most recent case state.

Impatto

Contact information is used for email OTP delivery (email) and SMS OTP delivery (phone). Tags help categorise recipients.

Esempio

Name: Jane Smith. Email: jane@example.com. Phone: +44 7700 900123. First Seen: 15 Jan 2026. Tags: VIP, Priority.

Current Address

Descrizione

The most recent address provided for verification. "Verified" with a date means postal verification was successfully completed for this address. Ghost Address and Forwarding badges indicate risk flags detected during address validation.

Impatto

The current address is the one used for the latest or active verification case. Previous addresses appear in Address History.

Esempio

12 Baker Street, London, NW1 6XE, GB. Verified: 20 Feb 2026. Badges: none (clean address).

Ghost Address badge means this is a known virtual office or mail forwarding address. Forwarding badge means mail may be redirected to a different location.

Verification Methods

Descrizione

Breakdown of how many email, SMS, and postal OTPs were sent to this recipient and how many were successfully verified. The progress bar shows the success rate for each channel.

Impatto

Identifies which verification channels work best for this recipient. Low success on a channel may indicate delivery issues.

Esempio

Email: 3 sent, 3 verified (100%). SMS: 2 sent, 2 verified (100%). Postal: 2 sent, 1 verified (50%). Green bar (≥80%), Amber (50-79%), Red (<50%).

Suggerimenti Pro

• Low postal success may indicate address issues or subject disengagement.
• Low email success may indicate spam filtering or invalid email.

Address History

Descrizione

Chronological list of all addresses this person has been verified at across all their cases. Each entry shows the full address, country flag, and whether verification was completed.

Impatto

Useful for detecting frequent movers, address fraud patterns, or confirming legitimate address changes over time.

Esempio

1. 12 Baker Street, London — Verified 20 Feb 2026. 2. 45 Oxford Road, Manchester — Verified 15 Nov 2025. 3. PO Box 123, Bristol (Ghost badge) — Not verified.

Case History

Descrizione

All verification cases for this recipient in reverse chronological order. Click any Case ID to view the full case details including timeline, risk assessment, and evidence pack.

Impatto

Complete audit trail of every verification attempt for this person. Useful for compliance reviews and dispute resolution.

Esempio

Case a1b2c3d4: COMPLETE, Verified (Digital + Postal), 12 Baker Street, 20 Feb 2026. Case e5f6g7h8: FAILED, --, 45 Oxford Road, 15 Nov 2025.

Create Case

Subject

Descrizione

The person whose address is being verified. "Subject" is Postal.id terminology for the end-person — not your employee or team member. Provide their full legal name as it would appear at the address.

Impatto

The subject's name is printed on the postal letter and included in the evidence pack. Use the correct legal name for compliance purposes.

Esempio

Input: "Jane Elizabeth Smith" (full legal name). Avoid nicknames or abbreviations unless that's the name at the address.

Subject Contact

Descrizione

Email is used for email OTP delivery (8-character code). Phone (with country prefix like +44 for UK, +1 for US) is used for SMS OTP delivery (6-digit code). Both are optional but required if the selected verification bundle includes email/SMS layers.

Impatto

Without email, the email OTP layer cannot function. Without phone, the SMS OTP layer cannot function. Postal verification does not require either.

Esempio

Email: jane.smith@example.com. Phone: +447700900123 (UK mobile) or +12125551234 (US). Note: phone must include country prefix.

Suggerimenti Pro

• Validate email addresses before entry — disposable emails trigger risk signals.
• Mobile numbers only — landlines cannot receive SMS.

Consent

Descrizione

Legal requirement (GDPR/data protection): you must confirm the subject has given consent for address verification before creating a case. This checkbox is mandatory — the case cannot be created without it.

Impatto

Ensures compliance with data protection regulations. The consent status is recorded in the audit trail and included in the evidence pack.

Esempio

Check the box to confirm: "Subject has given consent for address verification". Unchecked = "Create Case" button is disabled.

Creating cases without genuine subject consent may violate GDPR and expose your organisation to regulatory penalties.

Address Validation

Descrizione

After entering an address, the system automatically validates it for deliverability. Checks include: valid postal code format, known ghost/virtual office addresses, active mail forwarding/redirection services, and address standardisation.

Impatto

Pre-dispatch validation prevents wasted postal costs on undeliverable addresses and flags risk signals early.

Esempio

Enter "12 Baker St, London" → validation returns: Deliverable (green tick), standardised to "12 Baker Street, London, NW1 6XE". Or: "71-75 Shelton Street" → Ghost Address warning (orange).

Suggerimenti Pro

• Accept suggested address corrections for better deliverability.
• Ghost address warnings don't block case creation but do increase the risk score.

Verification Package Selection

Descrizione

Choose which verification bundle to use for this case. Each package defines which layers (email, SMS, postal, geo) are enabled and whether they're required or optional. "Default" badge means this is the bundle used for API-created cases. "Platform" badge means it's provided by Postal.id.

Impatto

The selected package determines the verification flow, timeline, cost, and resulting assurance level.

Esempio

Select "Enhanced" → email OTP sent immediately, postal letter dispatched within 1 hour. Estimated postal cost shown below (e.g. £1.20 for UK letter).

Suggerimenti Pro

• Click the ? next to each package name (Basic, Standard, Enhanced, Maximum) for detailed explanations.
• Required layers must pass; optional layers enhance assurance without blocking.

Client Reference

Descrizione

Optional internal reference for your own records. Use your matter ID, client number, file reference, or any identifier that helps you match this verification case to your internal systems.

Impatto

Searchable in the case list and included in webhook payloads and evidence packs. Makes it easy to cross-reference with your practice management software.

Esempio

Examples: "MATTER-2024-001", "CLT-4521", "AML-REF-789", "Property-Sale-42-High-St". Any format up to 100 characters.