Middesk APIBusiness VerificationObject reference

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
1{
2  "object": "address",
3  "address_line1": "2180 Bryant St Ste 210",
4  "address_line2": null,
5  "city": "San Francisco",
6  "state": "CA",
7  "postal_code": "94110-2141",
8  "full_address": "2180 Bryant St Ste 210, San Francisco, CA 94110-2141",
9  "latitude": 37.75938,
10  "longitude": -122.40994,
11  "property_type": "COMMERCIAL",
12  "cmra": false,
13  "deliverable": true,
14  "is_registered_agent": false,
15  "location_count": 1,
16  "rating": {
17    "indicators": [
18      {
19        "type": "valid_us_address",
20        "name": "Valid US address",
21        "rating": "positive",
22        "value": "valid",
23        "description": "Valid"
24      },
25      {
26        "type": "deliverability",
27        "name": "Deliverability",
28        "rating": "positive",
29        "value": "deliverable",
30        "description": "Deliverable"
31      },
32      {
33        "type": "geographical_location",
34        "name": "Geographical location",
35        "rating": "positive",
36        "value": "us",
37        "description": "US"
38      },
39      {
40        "type": "registered_agent",
41        "name": "Registered agent",
42        "rating": "positive",
43        "value": "not_registered_agent",
44        "description": "Not a registered agent"
45      },
46      {
47        "type": "private_mailbox",
48        "name": "Private mailbox",
49        "rating": "positive",
50        "value": "not_private_mailbox",
51        "description": "Not a private mailbox"
52      },
53      {
54        "type": "location_frequency",
55        "name": "Location frequency",
56        "rating": "low",
57        "value": "2-20_businesses",
58        "description": "2–20 businesses use this location"
59      },
60      {
61        "type": "property_type",
62        "name": "Property type",
63        "rating": "positive",
64        "value": "commercial",
65        "description": "Commercial"
66      },
67      {
68        "type": "virtual_address",
69        "name": "Virtual address",
70        "rating": "positive",
71        "value": "not_virtual_address",
72        "description": "Not a virtual address"
73      }
74    ],
75    "risk_rating": "low"
76  },
77  "sources": [
78    {
79      "id": "f074244d-5cf3-4703-950a-73a7d54ee555",
80      "type": "registration",
81      "metadata": {
82        "file_number": "C4221590",
83        "state": "CA",
84        "labels": ["primary"]
85      }
86    },
87    {
88      "id": "02c1dcb2-6405-478b-9b94-78c7cbea99",
89      "type": "website",
90      "metadata": {
91        "url": "https://www.middesk.com"
92      }
93    }
94  ],
95  "created_at": "2019-01-30T23:49:01.100Z",
96  "updated_at": "2019-01-30T23:49:01.100Z"
97}

Address attributes

