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 keys must be used with the Sandbox API url https://api-sandbox.middesk.com/v1/.

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.

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 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 \

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

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 "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

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

curl --request GET \
    --url "https://api-sandbox.middesk.com/v1/businesses" \
    -u "mk_test_779ad1d91ea0e22973e17482:"