LogoLogo
  • Introduction
  • Features
  • Getting Started
    • Cortex User Guide
      • Organizations
      • Log in
      • Generate an API key
      • Make your first API request
      • Configure the org settings
      • Set up a data model
        • Create custom objects
        • Add custom properties
      • One-to-many relationships
      • Read and write data
      • Making a Request
      • Handling responses
      • Authentication
      • Two-factor authentication
      • Set third-party cookies
      • Connections
      • Upload files
      • Cortex iOS
      • Get started with Swift
      • Cortex service accounts
      • Cortex developer tools
      • Automated Account Notifications
  • Cortex API
    • Overview
    • Objects
      • Objects Overview
      • Organization
      • Account
      • Connections
      • Notifications
      • Stats
      • Logs
      • Export
      • Events
      • Room
    • Object Definition
      • Object Properties
        • Any
        • Binary
        • Boolean
        • Date
        • Document
        • File
        • Geometry
        • List
        • Number
        • ObjectId
        • Reference
        • String
    • Object Types
    • Access Control
    • Querying
      • Query Operators
      • Property Selection
      • Property Access
    • Aggregating
      • Aggregation Operators
    • Scripting
      • Script Types
      • Script Limits
      • ObjectId
      • CortexObject
        • Accounts
        • Views
      • Cursors
      • Operations
      • Script Modules
        • API Module
        • Base64 Module
        • Cache Module
        • Connections Module
        • Console Module
        • Consts Module
        • Counters Module
        • Crypto Module
        • HTTP Module
        • Logger Module
        • Notifications Module
        • Request Module
        • Response Module
        • SAML Module
        • Schemas Modules
        • Script Module
        • Session Module
        • Util.id Module
        • Util.ip Module
        • Util.paths Module
        • XML Module
        • Developer
        • Config
        • Renderer
        • SFTP
        • FTP
        • DB
          • Cursors
          • Driver
      • Static Methods
        • Accounts
        • Views
        • Cursors
      • Audit
      • Environments
      • HTTP Driver
      • Notifications
        • Firebase Cloud Messaging (FCM)
        • Tencent Push Notification Service Configuration
      • Televisit
      • Transforms
      • Localization
      • Available Javascript Libraries
    • Decorators
      • Runtime
        • Acl
        • As
        • Log
        • Profile
      • Static
        • Env
        • Job
        • Object
        • On
        • Policy
        • Route
        • Transform
        • Trigger
    • Expressions
      • Primer
      • Pipelines
      • Operators
      • Accumulators
      • Variables
      • Conditionals
      • Transforms
      • Triggers
      • On
      • Events
    • Faults
      • Fault Reference
  • Releases
    • Cortex Release Notes
      • Cortex API 2.28.3 (R3.4.6)
      • Cortex API 2.28.1 (R3.4.3)
      • Cortex API 2.27.2 (R3.4.1)
      • Cortex API 2.27.1 (R3.3.5)
      • SQL DB Connector 1.3.4 (R3.3.3)
      • Cortex API 2.26.2 (R3.3.1)
      • Cortex API 2.26.1 (R3.2.2)
      • Cortex API 2.26.0 (R3.2.1)
      • SQL DB Connector 1.3.3
      • Cortex API 2.25.0 (R3.1.1)
      • SQL DB Connector 1.3.2 (R3.1.0)
      • Cortex API 2.24.2 (R3.0.2)
      • SQL DB Connector 1.3.1 (R3.0.0)
      • Cortex API 2.24.1 (R2.3.3)
      • Cortex API 2.24.0 (R2.3.2)
      • SQL DB Connector 1.3.0 (R2.3.0)
      • Cortex API 2.23.0 (R2.2.4)
      • SQL DB Connector 1.2.0 (R2.2.0)
      • Cortex API 2.22.2 (R2.1.2)
      • Cortex API 2.22.1 and SQL DB Connector 1.1.1 (R2.0.1)
      • Cortex API 2.22.0
      • Cortex API 2.21.3
      • Cortex API 2.21.2
      • Cortex Web 4.16.0
      • Cortex Web 4.15.1
      • Cortex API 2.20.1
      • Cortex Web 4.14.0
      • Cortex Renderer 1.3.3
      • Cortex API 2.19.4
      • Cortex API 2.19.3 and Cortex Web 4.13.1
      • Cortex Renderer 1.3.2
      • Cortex API 2.19.1
      • Cortex API 2.18.0
      • Cortex API 2.17.6
      • Cortex API 2.17.5
      • Cortex API 2.17.4
      • Cortex API 2.17.3
      • Cortex API 2.17.2
      • Cortex API 2.17.1
      • Cortex API 2.16.0
      • Cortex API 2.15.9
      • Cortex API 2.15.8-1
      • Cortex 2.15.8
      • Cortex API 2.18.1
      • Cortex API 2.16.1
      • Cortex Renderer 1.3.1
      • Cortex Renderer 1.3.0
      • Cortex Renderer 1.2.2
      • Cortex Renderer 1.2.1
      • Cortex Renderer 1.2.0
    • Third-Party License Attribution

© 2025 Medable, Inc. All rights reserved.

On this page
  • Medable API requests
  • The API endpoint
  • The API key
  • Authentication credentials
  • The API client
  • Make a request

Was this helpful?

  1. Getting Started
  2. Cortex User Guide

Make your first API request

Last updated 3 years ago

Was this helpful?

Medable API requests

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

  1. The API endpoint: for example, api.<env>.medable.com/<org_code>

  2. The API key: for example, mwidxhb8ShcqmV1B9iOYJh

  3. Authentication credentials: an email and password

  4. The API client: a terminal, web, iOS, or Android

The API endpoint

The endpoint for your API requests will look like the following:

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, such as an account. And remember, since we're making this request to the development org, we use the api.dev.medable.com URL.

In our case, we'll use the example org code we used when we made the new app: newhealthco.

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

The API key

Copy the API key that you generated in the previous step (see ). In our example, the API key is mwidxhb8ShcqmV1B9iOYJh.

Authentication credentials

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

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

The API client

Make a request

Note: This section is written assuming the request is being made through an OSX 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"
}

Tip: Add | python -m json.toolto the end of the curl request to pretty-print the JSON response.

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:

-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 using an account ID (575f58281d0c03a53ccc3ac6 in this case), we would receive 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"
}

One more thing before we log in. 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. 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 that 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 as well as send along verificationToken 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

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

Success! You've made your first API request!

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

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

So let's authenticate. To log in, we 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 .

For more information on 2FA, see .

Generate an API key
curl
API documentation on Accounts
Two-factor authentication
Authentication