AttributeTypeDescription
address_line1stringThe street address of the business.
address_line2stringThe second address line typically used for apartment or suite numbers.
citystringThe city of the business.
statestringThe state of the business.
postal_codestringThe postal code of the business.
full_addressstringDisplay version of address.
latitudefloatThe latitude of the business address.
longitudefloatThe longitude of the business address.
property_typestringThe type of property known to be located at this address. Possible values are COMMERCIALand RESIDENTIAL.
cmrabooleanIndicates when an address is a Commercial Mail Receiving Agency (CMRA).
deliverablebooleanA summary of the deliverability of the address. Value is Unknown if deliverability is unknown.
is_registered_agentbooleanWhether the address is a Registered Agent.
location_countfloatFrequency of location us across businesses in the U.S.
sourcesobject []A nested object containing the source details for each source where a given address was identified.
sources[].typestringThe 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[].metadataobject []A nested object containing the specific details for each address source.
sources[].metadata.file_numberstringThe unique identifier of the Secretary of State record where that address was found.
sources[].metadata.statestringThe specific state where that address was found.
sources[].metadata.websitestringThe domain where that address was found.
sources[].metadata.labelsstring[]A list containing the address labels from each source.
created_attimestamp
updated_attimestamp
ratingobjectAn object containing the overall risk rating for the address and the indicators that informed this rating.
rating.risk_ratingstringThe overall risk rating that we have found the address to have. Possible values are high, moderate, low, and not_available.
rating.indicatorsobject[]A list of objects containing all of the risk indicators for the address.
rating.indicators[].typestringThe type of the indicator. Possible values are valid_us_address, geographical_location, deliverability, location_frequency, registered_agent, private_mailbox, and property_type.
rating.indicators[].namestringA 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[].ratingstringThe overall score the indicator receives. Possible values are positive, negative, and neutral.
rating.indicators[].valuestringThe 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[].descriptionstringA 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
1{
2  ...
3  "fmcsa_registrations": [{
4    "id": "b3638510-87ec-425e-bdaa-ad6e48dec871",
5    "object": "fmcsa_registration",
6    "dot_number": "2948750",
7    "legal_name": "John Doe",
8    "dba_name": "John Doe's Donuts",
9    "addresses": [
10      "123 Street, HOUSTON, TX 77008"
11    ],
12    "source": "<link>"
13  }],
14  "addresses": [{
15    "object": "address",
16    "address_line1": "100 Blvd Unit 123",
17    "address_line2": null,
18    "city": "Atlanta",
19    "state": "GA",
20    "postal_code": "30341-2872",
21    "full_address": "5100 Blvd Unit 123",
22    "submitted": true,
23    "id": "7611e1be-6dc8-4fef-84a1-29027f45d6a8",
24    "latitude": 33.88864519592745,
25    "longitude": -84.31442417935,
26    "property_type": "RESIDENTIAL",
27    "deliverable": true,
28    "deliverability_analysis": null,
29    "street_view_available": true,
30    "labels": [],
31    "is_registered_agent": false,
32    "location_count": 1,
33    "created_at": "2022-07-15T13:57:25.802Z",
34    "updated_at": "2022-07-15T13:57:26.660Z",
35    "registered_agent_name": null,
36    "cmra": null,
37    "business_id": "b3638510-87ec-425e-bdaa-ad6e48dec871",
38    "sources": [{
39      "id": "be7afda5-a37c-4e30-baef-22a97c50366b",
40      "type": "fmcsa_registration",
41      "metadata": {
42        "dot_number": "2948750",
43        "labels": ["mailing", "physical"]
44      }
45    }]
46  }]
47}

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
1"addresses": [{
2  "object": "address",
3  "address_line1": "85 Second Street",
4  "address_line2": null,
5  "city": "San Francisco",
6  "state": "CA",
7  "postal_code": "94105-3459",
8  "full_address": "85 Second Street, San Francisco, CA 94105-3459",
9  "submitted": true,
10  "id": "f15e4ce9-109b-4a88-9540-5890ca511c2d",
11  "latitude": 39.09271,
12  "longitude": -104.87254,
13  "property_type": "COMMERCIAL",
14  "deliverable": true,
15  "deliverability_analysis": null,
16  "street_view_available": null,
17  "is_registered_agent": false,
18  "location_count": 1,
19  "labels": [],
20  "created_at": "2023-02-14T21:12:45.085Z",
21  "updated_at": "2023-02-14T21:12:45.085Z",
22  "registered_agent_name": null,
23  "cmra": null,
24  "business_id": "80556c5c-74d1-4e9c-91b8-9fe149338bef",
25  "sources": [
26    {
27      "id": "45fdfb94-7b45-402e-a3a6-2558b89fddac",
28      "type": "npi_record",
29      "metadata": {
30        "id": "1033531256",
31        "labels": ["mailing", "physical"],
32        "source_data": [
33          {
34            "name": "Business Name",
35            "value": "Middesk Inc"
36          },
37          {
38            "name": "National Provider Identifier (NPI)",
39            "value": "1234567890"
40          },
41          {
42            "name": "Primary Practice Address",
43            "value": "85 Second Street, San Francisco, CA 94105-3459"
44          },
45          {
46            "name": "Mailing Address",
47            "value": "85 Second Street, San Francisco, CA 94105-3459"
48          },
49          {
50            "name": "Secondary Practice Address",
51            "value": []
52          },
53          {
54            "name": "Enumeration Date",
55            "value": "2014-01-07"
56          }
57        ],
58        "source_data_link": "https://npiregistry.cms.hhs.gov/provider-view/1234567890"
59      }
60    }
61  ]
62},
63...
64]

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
1"addresses": [{
2  "object": "address",
3  "address_line1": "85 Second Street",
4  "address_line2": null,
5  "city": "San Francisco",
6  "state": "CA",
7  "postal_code": "94105-3459",
8  "full_address": "85 Second Street, San Francisco, CA 94105-3459",
9  "submitted": true,
10  "id": "f15e4ce9-109b-4a88-9540-5890ca511c2d",
11  "latitude": 39.09271,
12  "longitude": -104.87254,
13  "property_type": "COMMERCIAL",
14  "deliverable": true,
15  "deliverability_analysis": null,
16  "street_view_available": null,
17  "is_registered_agent": false,
18  "location_count": 1,
19  "labels": [],
20  "created_at": "2023-02-14T21:12:45.085Z",
21  "updated_at": "2023-02-14T21:12:45.085Z",
22  "registered_agent_name": null,
23  "cmra": null,
24  "business_id": "80556c5c-74d1-4e9c-91b8-9fe149338bef",
25  "sources": [
26    {
27      "id": "45fdfb94-7b45-402e-a3a6-2558b89fddac",
28      "type": "form_5500",
29      "metadata": {
30        "ack_id": "20240621220037NAL0002237923047",
31        "plan_year": 2023
32      }
33    }
34  ]
35},
36...
37]

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
1"addresses": [{
2  "object": "address",
3  "address_line1": "85 Second Street",
4  "address_line2": null,
5  "city": "San Francisco",
6  "state": "CA",
7  "postal_code": "94105-3459",
8  "full_address": "85 Second Street, San Francisco, CA 94105-3459",
9  "submitted": true,
10  "id": "f15e4ce9-109b-4a88-9540-5890ca511c2d",
11  "latitude": 39.09271,
12  "longitude": -104.87254,
13  "property_type": "COMMERCIAL",
14  "deliverable": true,
15  "deliverability_analysis": null,
16  "street_view_available": null,
17  "is_registered_agent": false,
18  "location_count": 1,
19  "labels": [],
20  "created_at": "2023-02-14T21:12:45.085Z",
21  "updated_at": "2023-02-14T21:12:45.085Z",
22  "registered_agent_name": null,
23  "cmra": null,
24  "business_id": "80556c5c-74d1-4e9c-91b8-9fe149338bef",
25  "sources": [
26    {
27      "id": "45fdfb94-7b45-402e-a3a6-2558b89fddac",
28      "type": "form_5500",
29      "license_number": "123455",
30      "license_type": "cosmetology",
31      "state": "CA",
32      "status": "active"
33    }
34  ]
35},
36...
37]

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
1"addresses": [
2  {
3    "object": "address",
4    "address_line1": "2478 Roseberry Ln",
5    "address_line2": null,
6    "city": "Grayson",
7    "state": "GA",
8    "postal_code": "30017-1554",
9    "full_address": "2478 Roseberry Ln, Grayson, GA 30017-1554",
10    "submitted": true,
11    "id": "38d7db40-8596-013d-7bba-6ea6aac5eb9c",
12    "latitude": 33.87024939590285,
13    "longitude": -83.96988736080574,
14    "property_type": "RESIDENTIAL",
15    "deliverable": true,
16    "deliverability_analysis": null,
17    "street_view_available": true,
18    "labels": [],
19    "created_at": "2024-11-15T13:15:08.545Z",
20    "updated_at": "2024-11-15T13:15:16.469Z",
21    "registered_agent_name": null,
22    "cmra": false,
23    "business_id": "3ef53f50-8596-013d-7bba-6ea6aac5eb9c",
24    "location_count": 2,
25    "is_registered_agent": false,
26    "sources": [
27      {
28        "id": "5b6a7370-8596-013d-7bba-6ea6aac5eb9c",
29        "type": "tax_exempt_organization",
30        "metadata": {
31          "labels": [
32            "mailing"
33          ]
34        }
35      }
36    ]
37  },
38  ...
39]

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 indicatorDescriptionKey
Valid US addressAn evaluation of whether the address is a valid address in the United State.valid_us_address
Geographical locationAn evaluation of whether the location of the address is in the US, international, or is unknown.geographical_location
Property typeAn evaluation of whether the address is residential or commercial.property_type
DeliverabilityAn evaluation of whether the address is deliverable, undeliverable, or vacant.deliverability
Private mailboxAn evaluation of if the address is one of the types of private mailboxes, including PO box and CMRA.private_mailbox
Registered agentAn evaluation of if the address is a registered agent address rather than the business’s actual operating address.registered_agent
Location frequencyAn evaluation of how many other businesses were found by Middesk using the same address.location_frequency
Virtual addressAn 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 to inquire about access.