API Basics

The MyDataHelps API is a REST-based interface, which means that applications make requests to the API by accessing specific URLs using HTTP. One of the hallmarks of REST is that the API calls are stateless, meaning each request is a single, self-contained operation.

Base URL

The endpoint for the MyDataHelps API is:


For example:


In the API reference, the base URL is usually omitted for brevity, and only the bolded part given.

Project Identifiers

All API calls are specific to a single project. You will generally identify your project in the resource url (e.g., api/v1/administration/projects/:projectId/participants).

You can find your project identifier in your project settings under the “About Settings” tab.


Every API call must contain an access token to authorize access to your project’s data. This will be sent in the HTTP header as a header key named “Authorization” containing the value “Bearer YOUR_TOKEN”. For more information on how to get an access token, see Authentication.

Required Headers

Every API call requires two fields in the HTTP request header:

Field Required Value Description
Authorization Bearer YOUR_TOKEN Contains the token that allows you to access the data. See Authentication for more information on how to obtain an access token.
Accept application/json Defines the data format the server should use. Only JSON is currently supported.

Data Formats

Data sent to and received from the MyDataHelps API will be in JSON format.

REST Basics

This section gives a brief introduction to REST APIs in general.


The URLs are centered around resources, which identify the kind of data you’re working with. For example, the URL api/v1/administration/projects/:projectId/participants is the URL for any API call that deals with project participants: querying them, adding them, updating them, and so on.

HTTP Verbs

Every API call uses a specific HTTP verb, which tells the system what kind of action you want to take with the resource. The verbs are summarized in the table below, but not all verbs apply to every resource. Consult the documentation for each resource to see what verbs are supported.

GET Gets data. This may be a query for all items matching a set of criteria, or a request for a specific item.
POST Submits data to the system, usually for adding a new item or taking a specific action with that item.
PUT Replaces an item with new data.
DELETE Deletes an item.


Some segments of the API URLs begin with a : to indicate that they are variables conveying information about the specific resource you wish to access. For example, the URL api/v1/administration/projects/:projectId/participants/:participantID identifies a resource with both a project ID and a participant ID.


In addition to the segments, many API calls use query parameters and/or request body data to send data to the server.

Query parameters are usually found on GET requests, specifying the details of the query. For example, in a request for participants, you can add query parameters to control how the results are broken up into pages: api/v1/administration/projects/:projectId/participants?pageSize=1&pageNumber=2.

Body data is usually used in PUT and POST requests to pass along the specific resource data you wish to add/update. For example, in a POST request to api/v1/administration/projects/:projectId/participants, the body of the request would specify the details of the participant(s) you wanted to add.

Error Handling

The response header for each request contains a status code indicating whether the request was successful. Common status codes you will encounter are:

Code Description
200 Success The request was successful.
400 Bad Request There was a problem with your request parameters.
429 Too Many Requests You have exceeded the API usage limits. See Rate Limits for details.
500 Internal Server Error There was an unknown issue processing the request. Check the response body for details, and contact support if you need help determining the problem.