API v1
Updated 2026-01-29
Authentication and Setup
To interact with the API, you must first generate a valid Client ID and Client Secret or an API Token. You have two options to get these credentials:
1: Generating API Credentials using API Client
- Log in to your DMPonline instance with administrator privileges.
- Navigate to the API Clients management page:
- Local Development:
http://localhost:3000/super_admin/api_clients - Production:
https://[Your-Domain]/super_admin/api_clients
- Local Development:
- Click the "Create API Client" button in the top right corner.
- Fill in the obligatory fields (Name and Contact Email) and click Save.
Retrieving Credentials
Once the client is created, the system will generate a client_id and client_secret. These are sent via email to the address you provided.
Note for Local Development: If running locally, emails are captured by Mailhog. The email will contain a JSON object like this:
{
"grant_type": "client_credentials",
"client_id": "long_string_with_client_id",
"client_secret": "long_string_with_client_secret"
}2: Generating API Credentials as Org Admin
Login as an Org Admin and visit your profile edit page: http://localhost:3000/users/edit
Go to the 'API Access' tab. Here you will see your 'Access token'. If one does not exist, click 'Regenerate token'. If you do not see the API Access tab, you do not have the necessary permissions.
Setting up Postman
We recommend organizing your requests into a Postman Collection. Set up environment variables for {{BASE_URL}} to switch between environments easily.
- Local:
http://localhost:3000/ - Production:
https://[Your-Domain]/
Setting up a Collection in Postman (completely optional)
Just a folder in Postman to organize your requests.
- Open Postman.
- Create a new Collection (e.g., named "Belnet" or "DMPonline").
- (Optional) Setup environment variables for {{BASE_URL}} to easily switch between local and production environments.
Adding Requests
- Hover over your new Collection folder.
- Select Add Request.
- Create a separate “Request” for each endpoint you intend to test. (Can be in the same folder)
Using the API
There are a couple endpoints out of the box from DMPonline, below will be a detailed guide to use these endpoints given the information we already know and have set up above.
Heartbeat (Status Check)
GET {{BASE_URL}}/api/v1/heartbeat
Informative call to check server status. Does not require authentication.
Sample Response:
{
"application": "DMPonline.be",
"source": "GET /api/v1/heartbeat",
"time": "2026-01-29T09:03:57+00:00",
"caller": "[YOUR IP ADDRESS]",
"code": 200,
"message": "OK",
"total_items": 0,
"items": []
}Authentication / Login
Option A: API Client Login
POST {{BASE_URL}}/api/v1/authenticate
Use the JSON body received in your email (client_id, client_secret, and grant_type: client_credentials).
Headers
| Key | Value |
|---|---|
| Content-Type | application/json |
| Accept | application/json |
Body
{
"grant_type": "client_credentials",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}Sample Response:
{
"access_token": "LONG_ACCESS_TOKEN_STRING_STARTS_WITH_EY..",
"token_type": "Bearer",
"expires_in": 1769764618,
"created_at": "2026-01-29T09:16:58+00:00"
}Option B: Org Admin Login
POST {{BASE_URL}}/api/v1/authenticate
Headers
| Key | Value |
|---|---|
| Content-Type | application/json |
| Accept | application/json |
Body
{
"grant_type": "authorization_code",
"email": "YOUR_ADMIN_EMAIL",
"code": "YOUR_PERSONAL_API_TOKEN"
}Sample Response:
{
"access_token": "LONG_ACCESS_TOKEN_STRING_STARTS_WITH_EY..",
"token_type": "Bearer",
"expires_in": 1769764952,
"created_at": "2026-01-29T09:22:32+00:00"
}Important: Both methods return an access_token. You must use this as a Bearer Token in the Authorization header for all the following requests.
Templates and Plans
Get Templates
GET {{BASE_URL}}/api/v1/templates
Retrieves funder templates or organizational templates.
Headers
| Key | Value |
|---|---|
| Accept | application/json |
| Authorization | Bearer YOUR_ACCESS_TOKEN |
Sample Response:
{
"application": "DMPonline.be",
"source": "GET /api/v1/templates",
"time": "2026-01-29T09:34:15+00:00",
"caller": "Bob Brown",
"code": 200,
"message": "OK",
"page": 1,
"per_page": 100,
"total_items": 13,
"items": [
{
"dmp_template": {
"title": "SAMPLE TITLE",
"description": "SAMPLE DESCRIPTION",
"version": 1,
"created": "2022-09-27T11:23:20Z",
"modified": "2024-09-27T11:28:27Z",
"affiliation": {
"name": "SAMPLE AFFILIATION NAME",
"abbreviation": "SAN",
"affiliation_id": {
"type": "SAMPLE TYPE",
"identifier": "SAMPLE URL IDENTIFIER"
}
},
"template_id": {
"type": "other",
"identifier": "6429"
}
}
}
]
}Get All Plans
GET {{BASE_URL}}/api/v1/plans
Retrieves a list of plans you have access to. Supports pagination via page=[n] and per_page=[n].
Headers
| Key | Value |
|---|---|
| Accept | application/json |
| Authorization | Bearer YOUR_ACCESS_TOKEN |
Sample Response:
{
"application": "DMPonline.be",
"source": "GET /api/v1/plans",
"time": "2026-01-29T09:44:44+00:00",
"caller": "Bob Brown",
"code": 200,
"message": "OK",
"page": 1,
"per_page": 100,
"total_items": 283,
"next": "/api/v1/plans?page=2&per_page=100",
"items": [
{
"dmp": {
"schema": "SAMPLE SCHEMA URL",
"title": "SAMPLE PLAN TITLE",
"language": "eng",
"created": "2019-07-17T12:34:27Z",
"modified": "2024-09-17T12:58:27Z",
"ethical_issues_exist": "unknown",
"dmp_id": {
"type": "url",
"identifier": "http://localhost:3000/api/v1/plans/PLAN_ID"
},
"contact": {
"name": "JOS VERMEULEN",
"mbox": "JOSVERMEULEN@uschoten.be",
"affiliation": {
"name": "Universiteit Schoten",
"abbreviation": "USchoten",
},
"contact_id": {
"type": "orcid",
"identifier": "https://orcid.org/0000-0003-0408-1467"
}
}
}
}
]
}Get Specific Plan
GET {{BASE_URL}}/api/v1/plans/PLAN_ID
Headers
| Key | Value |
|---|---|
| Accept | application/json |
| Authorization | Bearer YOUR_ACCESS_TOKEN |
Sample Response:
{
"application": "DMPonline.be",
"source": "GET /api/v1/plans/197325",
"time": "2026-01-29T09:54:59+00:00",
"caller": "Bob Brown",
"code": 200,
"message": "OK",
"page": 1,
"per_page": 100,
"total_items": 1,
"items": [
{
"dmp": {
"schema": "SAMPLE SCHEMA URL",
"title": "SAMPLE PLAN TITLE",
"description": "",
"language": "eng",
"created": "2024-02-27T07:26:10Z",
"modified": "2024-02-27T07:30:17Z",
"ethical_issues_exist": "unknown",
"dmp_id": {
"type": "url",
"identifier": "http://localhost:3000/api/v1/plans/PLAN_ID"
},
"contact": {
"name": "JOS VERMEULEN",
"mbox": "JOSVERMEULEN@uschoten.be",
"affiliation": {
"name": "Universiteit Schoten",
"abbreviation": "USchoten"
},
"contact_id": {
"type": "orcid",
"identifier": "https://orcid.org/0000-0003-0408-1467"
}
},
"contributor": [
{
"name": "JOS VERMEULEN",
"mbox": "JOSVERMEULEN@uschoten.be",
"role": [
"other"
],
"affiliation": {
"name": "Universiteit Schoten",
"abbreviation": "USchoten"
},
"contributor_id": {
"type": "orcid",
"identifier": "https://orcid.org/0000-0003-0408-1467"
}
},
{
"name": "SAMPLE SECOND CONTRIBUTOR",
"mbox": "SAMPle SECOND CONTRIBUTOR EMAIL",
"role": [
"LINK TO ROLE"
],
"affiliation": {
"name": "Universiteit Schoten",
"abbreviation": "USchoten"
}
}
],
"project": [
{
"title": "Sample Project Title",
"description": "",
"start": "2023-03-01T00:00:00Z",
"end": "2025-06-30T00:00:00Z",
"funding": [
{
"grant_id": {
"type": "other",
"identifier": "NA"
},
"funding_status": "granted",
"dmproadmap_funding_opportunity_id": {
"type": "other",
"identifier": "NA"
},
"dmproadmap_funded_affiliations": [
{
"name": "Universiteit Schoten",
"abbreviation": "USchoten"
}
]
}
]
}
],
"dataset": [
{
"type": "dataset",
"title": "Generic dataset",
"description": "No individual datasets have been defined for this DMP."
}
],
"extension": [
{
"dmproadmap": {
"template": {
"id": 7421,
"title": "USCHOTEN DMP"
}
}
}
]
}
}
]
}Creating a Plan
POST {{BASE_URL}}/api/v1/plans
Expects an RDA Common Standard JSON representation.
Headers
| Key | Value |
|---|---|
| Content-Type | application/json |
| Accept | application/json |
| Server-Agent | DMPonline |
| Authorization | Bearer YOUR_ACCESS_TOKEN |
Body
{
"total_items": 1,
"items": [
{
"dmp": {
"title": "Examination of some interesting topics in biochemistry",
"contact": {
"name": "Jane Doe",
"mbox": "jane.doe@example.edu",
"affiliation": {
"name": "Example University"
},
"contact_id": {
"type": "orcid",
"identifier": "0000-0000-0000-0000"
}
},
"contributor": [
{
"name": "John Smith",
"mbox": "john.smith@un.edu",
"role": [
"https://dictionary.casrai.org/Contributor_Roles/Data_curation",
"https://dictionary.casrai.org/Contributor_Roles/Investigation"
],
"affiliation": {
"name": "University of Nowhere",
"affiliation_id": {
"type": "ror",
"identifier": "https://ror.org/123abc45y"
}
},
"contributor_id": {
"type": "orcid",
"identifier": "https://orcid.org/0000-0000-0000-0000"
}
}
],
"extension": [
{
"dmproadmap": {
"template": {
"id": 3
}
}
}
]
}
}
]
}Sample Response:
{
"application": "DMPonline.be",
"source": "POST /api/v1/plans",
"time": "2026-01-29T10:27:56+00:00",
"caller": "Bob Brown",
"code": 201,
"message": "Created",
"page": 1,
"per_page": 100,
"total_items": 1,
"items": [
{
"dmp": {
"schema": "https://github.com/RDA-DMP-Common/RDA-DMP-Common-Standard/tree/master/examples/JSON/JSON-schema/1.0",
"title": "Examination of some interesting topics in biochemistry",
"language": "eng",
"created": "2026-01-29T10:27:56Z",
"modified": "2026-01-29T10:27:56Z",
"ethical_issues_exist": "unknown",
"dmp_id": {
"type": "url",
"identifier": "http://localhost:3000/api/v1/plans/197641"
},
"contact": {
"name": "Jane Doe",
"mbox": "jane.doe@example.edu",
"affiliation": {
"name": "Example University",
"abbreviation": "EU"
},
"contact_id": {
"type": "orcid",
"identifier": "https://orcid.org/0000-0002-5297-1074"
}
},
"contributor": [
{
"name": "Jane Doe",
"mbox": "jane.doe@example.edu",
"role": [
"http://credit.niso.org/contributor-roles//data-curation"
],
"affiliation": {
"name": "Example University",
"abbreviation": "EU"
},
"contributor_id": {
"type": "orcid",
"identifier": "https://orcid.org/0000-0002-5297-1074"
}
}
],
"project": [
{
"title": "Examination of some interesting topics in biochemistry",
"start": "2026-01-29T10:27:56+00:00",
"end": "2028-01-29T10:27:56+00:00"
}
],
"dataset": [
{
"type": "dataset",
"title": "Generic dataset",
"description": "No individual datasets have been defined for this DMP."
}
],
"extension": [
{
"dmproadmap": {
"template": {
"id": 3,
"title": "PPW DMP "
}
}
}
]
}
}
]
}