Step 1: Obtain your API key

Middesk authenticates your API requests using your account's unique API key. If you do not include your key when making an API request or use one that is incorrect or outdated, Middesk will return an error.

You can access your API key by logging into your Middesk account and visiting Developer Settings.

If you do not have a Middesk account yet, you can Sign Up in only a few minutes.

If you are following along with our examples here to get up and running with Middesk, we should note that the API keys included in our docs are all randomly generated, so be sure to replace these keys with your own.

Step 2: Make an API request

After obtaining your keys, ensure that they are working as expected. Try making your first API request by creating a new Business via the https://api.middesk.com/v1/businesses endpoint. If you are confused about what a "Business" is, don't worry! In the next section, we will go through all the core concepts and terms that you need to know.

You can also copy + paste the cURL request that is already pre-populated with your Sandbox secret key here.

curl https://api-sandbox.middesk.com/v1/businesses \
  -u $YOUR_SANDBOX_API_KEY: \
  --header "Accept: application/json" \
  -X POST \
  -d name=Middesk \
  -d tin[tin]=123410000 \
  -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

After creating a business, you will receive a response from our API to confirm the creation of that Business.

{
  "object": "business",
  "id": "5966eefe-7ba5-4e98-9f95-1e8d0bca6ec6",
  "name": "Middesk",
  "external_id": null,
  "created_at": "2019-02-04T18:17:20.421Z",
  "updated_at": "2019-02-04T18:17:20.421Z",
  "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",
      "created_at": "2019-02-04T18:17:20.533Z",
      "updated_at": "2019-02-04T18:17:20.533Z"
    }
  ],
  "website": {
    "url": "https://www.middesk.com"
  },
  "tin": {
    "tin": "12-3410000"
  }
}

You've just created your first Business! Move on to the next section to learn about what a Business is and how it is used within the Middesk API.