First API Request

To make your first Medable API request, you need to know four things:

  1. The API endpoint (e.g. api.dev.medable.com/myorgcode)
  2. The API key (e.g. 'mwidxhb8ShcqmV1B9iOYJh')
  3. Authentication Credentials (email and password)
  4. The API Client (terminal, web, iOS, or Android)

1. The API Endpoint

The endpoint for your api requests will look like

https://api.dev.medable.com/{{your_org_code}}/v2/{{api_resource}}

Where your_org_code is the org code you specified when Signing Up. And api_resource is the resource you are trying to access (e.g. accounts). And remember, since we're making this request to the development org, we use the api.dev.medable.com url.

Note

When making requests, use the plural name for your api_resource. For example if the resource is account, in your endpoint you'll use accounts e.g. https://api.dev.medable.com/newhealthco/v2/accounts

In our case, we'll use the example org code we used in signup newhealthco.

2. The API Key

Copy your API key that you generated in the last step. In our example, our API key is mwidxhb8ShcqmV1B9iOYJh.

3. Authentication Credentials

Because we specified that our app uses sessions, a username and password is needed to authenticate and initiate a user session.

For username, use your email address. In our case, john@newhealthco.com. For password, use the password you set when signing up.

If you're interested in siganture-based authentication, see Authentication.

4. The API Client

There are a number of tools out there that make it easy to make API requests. One option is Postman and another option is our live API explorer in our API Reference page . In this guide, we'll keep it simple and make our requests from the command line using cURL. For more information on cURL, click here.

Making the Request (from Terminal)

Now that you're ready to make a request, you simply have to issue the command in the form of curl [options...] <url>. Let's give it a shot using the API endpoint:

$ curl https://api.dev.medable.com/newhealthco/v2/accounts
{
    "object":"fault",
    "name":"error",
    "code":"kNotFound",
    "status":404,
    "reason":"Invalid application client api key.",
    "message":"Resource not found"
}

We got a result back! Unfortunately the result is a fault.

This is because we need to pass in a few more options to get the request to work. First, we need to add the api key header. We can do this using the following option option:

-H "medable-client-key: mwidxhb8ShcqmV1B9iOYJh"

So let's give that a try:

$ curl -H "medable-client-key: mwidxhb8ShcqmV1B9iOYJh" https://api.dev.medable.com/newhealthco/v2/accounts
{
   "object":"list",
   "data":[

   ],
   "hasMore":false
}

The fault is gone, but now we get back an unexpected result. Rather than a list of accounts, which should at least have our own account in it, we get an empty result.

This is because the Account resource requires authentication to access. If we had tried to access a specific account, we would have received a 403 error like so:

$ curl -H "medable-client-key: mwidxhb8ShcqmV1B9iOYJh" https://api.dev.medable.com/newhealthco/v2/accounts/575f58281d0c03a53ccc3ac6
{
   "object":"fault",
   "name":"error",
   "code":"kAccessDenied",
   "status":403,
   "reason":"Read access denied.",
   "message":"Access to this resource is denied"
}

So let's authenticate. To log in, we just need to POST to the login route with our username and password. For more information on the Account resource and the available routes, see the api documentation on Accounts.

One more thing before we login. For session based apps, Medable uses cookies to track the session id. So we need to enable cookie support in cURL. To do this, we pass in the additional options:

-b cookies.txt -c cookies.txt

The first option -b reads any existing cookies from cookies.txt and sends with the request and the second option -c writes any cookies coming from Medable to cookies.txt.

$ curl -b cookies.txt -c cookies.txt -H "medable-client-key: mwidxhb8ShcqmV1B9iOYJh" -d "email=john@newhealthco.com&password=This is not the password\!" https://api.dev.medable.com/newhealthco/v2/accounts/login
{
    "_id":"575f58281d0c03a53ccc3ac6",
    "object":"account",
    "created":"2016-06-14T01:04:40.888Z",
    "updated":"2016-06-14T01:08:06.647Z",
    "updater":{
       "_id":"575f58281d0c03a53ccc3ac6",
       "object":"account",
       "path":"/accounts/575f58281d0c03a53ccc3ac6"
    },
    "access":6,
    "favorite":false,
    "email":"john@newhealthco.com",
    "name":{
       "first":"John",
       "last":"Smith"
    },
    "mobile":"+15555555555",
    "locale":"en_US",
    "state":"verified",
    "locked":false,
    "key":{
       "fingerprint":"73ad85a0-31cc-11e6-ba07-3f24c7443557",
       "secret":"PXXvBvG86sJC2RVk4X6K4FV0OUH7ojzp"
    },
    "roles":[
       "000000000000000000000004",
       "000000000000000000000007",
       "000000000000000000000006"
    ],
    "shared":false
}

And we've successfully logged in! We know this because after a successful login, we receive our account object in the response.

If instead of a response similar to the above you receive a fault response that resembles this:

{"object":"fault","name":"location","code":"kNewLocation","status":403,"message":"A new location has been added to the account."}

This means that two-factor authentication (2FA) has been initiated. Note, the fault could be kNewLocation, kUnverifiedLocation, or kLocationClientMismatch.

When this happens, you will receive a verification token via sms to your mobile number. Once you receive that token, you'll need to authenticate again and this time send along the verificationToken as well like so:

curl -b cookies.txt -c cookies.txt -H "medable-client-key: mwidxhb8ShcqmV1B9iOYJh" -d 'email=john@newhealthco.com&password=NotYourPassword&location[verificationToken]=123456' https://api.medable.com/newhealthco/v2/accounts/login

For more information on 2FA, see Two Factor Authentication.

Now that we've logged in and have an active session, let's try that account request again.

$ curl -b cookies.txt -c cookies.txt -H "medable-client-key: mwidxhb8ShcqmV1B9iOYJh" https://api.dev.medable.com/newhealthco/v2/accounts
{
   "object":"list",
   "data":[
      {
         "_id":"575f58281d0c03a53ccc3ac6",
         "object":"account",
         "created":"2016-06-14T01:04:40.888Z",
         "updated":"2016-06-14T01:08:06.647Z",
         "updater":{
            "_id":"575f58281d0c03a53ccc3ac6",
            "object":"account",
            "path":"/accounts/575f58281d0c03a53ccc3ac6"
         },
         "access":6,
         "favorite":false,
         "email":"john@newhealthco.com",
         "name":{
            "first":"John",
            "last":"Smith"
         },
         "mobile":"+15555555555",
         "locale":"en_US",
         "state":"verified",
         "locked":false,
         "key":{
            "fingerprint":"73ad85a0-31cc-11e6-ba07-3f24c7443557",
            "secret":"PXXvBvG86sJC2RVk4X6K4FV0OUH7ojzp"
         },
         "roles":[
            "000000000000000000000004",
            "000000000000000000000007",
            "000000000000000000000006"
         ],
         "shared":false
      }
   ],
   "hasMore":false
}

Success! You've made your first API Request!