Using the Sandbox Environment

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

Through the Dashboard

While logged in to the dashboard, you can access the Sandbox test environment by clicking on the Products icon on the top-right corner of the page, then toggling "View Sandbox". Once in Sandbox mode, the sample attributes described under the Example Sandbox Business Attributes table below can be used to create a Business with sample data.

Through the API

You are immediately provided Sandbox API keys when your account is created. Your Sandbox keys can be retrieved by logging into your Middesk account and visiting Developer Settings.

Sandbox API requests are free and while you may include real business data in the Create a Business request, the response will return fake data. You may also set up Webhooks in the Sandbox environment.

Example Sandbox Business Attributes

One major benefit of using the Sandbox environment is that you can walk through various example scenarios that you might encounter you Create a Business.

To do so, include one (or more) of the specified values in the table below in your Create a Business request. Middesk will then return a response according to that value. This will allow you to run specific scenarios and build out your integration workflow accordingly.





Unregistered Business

The business has no Secretary of State filings. The Business returned will have no associated registrations.


Similar Name Business

The 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.


123 Grand St., New York, NY 10013

Unable to identify a match to the submitted Office Address. The submitted address is not found to match any address listed in Business records.


223 Grand St., New York, NY 10013

Identified 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.


J Doe

Unable 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.



TIN Name mismatch. The submitted TIN was found to be associated with a different entity name.


A business name containing the word bankruptcy

The business will have a bankruptcy. The Business will have a bankruptcy attached.


A Business name or Person name containing the phrase watchlist hit.

The business or person will have a watchlist hit on them

Industry Classification

Any website

The business' website will have an industry classification

Industry Classification

A website containing the words highrisk

The business' website will have an industry classification with a high risk result.



Verified. 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.

Feel free to mix-and-match any of the values found on the table to create unique scenarios. For example, you 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.

Now that you understand how to use the Sandbox environment, let's walk through an example Sandbox workflow.

1. Creating a Business in Sandbox

Creating a Business in the Sandbox environment works the same way that it would with your production keys.

Authentication to the API using API keys is generally performed via HTTP Basic Auth. Provide the API key as the basic auth username value. No password is required.

Bearer authentication is supported as well, in which case you can pass a header value as Authorization: Bearer mk_live_4eC39HqLyjWDarjtT1zdp7dc.

Note: This is the same request that you made back in the Introduction (Editing) section.

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 \

If you can recall from the Lifecycle of a Business section, once you Create a Business, Middesk will return the response below to you synchronously where the status of the Business is set to open. Simultaneously, Middesk will kick off the search process in the background for the Business you just created.

  "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": []

Every Business object will have its own unique id that is generated by Middesk. You will use this id later to retrieve the same Business object when checking for updates.

2. Receiving responses

As Middesk conducts its investigation on the requested Business, it will progress the report through the statuses of the Lifecycle and will post any relevant events to your Webhook URL if you have one set up.

If you do not wish to set up a Webhook, you may poll for new updates by using the Retrieve a Business endpoint.

3. Retrieving a Business

After creating a Business, you can retrieve it using the Retrieve a Business endpoint at any time to ingest new updates if there are any.

To retrieve the same Business object that we created in Step 1: Creating a Business in Sandbox, include the id that you saved from Step 1: Creating a Business in Sandbox in the endpoint.

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

If you've created more than one Business, you can retrieve all of them simultaneously with the following request.

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

Did this page help you?