> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.middesk.com/reference/address/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server. # Address object > Lists the contents of an address object. This page describes the `address` object, which includes geocoded address data for businesses along with risk indicators (like property type, deliverability, and location frequency) and supplementary data from sources like FMCSA, NPI registry, Form 5500, professional licenses, and tax-exempt organizations. A business can have one or many addresses. Middesk geocodes addresses in all 50 American states, DC, five American territories including AS, GU, MP, PR and VI, Palau, and the Marshall Islands. Middesk also returns a variety of details that can be helpful for compliance, fraud, and underwriting decisions. **`Example JSON response`** ```json title="Example JSON response" { "object": "address", "id": "f15e4ce9-109b-4a88-9540-5890ca511c2d", "address_line1": "2180 Bryant St Ste 210", "address_line2": null, "city": "San Francisco", "state": "CA", "postal_code": "94110-2141", "full_address": "2180 Bryant St Ste 210, San Francisco, CA 94110-2141", "submitted": false, "latitude": 37.75938, "longitude": -122.40994, "property_type": "commercial", "cmra": false, "deliverable": true, "deliverability_analysis": null, "street_view_available": true, "is_registered_agent": false, "registered_agent_name": null, "location_count": 1, "labels": [], "business_id": "80556c5c-74d1-4e9c-91b8-9fe149338bef", "rating": { "indicators": [ { "type": "valid_us_address", "name": "Valid US address", "rating": "positive", "value": "valid", "description": "Valid" }, { "type": "deliverability", "name": "Deliverability", "rating": "positive", "value": "deliverable", "description": "Deliverable" }, { "type": "geographical_location", "name": "Geographical location", "rating": "positive", "value": "us", "description": "US" }, { "type": "registered_agent", "name": "Registered agent", "rating": "positive", "value": "not_registered_agent", "description": "Not a registered agent" }, { "type": "private_mailbox", "name": "Private mailbox", "rating": "positive", "value": "not_private_mailbox", "description": "Not a private mailbox" }, { "type": "location_frequency", "name": "Location frequency", "rating": "low", "value": "2-20_businesses", "description": "2–20 businesses use this location" }, { "type": "property_type", "name": "Property type", "rating": "positive", "value": "commercial", "description": "Commercial" }, { "type": "virtual_address", "name": "Virtual address", "rating": "positive", "value": "not_virtual_address", "description": "Not a virtual address" } ], "risk_rating": "low" }, "sources": [ { "id": "f074244d-5cf3-4703-950a-73a7d54ee555", "type": "registration", "metadata": { "file_number": "C4221590", "state": "CA", "labels": ["primary"] } }, { "id": "02c1dcb2-6405-478b-9b94-78c7cbea99", "type": "website", "metadata": { "url": "https://www.middesk.com" } } ], "created_at": "2019-01-30T23:49:01.100Z", "updated_at": "2019-01-30T23:49:01.100Z" } ``` ## Address attributes | Attribute | Type | Description | | ---------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `object` | string | The object type. Always `address`. | | `id` | string (uuid) | Unique identifier for the address record. | | `address_line1` | string \| null | The street address of the business. | | `address_line2` | string \| null | The second address line typically used for apartment or suite numbers. | | `city` | string \| null | The city of the business. | | `state` | string \| null | The state of the business. Two-letter state abbreviation. | | `postal_code` | string \| null | The postal code of the business. | | `full_address` | string | Display version of address. | | `submitted` | boolean | Whether the address was submitted by the user (`true`) or discovered by Middesk (`false`). | | `latitude` | float \| null | The latitude of the business address. | | `longitude` | float \| null | The longitude of the business address. | | `property_type` | string \| null | The type of property known to be located at this address. Possible values are `commercial` and `residential`. | | `cmra` | boolean | Indicates when an address is a Commercial Mail Receiving Agency (CMRA). | | `deliverable` | boolean | A summary of the deliverability of the address. | | `deliverability_analysis` | object \| null | Detailed deliverability analysis for the address. | | `deliverability_analysis.message` | string | A human-readable deliverability message. | | `deliverability_analysis.sub_type` | string | Deliverability category. One of `Deliverable`, `Undeliverable`, or `Unknown`. | | `deliverability_analysis.sub_key` | string | Deliverability key. One of `deliverable`, `undeliverable`, or `unknown`. | | `street_view_available` | boolean \| null | Whether a Google Street View image is available for the address. | | `is_registered_agent` | boolean \| null | Whether the address is a Registered Agent. | | `registered_agent_name` | string \| null | The name of the registered agent at this address, if applicable. | | `location_count` | integer \| null | Frequency of location use across businesses in the U.S. | | `labels` | string\[] | A list of labels associated with the address. | | `business_id` | string (uuid) | The ID of the business this address belongs to. | | `sources` | object\[] | A nested object containing the source details for each source where a given address was identified. | | `sources[].id` | string (uuid) | Unique identifier for the source. | | `sources[].type` | string | The source type for a given address. Possible values are:- `registration`: The address was found based on government registration records - `website`: The address was found on the company website - `profile`: The address was found on the company's facebook or google profile - `historical_registration`: The address was found on a past version of a matching government registration record | | `sources[].metadata` | object | A nested object containing the specific details for each address source. | | `sources[].metadata.file_number` | string | The unique identifier of the Secretary of State record where that address was found. | | `sources[].metadata.state` | string | The specific state where that address was found. | | `sources[].metadata.website` | string | The domain where that address was found. | | `sources[].metadata.labels` | string\[] | A list containing the address labels from each source. | | `created_at` | timestamp | Timestamp of when the address was created. | | `updated_at` | timestamp | Timestamp of when the address was last updated. | | `rating` | object | An object containing the overall risk rating for the address and the indicators that informed this rating. | | `rating.risk_rating` | string | The overall risk rating Middesk assigns to the address. Possible values are `high`, `moderate`, `low`, and `not_available`. | | `rating.indicators` | object\[] | A list of objects containing all of the risk indicators for the address. | | `rating.indicators[].type` | string | The type of the indicator. Possible values are `valid_us_address`, `geographical_location`, `deliverability`, `location_frequency`, `registered_agent`, `private_mailbox`, and `property_type`. | | `rating.indicators[].name` | string | A readable name for the indicator. Possible values are `Valid US address`, `Geographical location`, `Deliverability`, `Location frequency`, `Registered agent`, `Private mailbox`, and `Property type`. | | `rating.indicators[].rating` | string | The overall score the indicator receives. Possible values are `positive`, `negative`, and `neutral`. | | `rating.indicators[].value` | string | The value that was found for the indicator. These are specific per type, see the table below in the Address risk section to learn more. | | `rating.indicators[].description` | string | A readable version of the indicator value. | ## FMCSA registrations As a supplementary data point for business address verification, Middesk adds the ability to search and match against the FMCSA (Federal Motor Carrier Safety Administration). FMCSA data appears in the `sources` field when the business address can be found in their database. **`Example JSON response`** ```json title="Example JSON response" { ... "fmcsa_registrations": [{ "id": "b3638510-87ec-425e-bdaa-ad6e48dec871", "object": "fmcsa_registration", "dot_number": "2948750", "legal_name": "John Doe", "dba_name": "John Doe's Donuts", "addresses": [ "123 Street, HOUSTON, TX 77008" ], "source": "" }], "addresses": [{ "object": "address", "address_line1": "100 Blvd Unit 123", "address_line2": null, "city": "Atlanta", "state": "GA", "postal_code": "30341-2872", "full_address": "5100 Blvd Unit 123", "submitted": true, "id": "7611e1be-6dc8-4fef-84a1-29027f45d6a8", "latitude": 33.88864519592745, "longitude": -84.31442417935, "property_type": "RESIDENTIAL", "deliverable": true, "deliverability_analysis": null, "street_view_available": true, "labels": [], "is_registered_agent": false, "location_count": 1, "created_at": "2022-07-15T13:57:25.802Z", "updated_at": "2022-07-15T13:57:26.660Z", "registered_agent_name": null, "cmra": null, "business_id": "b3638510-87ec-425e-bdaa-ad6e48dec871", "sources": [{ "id": "be7afda5-a37c-4e30-baef-22a97c50366b", "type": "fmcsa_registration", "metadata": { "dot_number": "2948750", "labels": ["mailing", "physical"] } }] }] } ``` ## NPPES NPI Registry data As a supplementary data point for business address verification, Middesk adds the ability to search and match against data from the National Provider Identifier (NPI) registry, which HIPAA-covered entities are required to register with. NPI registry data appears in the `sources` field when found. **`Example JSON response`** ```json title="Example JSON response" "addresses": [{ "object": "address", "address_line1": "85 Second Street", "address_line2": null, "city": "San Francisco", "state": "CA", "postal_code": "94105-3459", "full_address": "85 Second Street, San Francisco, CA 94105-3459", "submitted": true, "id": "f15e4ce9-109b-4a88-9540-5890ca511c2d", "latitude": 39.09271, "longitude": -104.87254, "property_type": "COMMERCIAL", "deliverable": true, "deliverability_analysis": null, "street_view_available": null, "is_registered_agent": false, "location_count": 1, "labels": [], "created_at": "2023-02-14T21:12:45.085Z", "updated_at": "2023-02-14T21:12:45.085Z", "registered_agent_name": null, "cmra": null, "business_id": "80556c5c-74d1-4e9c-91b8-9fe149338bef", "sources": [ { "id": "45fdfb94-7b45-402e-a3a6-2558b89fddac", "type": "npi_record", "metadata": { "id": "1033531256", "labels": ["mailing", "physical"], "source_data": [ { "name": "Business Name", "value": "Middesk Inc" }, { "name": "National Provider Identifier (NPI)", "value": "1234567890" }, { "name": "Primary Practice Address", "value": "85 Second Street, San Francisco, CA 94105-3459" }, { "name": "Mailing Address", "value": "85 Second Street, San Francisco, CA 94105-3459" }, { "name": "Secondary Practice Address", "value": [] }, { "name": "Enumeration Date", "value": "2014-01-07" } ], "source_data_link": "https://npiregistry.cms.hhs.gov/provider-view/1234567890" } } ] }, ... ] ``` ## Form 5500 data As a supplementary data point for business address verification, Middesk adds the ability to search and match against data from the US Department of Labor Form 5500 datasets. Form 5500 registry data appears in the `sources` field when found. **`Example JSON response`** ```json title="Example JSON response" "addresses": [{ "object": "address", "address_line1": "85 Second Street", "address_line2": null, "city": "San Francisco", "state": "CA", "postal_code": "94105-3459", "full_address": "85 Second Street, San Francisco, CA 94105-3459", "submitted": true, "id": "f15e4ce9-109b-4a88-9540-5890ca511c2d", "latitude": 39.09271, "longitude": -104.87254, "property_type": "COMMERCIAL", "deliverable": true, "deliverability_analysis": null, "street_view_available": null, "is_registered_agent": false, "location_count": 1, "labels": [], "created_at": "2023-02-14T21:12:45.085Z", "updated_at": "2023-02-14T21:12:45.085Z", "registered_agent_name": null, "cmra": null, "business_id": "80556c5c-74d1-4e9c-91b8-9fe149338bef", "sources": [ { "id": "45fdfb94-7b45-402e-a3a6-2558b89fddac", "type": "form_5500", "metadata": { "ack_id": "20240621220037NAL0002237923047", "plan_year": 2023 } } ] }, ... ] ``` ## Professional license data As a supplementary data point for business address verification, Middesk adds the ability to search and match against professional license data. This includes construction licenses, medical licenses, cosmetology licenses, auto repair licenses, and real estate licenses. The possible license types are `construction`, `medical`, `cosmetology`, `real_estate`, and `auto_repair`. **`Example JSON response`** ```json title="Example JSON response" "addresses": [{ "object": "address", "address_line1": "85 Second Street", "address_line2": null, "city": "San Francisco", "state": "CA", "postal_code": "94105-3459", "full_address": "85 Second Street, San Francisco, CA 94105-3459", "submitted": true, "id": "f15e4ce9-109b-4a88-9540-5890ca511c2d", "latitude": 39.09271, "longitude": -104.87254, "property_type": "COMMERCIAL", "deliverable": true, "deliverability_analysis": null, "street_view_available": null, "is_registered_agent": false, "location_count": 1, "labels": [], "created_at": "2023-02-14T21:12:45.085Z", "updated_at": "2023-02-14T21:12:45.085Z", "registered_agent_name": null, "cmra": null, "business_id": "80556c5c-74d1-4e9c-91b8-9fe149338bef", "sources": [ { "id": "45fdfb94-7b45-402e-a3a6-2558b89fddac", "type": "form_5500", "license_number": "123455", "license_type": "cosmetology", "state": "CA", "status": "active" } ] }, ... ] ``` ## Tax exempt organization data As a supplementary data point for business address verification, Middesk matches against tax exempt organization data. This includes charitable organizations, churches and religious organizations, private foundations, political organizations, and other non-profits. When a tax exempt organization is found, data appears in the `sources` field. **`Example JSON response`** ```json title="Example JSON response" "addresses": [ { "object": "address", "address_line1": "2478 Roseberry Ln", "address_line2": null, "city": "Grayson", "state": "GA", "postal_code": "30017-1554", "full_address": "2478 Roseberry Ln, Grayson, GA 30017-1554", "submitted": true, "id": "38d7db40-8596-013d-7bba-6ea6aac5eb9c", "latitude": 33.87024939590285, "longitude": -83.96988736080574, "property_type": "RESIDENTIAL", "deliverable": true, "deliverability_analysis": null, "street_view_available": true, "labels": [], "created_at": "2024-11-15T13:15:08.545Z", "updated_at": "2024-11-15T13:15:16.469Z", "registered_agent_name": null, "cmra": false, "business_id": "3ef53f50-8596-013d-7bba-6ea6aac5eb9c", "location_count": 2, "is_registered_agent": false, "sources": [ { "id": "5b6a7370-8596-013d-7bba-6ea6aac5eb9c", "type": "tax_exempt_organization", "metadata": { "labels": [ "mailing" ] } } ] }, ... ] ``` ## Address risk You can leverage address risk to determine an overall risk rating of `High`, `Moderate`, `Low`, or `Not Available` for each of the business's addresses (both known and submitted). Going one step further, you can inspect each risk indicator used to determine the overall risk rating and optionally, derive an outcome based on your own defined heuristics. Here's a look at the current risk indicators and their respective keys with the address object. Each indicator includes a rating field of its own, yielding a `positive`, `neutral`, or `negative` rating for each category type. If the indicator cannot be accurately determined for any reason, the indicator is absent from the payload. | Risk indicator | Description | Key | | --------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------- | | Valid US address | An evaluation of whether the address is a valid address in the United State. | `valid_us_address` | | Geographical location | An evaluation of whether the location of the address is in the US, international, or is unknown. | `geographical_location` | | Property type | An evaluation of whether the address is residential or commercial. | `property_type` | | Deliverability | An evaluation of whether the address is deliverable, undeliverable, or vacant. | `deliverability` | | Private mailbox | An evaluation of if the address is one of the types of private mailboxes, including PO box and CMRA. | `private_mailbox` | | Registered agent | An evaluation of if the address is a registered agent address rather than the business's actual operating address. | `registered_agent` | | Location frequency | An evaluation of how many other businesses were found by Middesk using the same address. | `location_frequency` | | Virtual address | An evaluation of whether the address is the location of a virtual address provider. | `virtual_address` | > **Get a demo** > > Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access. > Lists the contents of an address object.