Introduction
Welcome to the RISKID Public API Reference! You can use our RISKID API endpoints to interact with your RISKID account.
Use risks and projects you've created in RISKID in your own applications to create value and connection to other tools. Creating BI, dashboards etc.
To use the RISKID Public API you need to have:
- a client name
- a client secret
- an api name
The RISKID Public API is built with REST concepts in mind, but we do not aim to be RESTful. Currently all our endpoints return JSON-encoded responses and use standard HTTP response codes and verbs. For Authorization we make use of OAuth2.
Authentication (Tokens)
RISKID Public API uses tokens to allow access to the API. You can get a working token according to the following workflow.
<%= image_tag "public_structure.png"%>
You can request for your client credentials from your RISKID account manager.
RISKID expects for the token key to be included in all API requests to the server in the parameter that looks like the following:
"token": awonderfultokenforriskid
Getting the token
POST /token:
{
"client_name":"409e6910bec5.riskid",
"client_secret":"d0e6c21fcba487a4a0766908fe6977ce"
}
{
"client_name":"409e6910bec5.riskid",
"client_secret":"d0e6c21fcba487a4a0766908fe6977ce"
}
Server response
{
"access_token": "string",
"expires_in": "number"
}
{
"access_token": "a2e8805e51cb1e125f3004d59d8fdc93299fc017",
"expires_in": "3600"
}
In order to start placing requests to the API you must first create an active token. You can retrieve the token by sending your client name and client secret. These are provided through the RISKID account manager.
Your client name and secret key is need to generate your access tokens, so be sure to keep them secure! Do not share your secret keys in publicly accessible areas such as code repositories, client-side code, and so forth.
HTTP Request
POST http://your.riskid.domain/openapi/token
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| client_name | Yes | - | Use the client_name provided by RISKID linked to your account. |
| client_secret | Yes | - | Use the client_secret provided by RISKID linked to your account. |
Response properties
| Property | Description |
|---|---|
| access_token | The token to be used for further requests to the API |
| expires_in | Token expire time in milliseconds |
Using the token
POST /projects:
{
"api_name":"your_api_name",
"token":"access_token_from_token_request",
}
{
"api_name":"my_application",
"token":"a2e8805e51cb1e125f3004d59d8fdc93299fc017",
}
In every request call, the token needs to be added to identify the client.
Token expired
402: Token is expired
The token you create with your credentials is time limited. When it expires you will receive an error in the response and you'd need to request a new token
Handling projects
Getting projects
Sample of request params:
"api_name":"my_application",
"token":"a2e8805e51cb1e125f3004d59d8fdc93299fc017",
"codes": ["ABCD"]
"api_name":"string",
"token":"<token_string>",
"codes": ["string"],
"owners": ["string"], // email address
"authors": ["string"], // email address
"created_after": "yyyy-mm-dd",
"created_before": "yyyy-mm-dd"
The above command returns JSON schema like this:
{
"projects":[
{
"id": "17",
"name": "Project ABCD",
"code": "ABCD",
"description": "This is a sample project called Project ABCD",
"folder": "Sample Projects",
"owners": [
{
"surname": "Banner",
"forename": "Michael",
"email": "m.banner@example.com",
"index": "1"
}
],
"currency": "EUR",
"start_date": "2021-05-03",
"end_date": "2021-12-15",
"created_on": "2021-03-20",
"modified_on": "2021-11-10",
"budget": "100000",
"cost": "20000",
"author": {
"surname": "Banner",
"forename": "Michael",
"email": "m.banner@example.com"
}
}
]
}
{
"projects":[
{
"id": "number",
"name": "string",
"code": "string",
"description": "string",
"folder": "string",
"owners": [
{
"surname": "string",
"forename": "string",
"email": "string",
"index": "number"
}
],
"currency": "string",
"start_date": "yyyy-mm-dd",
"end_date": "yyyy-mm-dd",
"created_on": "yyyy-mm-dd",
"modified_on": "yyyy-mm-dd",
"budget": "number",
"cost": "number",
"author": {
"surname": "string",
"forename": "string",
"email": "string"
}
}
]
}
This endpoint retrieves RISKID projects.
HTTP Request
GET http://<riskid_api_domain>/openapi/projects
Query Parameters
These query parameters will allow you to filter the projects. If none is provided, all projects will be returned
| Parameter | Type | Required | Description |
|---|---|---|---|
| codes | array | No | Array of project codes of the specific projects that you want to receive. |
| owners | array | No | Array of owner email addresses of whom you want to have the projects. |
| authors | array | No | Array of email addresses of the author to search for. Return all projects that are created by these authors. |
| created_after | string | No | All projects after this date, date not included. Accepts date strings in yyyy-mm-dd format. So if you want every project created in 2022 this parameter needs to be "2021-12-31". If not limited by created_before, max 6 months is applied. |
| created_before | string | No | All projects before this date, date not included. Accepts date strings in yyyy-mm-dd format. So if you want every project before 2022 this needs to be "2022-01-01". If not limited by created_after, max 6 months is applied. |
Creating a project
The following request params will create a new project in RISKID
"api_name":"my_application",
"token":"a2e8805e51cb1e125f3004d59d8fdc93299fc017",
"data":{
"name": "Project ABCD",
"codes": "ABCD",
"owners": [
{
"surname": "Banner",
"forename": "Michael",
"email": "m.banner@example.com"
}
],
"description": "This is a sample project called Project ABCD",
"start_date": "2021-05-03",
"end_date": "2021-12-15",
"currency": "EUR",
"budget": "100000",
"cost": "20000"
}
"api_name":"string",
"token":"<token_string>",
"data":{
"name": "string",
"code": "string",
"owners": [
{
"surname": "string",
"forename": "string",
"email": "string"
}
],
"description": "string",
"start_date": "yyyy-mm-dd",
"end_date": "yyyy-mm-dd",
"currency": "string",
"budget": "number",
"cost": "number"
}
Return schema
{
"project":{
"id": "17",
"name": "Project ABCD",
"code": "ABCD",
"description": "This is a sample project called Project ABCD",
"folder": "Sample Projects",
"owners": [
{
"surname": "Banner",
"forename": "Michael",
"email": "m.banner@example.com",
"index": "1"
}
],
"currency": "EUR",
"start_date": "2021-05-03",
"end_date": "2021-12-15",
"created_on": "2021-03-20",
"modified_on": "2021-11-10",
"budget": "100000",
"cost": "20000",
"author": {
"surname": "Banner",
"forename": "Michael",
"email": "m.banner@example.com"
}
}
}
{
"project": {
"id": "number",
"name": "string",
"code": "string",
"description": "string",
"folder": "string",
"owners": [
{
"surname": "string",
"forename": "string",
"email": "string",
"index": "number"
}
],
"currency": "string",
"start_date": "yyyy-mm-dd",
"end_date": "yyyy-mm-dd",
"created_on": "yyyy-mm-dd",
"modified_on": "yyyy-mm-dd",
"budget": "number",
"cost": "number",
"author": {
"surname": "string",
"forename": "string",
"email": "email string"
}
}
}
This endpoint creates a new project in RISKID. It creates projects using the email used to register for the API Name.
HTTP Request
POST http://<riskid_api_domain>/openapi/projects
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| api_name | Yes | string | api_name provided by RISKID |
| token | Yes | string | A unique token retrieved using your generated token. See "Getting the token" |
| data | Yes | string | The name of the project. JSON String required |
Data Options
| Option | Required | Type | Description |
|---|---|---|---|
| name | Yes | string | The name of the project |
| code | Yes | string | A unique code that identifies the project, it must be unique within RISKID. |
| owners | Yes | array | The newly created project must have at least 1 owner. The owner is described in JSON: {"surname", "forename", "email} If the email matches to an user in RISKID, this user will be the owner. If the email fails to match to an user, we will create a new RISKID normal user to become the owner. |
| description | No | string | A text describing the project |
| start_date | No | string | Start date of the project: Date string in yyyy-mm-dd format |
| end_date | No | string | Target / End date of the project: Date string in yyyy-mm-dd format |
| currency | No | string | Currency being used for the project. Please check the full currency list here. |
| budget | No | int | The amount that is budgeted to this project. Maxed at (9999999999999) |
| cost | No | int | The amount this project has costed. (Maxed at 9999999999999) |
Modifying a project
The following request params will make changes to a project in RISKID
"api_name": "my_application",
"token": "a2e8805e51cb1e125f3004d59d8fdc93299fc017",
"code": "ABCD",
"data": {
"new_code": "EFGH",
"currency": "USD",
}
"api_name": "string",
"token": "<token_string>",
"code": "string", //The original project code
"data": {
"new_code": "string", //The new project code
"currency": "string",
}
This endpoint modifies a existing project in RISKID.
HTTP Request
PUT http://<riskid_api_domain>/openapi/projects
Query Parameters
| Params | Required | Type | Description |
|---|---|---|---|
| api_name | Yes | string | api_name provided by RISKID |
| token | Yes | string | A unique token retrieved using your. |
| code | Yes | string | Unique project code of the project you want to edit |
| data | Yes | JSON string | The name of the project |
Data Options
| Parameter | Required | Type | Description |
|---|---|---|---|
| name | No | string | The name of the project |
| new_code | No | string | A unique code that identifies the project, it must be unique within RISKID. |
| description | No | string | A text describing the project |
| start | No | string | Start date of the project: Date string in yyyy-mm-dd format |
| target | No | string | Target / End date of the project: Date string in yyyy-mm-dd format |
| currency | No | string | Currency being used for the project. Please check the full currency list here. |
| budget | No | int | The amount that is budgeted to this project. Maxed at (9999999999999) |
| cost | No | int | The amount this project has costed. (Maxed at 9999999999999) |
Handling risks
Getting risks
Sample of request params:
"api_name":"my_application",
"token":"a2e8805e51cb1e125f3004d59d8fdc93299fc017",
"projects": ["ABCD"],
"measures": true,
"comments": true,
"api_name":"string",
"token":"<token_string>",
"projects": ["string"],
"owners": ["string"], // email address
"authors": ["string"], // email address
"created_after": "yyyy-mm-dd",
"created_before": "yyyy-mm-dd",
"edited_after": "yyyy-mm-dd",
"edited_before": "yyyy-mm-dd",
"measures": "boolean",
"comments": "boolean"
The above command returns JSON schema like this:
{
"risks": [
{
"name": "Current supplier cannot provide enough raw material for the construction",
"index": "9",
"mitigation": "Accept",
"state": "Current",
"created_at": "2021-06-03 07:38:20",
"updated_at": "2021-12-10 03:51:42",
"project": {
"name": "Project ABCD",
"code": "ABCD"
},
"cost": "1000.00",
"risknumber": "20",
"current_score": [
{ "name": "probability", "value": "2", "min": "", "max": "" },
{ "name": "finance", "value": "3", "min": "", "max": "" },
{ "name": "time", "value": "2", "min": "", "max": "" }
],"residual_score": [
{ "name": "probability", "value": "2", "min": "", "max": "" },
{ "name": "finance", "value": "3", "min": "", "max": "" },
{ "name": "time", "value": "2", "min": "", "max": "" }
],
"tags": [
{
"collection_name": "Location",
"tags": [ { "label": "London" }, { "label": "Tokyo" } ]
},
{
"collection_name": "Phase",
"tags": [ { "label": "Tender" }, { "label": "Design" } ]
}
],
"goals": [
{
"collection_name": "Social",
"goals": [
{ "label": "Increased user interaction", "description": "Reach out to more users and receive more feedback" }
]
}
],
"measures": [
{
"name": "Contract extra vendors",
"index": "1",
"target": "2021-07-15 00:00:00",
"state": "Done",
"type_label": "Corrective",
"created_at": "2021-07-14 08:24:06",
"updated_at": "2021-07-17 08:37:34",
"cost": null
}
],
"comments": [
{
"text": "All mitigation measures have been placed.",
"time": "2020-11-16 07:55:10",
"active": "1",
"created_at": "2020-07-17 09:55:10",
"updated_at": "2020-07-17 09:55:10",
"user": { "full_name": "Michael Banner", "email": "m.banner@example.com" }
}
]
}
]
}
{
"risks": [
{
"name": "string",
"index": "number",
"mitigation": "string",
"state": "string",
"created_at": "date time yyyy-mm-dd HH:mm:ss",
"updated_at": "date time yyyy-mm-dd HH:mm:ss",
"project": {
"name": "string",
"code": "string"
},
"cost": "number",
"risknumber": "number",
"current_score": [
{ "name": "string", "value": "number", "min": "number", "max": "number" },
{ "name": "finance", "value": "number", "min": "number", "max": "number" },
{ "name": "time", "value": "number", "min": "number", "max": "number" }
],"residual_score": [
{ "name": "probability", "value": "number", "min": "number", "max": "number" },
{ "name": "finance", "value": "number", "min": "number", "max": "number" },
{ "name": "time", "value": "number", "min": "number", "max": "number" }
],
"tags": [
{
"collection_name": "string",
"tags": [ { "label": "string" }, { "label": "string" } ]
}
],
"goals": [
{
"collection_name": "string",
"goals": [
{ "label": "string", "description": "string" }
]
},
{
"collection_name": "string",
"goals": [
{ "label": "string", "description": "string" }
]
}
],
"measures": [
{
"name": "string",
"index": "number",
"target": "date time yyyy-mm-dd HH:mm:ss",
"state": "string",
"type": "string",
"created_at": "date time yyyy-mm-dd HH:mm:ss",
"updated_at": "date time yyyy-mm-dd HH:mm:ss",
"cost": "number"
}
],
"comments": [
{
"text": "string",
"time": "date time yyyy-mm-dd HH:mm:ss",
"active": "1",
"created_at": "date time yyyy-mm-dd HH:mm:ss",
"updated_at": "date time yyyy-mm-dd HH:mm:ss",
"user": { "full_name": "string", "email": "email string" }
}
]
}
]
}
This endpoint retrieves RISKID projects.
HTTP Request
GET http://<riskid_api_domain>/openapi/risks
Query Parameters
These query parameters will allow you to filter the projects. If none is provided, all projects will be returned
| Parameter | Type | Required | Description |
|---|---|---|---|
| projects | array | Yes | The risks of projects set in this array of project codes will be returned. |
| owners | array | No | Array of risk owner email addresses of whom you want to have the risks. |
| authors | array | No | Array of email addresses of the author to search for. Return all risks that are created by these authors. |
| created_after | date string | No | All risks after this date, date not included. Accepts date strings in yyyy-mm-dd format. So if you want every project created in 2022 this parameter needs to be "2021-12-31". If not limited by created_before, max 6 months is applied. |
| created_before | date string | No | All risks before this date, date not included. Accepts date strings in yyyy-mm-dd format. So if you want every project before 2022 this needs to be "2022-01-01". If not limited by created_after, max 6 months is applied. |
| edited_after | date string | No | All risks after this date, date not included. Accepts date strings in yyyy-mm-dd format. So if you want every project created in 2022 this parameter needs to be "2021-12-31". If not limited by created_before, max 6 months is applied. |
| edited_before | date string | No | All risks before this date, date not included. Accepts date strings in yyyy-mm-dd format. So if you want every project before 2022 this needs to be "2022-01-01". If not limited by created_after, max 6 months is applied. |
| measures | boolean | No | If set to true it will also return the measures attached to the risk. |
| comments | boolean | No | If set to true it will also return the comments attached to the risk. |
Appendices
Errors
The RISKID API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your API key is wrong. |
| 403 | Forbidden -- The object requested is hidden for administrators only. |
| 404 | Not Found -- The specified object could not be found. |
| 405 | Method Not Allowed -- You tried to access a object with an invalid method. |
| 406 | Couldn't perform request -- We couldn't perform your request. Please try something else. |
| 410 | Gone -- The object requested has been removed from our servers. |
| 418 | I'm a teapot. |
| 429 | Too Many Requests -- You're requesting too many resources! Slow down! |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Currency list options
The RISKID API uses the following default currency list:
| Currency Code | Full Description |
|---|---|
| ARS | Argentine Peso |
| AUD | Australian Dollar |
| BBD | Barbados Dollar |
| BGN | Bulgarian Lev |
| BMD | Bermudan Dollar |
| BRL | Brazilian Real |
| BSD | Bahamian Dollar |
| CAD | Canadian Dollar |
| CHF | Swiss Franc |
| CLP | Chilean Peso |
| CNY | Chinese Yuan |
| CZK | Czech Koruna |
| DKK | Danish Krone |
| DZD | Algerian Dinar |
| EUR | Euro |
| GBP | British Pound Sterling |
| HKD | Hong Kong Dollar |
| HUF | Hungarian Forint |
| IDR | Indonesian Rupiah |
| ILS | Israeli New Shekel |
| INR | Indian Rupee |
| ISK | Icelandic Króna |
| JOD | Jordanian Dinar |
| JPY | Japanese Yen |
| KRW | South Korean Won |
| LBP | Lebanese Pound |
| MXP | Mexican Peso |
| MYR | Malaysian Ringgit |
| NOK | Norwegian Krone |
| NZD | New Zealand Dollar |
| PHP | Philippine Peso |
| PKR | Pakistani Rupee |
| PLN | Polish Zloty |
| QAR | Qatari Riyal |
| RON | Romanian Leu |
| RUB | Russian Ruble |
| SAR | Saudi Riyal |
| SDG | Sudanese Pound |
| SEK | Swedish Krona |
| SGD | Singapore Dollar |
| THB | Thai Baht |
| TWD | New Taiwan Dollar |
| TRY | Turkish Lira |
| USD | US Dollar |
| VEB | Venezuelan Bolivar |
| ZAR | South African Rand |