Using the Test Environment

Middesk has a test environment that can be accessed through the API or through the Dashboard.

Through the Dashboard

While logged in on the dashboard, a Middesk customer can access the Sandbox test environment by clicking on the Products icon in the top-right of the page, then toggling "View Sandbox". Once in Sandbox mode, the sample inputs described below can be used to create businesses with different sample data and features.

Through the API

Middesk customers are provided test API keys when their account is created. Your account's test keys can be retrieved by logging into your Middesk account and visiting Developer Settings. Test keys must be used with the Sandbox API url

Test API requests are free and return fake data, and also work with Middesk's webhooks feature. You can use the Webhooks API or contact us directly to set up your test webhook URL.

1. Creating a test business

Creating a business in the Middesk test environment works the same way that it would with your production keys. A sample business can be created with the below command:

curl \
    -u 'mk_test_779ad1d91ea0e22973e17482:' \
    --header 'accept: application/json' \
    -X POST \
    -d name=Middesk \
    -d website[url]= \
    -d addresses[0][address_line1]=2180+Bryant+St \
    -d addresses[0][address_line2]=Unit+210 \
    -d addresses[0][city]=San+Francisco \
    -d addresses[0][state]=CA \
    -d addresses[0][postal_code]=94110 \

Upon submission, Middesk will kick off this report in the test environment, and respond synchronously with a response similar to the below.

  "object": "business",
  "id": "64bce6b6-9773-41e5-9a6e-328e2a53dfcc",
  "name": "Middesk",
  "external_id": null,
  "created_at": "2019-09-03T21:17:16.954Z",
  "updated_at": "2019-09-03T21:17:16.954Z",
  "status": "open",
  "addresses": [
      "object": "address",
      "address_line1": "2180 Bryant St",
      "address_line2": "Unit 210",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94110",
      "full_address": "2180 Bryant St, Unit 210, San Francisco, CA 94110",
      "deliverable": null,
      "deliverability_analysis": null,
      "sources": [],
      "created_at": "2019-09-03T21:17:16.978Z",
      "updated_at": "2019-09-03T21:17:16.978Z"
  "domain": null,
  "summary": null,
  "tags": [],
  "tin": null,
  "formation": null,
  "website": {
    "object": "website",
    "id": "12e5bfdb-c776-4d04-b13f-7138bdafed71",
    "url": "",
    "title": null,
    "description": null,
    "pages": [],
    "entities": [],
    "registration": {}
  "watchlist": null,
  "names": [],
  "filings": [],
  "phone_numbers": [],
  "registrations": [],
  "reports": [
      "object": "report",
      "id": "460df301-389c-405b-b474-7a88a42d020c",
      "created_at": "2019-09-03T21:17:17.012Z",
      "updated_at": "2019-09-03T21:17:17.012Z",
      "completed_at": null,
      "status": "pending",
      "package": "basic"
  "tasks": []

2. Receiving responses

Middesk will progress the report through pendingin_review states and will post events to your test webhook URL for each transition.

In completing the business, Middesk will populate the report with a set of fake data.

To simulate the time it takes to successfully fetch all the information about a business request, there is a delay of 1 to 2 seconds before the business payload is returned back in the response.

3. Retrieving a business

Once you have created a test business, you can retrieve the same business resource. A sample test business with fake data can be retrieved with the below command, using the Middesk-provided 'business_id' in the call:

curl --request GET \
    --url "${BUSINESS_ID}" \
    -u "mk_test_779ad1d91ea0e22973e17482:"

A PDF of a Business can also be requested in Sandbox with the following command:

curl --request GET \
    --url "${BUSINESS_ID}/pdf" \
    -u "mk_test_779ad1d91ea0e22973e17482:"

4. Retrieving all businesses

After creating more than one business, you can retrieve all created businesses at the same time. A list of all businesses created in your sandbox account can be retrieved with the following command:

curl --request GET \
    --url "" \
    -u "mk_test_779ad1d91ea0e22973e17482:"

Basic test businesses

One major draw of the test environment is that it's free to use. To support its availability, we provide responses with dummy data, some of which can be controlled by specific inputs. This allows for running specific scenarios and understanding how to adjust the integration. Below is a list of inputs with a description of the expected change in response.

NameUnregistered BusinessThe business has no Secretary of State filings. The Business returned will have no associated registrations.
NameSimilar Name BusinessThe business has a Secretary of State filing with a similar name to the submitted business name. The "name" review task indicates that a similar name was found to the submitted name.
Address123 Grand St., New York, NY 10013Unable to identify a match to the submitted Office Address. The submitted address is not found to match any address listed in Business records.
Address223 Grand St., New York, NY 10013Identified an address within 0.2 miles of the submitted Office Address. The submitted address is found to be close to the addresses found in Business records.
PersonJ DoeUnable to identify a match to the submitted person. The person input will result in an unverified Person, meaning there's no match found to the Person's name on any Business record.
TIN110000099TIN Name mismatch. The submitted TIN was found to be associated with a different entity name.
BankruptcyA business name containing the word bankruptcyThe business will have a bankruptcy. The Business will have a bankruptcy attached.
WatchlistA Business name or Person name containing the phrase watchlist hit.The business or person will have a watchlist hit on them
Industry ClassificationAny websiteThe business' website will have an industry classification
Industry ClassificationA website containing the words highriskThe business' website will have an industry classification with a high risk result.
AnyAnyVerified. If none of the above inputs match, the Business will fallback to verifying all information. Given most inputs then, you can expect to receive a Review object with successful tasks.

The above allows for created mixed responses; different states for different attributes can be triggered with specific values. Given the above, one can create a business with an approximate address match and unverified person using the inputs 223 Grand St., New York, NY 10013 and J Doe, respectively.

As alluded to in the last row, the test environment will fall back to successful statuses for its Review tasks, such that in most cases, you'll be able to work with relatively rich data.

Differences between test and production

The Middesk test environment enables developers integrate with the Middesk API before going live in a production environment. Listed below are some differences between the test and production environments.

Depth of report information

Middesk provides a rich set of information for its reports. A business can have multiple registration records, multiple addresses, multiple officers, and so on. In general, the test environment provides enough information to build an integration, but, given that the data is mocked, its variance is limited, with the aim to represent the most common cases to build against.

Business lifecycle

As referenced in the Middesk Business Lifecycle, Middesk transitions a business through multiple states, from pending to in_audit (occasionally) to in_review. The sandbox supports these transitions, with the exception of the in_audit status. When building against the Middesk sandbox, it's important to take this difference into consideration.


In the test environment, documents will be retrieved for every business. In production, this is a premium feature. If interested in learning more, please contact sales.

Additional features

Business Batches

Batches in Sandbox can be created and read in the same way as they are in production. Use this feature to create many businesses at once, and provide attributes as detailed in the table above to trigger different verification scenarios as desired.

Industry Classification

Classifications can be created for Sandbox businesses if a website URL is inputted or as stand-alone classifications. For both products, the possible inputs to get different results are described above.


To test subscriptions, create a business with the inputs described below. The business will automatically have a subscription with the corresponding event yype. After a minute, the business and its records will be updated accordingly to simulate the occurrence of that event, which you can receive by creating a webhook or polling for updates.

Event TypeInput FieldValueDescription
watchlist_result.createdBusiness NameWatchlist Result Created IncA new Watchlist Result will be created for the Business

What’s Next

Learn to use our webhooks capability.