Aggregated service of government and public records, background records, and public professional profiles. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results. ## Coverage * **Coverage:** \~ 90% * **Country:** United States * **Service ID:** `usa_states_residential` * **Data domain:** Address * **Category:** Residential ## Inputs | Field | Required | Example | | --------------------- | -------: | ---------------------- | | `first_name` | Yes | `John` | | `last_name` | Yes | `Doe` | | `date_of_birth` | Yes | `1990-01-01` | | `address.street_1` | Yes | `123 Sample Street` | | `address.postal_code` | Yes | `10001` | | `phone` | No | `+15550101000` | | `ssn` | No | `123456789` | | `email` | No | `john.doe@example.com` | | `address.street_2` | No | `Unit 4` | | `address.city` | No | `Sample City` | | `address.region` | No | `Sample State` | | `vendor_data` | No | `user-1234` | * **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code` * **Optional inputs:** `phone`, `ssn`, `email`, `address.street_2`, `address.city`, `address.region`, `vendor_data` * **Consent:** Not required * **Workflow availability:** Available in workflow * **Coverage:** \~ 90% * **Price:** \$0.60 per successful query ## Body parameters ISO 3166-1 alpha-3 country code for this database service. Example: `USA` Array containing this service ID. Pinning the service keeps the request scoped to this exact database. Example: `usa_states_residential` Given name to validate. Example: `John` Family name to validate. Example: `Doe` Date of birth in `YYYY-MM-DD` format. Example: `1990-01-01` Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended. Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}` Phone number in international format. Example: `+15550101000` `ssn` value required by this database service. Example: `123456789` Email address. Example: `john.doe@example.com` Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise. Example: `user-1234` ## Input rules & validation notes * US Social Security Number (9 digits, with optional dashes) * `ssn` must match `(?:\d{9}|\d{3}-\d{2}-\d{4})`. * For `ssn`, send the full 9-digit SSN/ITIN (dashes optional). Unlike the US Credit Bureau and Financial Services checks, this service does not accept the last-4-digits form. * For address services, send structured address fields instead of a single `address` string when possible. * `address.street_1` is the street address, including street number and street type. * `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it. * `address.city` is city, suburb, district, locality, or neighborhood. * `address.region` is state, province, region, or town. * `address.postal_code` is postcode or postal code. * Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged. ## How to call it ```bash cURL theme={null} curl -X POST "https://verification.didit.me/v3/database-validation/" \ -H "x-api-key: YOUR_API_KEY" \ -F "issuing_state=USA" \ -F "services=usa_states_residential" \ -F "vendor_data=user-1234" \ -F "first_name=John" \ -F "last_name=Doe" \ -F "date_of_birth=1990-01-01" \ -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}' ``` Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it. **`MATCH`** — The registry confirmed the identity and every checked field matched. ```json 200 OK — MATCH theme={null} { "request_id": "req_01H…", "status": "Approved", "issuing_state": "USA", "match_type": "full_match", "validations": [ { "outcome_code": "MATCH", "service_id": "usa_states_residential", "service_name": "United States of America - United States Residential", "source_data": { "address": "123 Sample Street", "address_match_score": "1.000", "city": "Sample City", "date_of_birth": "1990-01-01", "first_name": "John", "full_name": "John Doe", "last_name": "Doe", "name_match_score": "1.000", "postal_code": "10001", "state": "Sample State", "street": "sample_value", "verifications": { "address": true, "date_of_birth": true, "full_name": true } }, "validation": { "address": "full_match", "date_of_birth": "full_match", "full_name": "full_match" } } ] } ``` **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match. ```json 200 OK — PARTIAL_MATCH theme={null} { "request_id": "req_01H…", "status": "In Review", "issuing_state": "USA", "match_type": "partial_match", "validations": [ { "outcome_code": "PARTIAL_MATCH", "service_id": "usa_states_residential", "service_name": "United States of America - United States Residential", "source_data": { "address": "123 Sample Street", "address_match_score": "1.000", "city": "Sample City", "date_of_birth": "1990-01-01", "first_name": "John", "full_name": "John Doe", "last_name": "Doe", "name_match_score": "1.000", "postal_code": "10001", "state": "Sample State", "street": "sample_value", "verifications": { "address": true, "date_of_birth": true, "full_name": false } }, "validation": { "address": "full_match", "date_of_birth": "full_match", "full_name": "no_match" } } ] } ``` **`NO_MATCH`** — The registry returned no match for the submitted data. ```json 200 OK — NO_MATCH theme={null} { "request_id": "req_01H…", "status": "Declined", "issuing_state": "USA", "match_type": "no_match", "validations": [ { "outcome_code": "NO_MATCH", "service_id": "usa_states_residential", "service_name": "United States of America - United States Residential", "source_data": { "address": "NO_MATCH", "date_of_birth": "NO_MATCH", "full_name": "NO_MATCH" }, "validation": { "address": "no_match", "date_of_birth": "no_match", "full_name": "no_match" } } ] } ``` ## Returned data The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `usa_states_residential` currently documents this normalized shape: * `address` * `address_match_score` * `city` * `date_of_birth` * `first_name` * `full_name` * `last_name` * `name_match_score` * `postal_code` * `state` * `street` ## Pricing & SLAs United States of America - United States Residential queries are billed only when Didit receives a conclusive result from the validation source. * **Per-call price:** \$0.60 USD. * **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source. * **Latency:** typical p95 \< 2 s. * **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset. ## Continue reading * [United States Database Validation overview](/api-reference/database-validation/united-states) * [Database Validation overview](/core-technology/database-validation/overview) * [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)