API Reference

Address

A business will 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. We also return a variety of details that can be helpful for compliance, fraud, and underwriting decisions.

{
  "object": "address",
  "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",
  "latitude": 37.75938,
  "longitude": -122.40994,
  "property_type": "COMMERCIAL",
  "cmra": false,
  "deliverable": true,
  "is_registered_agent": false,
  "location_count": 1,
  "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"
}
AttributeTypeDescription
address_line1stringThe street address of the business.
address_line2 stringThe second address line typically used for apartment or suite numbers.
city stringThe city of the business
state stringThe state of the business
postal_code stringThe postal code of the business
full_address stringDisplay version of address
latitude floatThe latitude of the business address
longitude floatThe longitude of the business address
property_typestringThe type of property known to be located at this address. Possible values are:
"COMMERCIAL"
"RESIDENTIAL"
cmrabooleanIndicates when an address is a Commercial Mail Receiving Agency (CMRA).
deliverablebooleanA summary of the deliverability of the address. Value isUnknown 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
ratingobject An 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

🚧

FMCSA Registrations Enablement

As a supplementary data point for business address verification, we have added the ability to search and match against the FMCSA (Federal Motor Carrier Safety Administration). FMCSA data will appear in the "sources" field when the business address can be found in their database.

{
	...
	"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": "<link>"
	}],
	"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

🚧

NPPES NPI Registry Data Enablement

As a supplementary data point for business address verification, we have added 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 will appear in the "sources" field when found.

"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

🚧

Form 5500 Data Enablement

As a supplementary data point for business address verification, we have added the ability to search and match against data from the US Department of Labor Form 5500 datasets. Form 5500 registry data will appear in the "sources" field when found.

"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

🚧

Professional Licenses Data Enablement

As a supplementary data point for business address verification, we have added 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.

"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, we match 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 will appear in the "sources" field.

"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" of each of the business’s addresses (both known and submitted). Going one step further, we 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 will be absent from the payload.

Risk IndicatorDescriptionKey
Valid US addressAn evaluation of whether the address is a valid address in the United Statesvalid_us_address
Geographical locationAn evaluation of whether the location of the address is in the US, international, or is unknowngeographical_location
Property typeAn evaluation of whether the address is residential or commercialproperty_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