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 https://api-sandbox.middesk.com/v1/.

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 https://api-sandbox.middesk.com/v1/businesses \
    -u 'mk_test_779ad1d91ea0e22973e17482:' \
    --header 'accept: application/json' \
    -X POST \
    -d name=Middesk \
    -d website[url]=https://www.middesk.com \
    -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": "https://www.middesk.com",
    "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 pending → in_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 "http://api-sandbox.middesk.com/v1/businesses/${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 "http://api-sandbox.middesk.com/v1/businesses/${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 "https://api-sandbox.middesk.com/v1/businesses" \
    -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.

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.

Documents

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.

Subscriptions

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.