Latest update: 22.03.2024

This document describes each endpoint available with the Efecte REST API v1. This is a technical interface description - please find the REST API overview here. 

Accessing Data Cards

GET /dc/{templateCode}/data

Get all data cards by template code – returns paginated list of data card-information by given template.

REQUEST

PATH PARAMETERS

QUERY PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data?filter=%24status%24%20%3D%20%2702%20-%20Solving%27&selectedAttributes=subject%2Cstatus&limit=2&filterId=0&dataCards=true

GET /dc/{templateCode}/data/stream

Returns all available data cards by streaming. For complex and heavy operations streaming results could provide faster and more efficient results than getting paginated data.

REQUEST

PATH PARAMETERS

QUERY PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data?filter=%24status%24%20%3D%20%2702%20-%20Solving%27&selectedAttributes=subject%2Cstatus&limit=2&filterId=0&dataCards=true

PUT /dc/{templateCode}/data

Create or edit multiple data cards 

REQUEST

PATH PARAMETERS

Example

PUT https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data

BODY

[
 {
   "folderCode": "incident_management",
   "dataCardId": "12345",
   "data": {
     "description": {
       "values": [
         {
           "value": "Updating incident"
         }
       ]
     },
     "description": {
       "values": [
         {
           "value": "Description"
         }
       ]
     }
   }
 },
 {
   "folderCode": "incident_management",
   "data": {
     "description": {
       "values": [
         {
           "value": "Creating a new incident"
         }
       ]
     }
   }
 }
]

POST /dc/{templateCode}/data

Create a new data card

REQUEST

PATH PARAMETERS

QUERY PARAMETERS

Example

POST https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data

BODY

 {
   "folderCode": "incident_management",
   "data": {
     "description": {
       "values": [
         {
           "value": "Creating incident"
         }
       ]
     },
     "description": {
       "values": [
         {
           "value": "Description"
         }
       ]
     }
   }
 }

GET /dc/{templateCode}/data/{dataCardId}

Get a single data card

REQUEST

PATH PARAMETERS

QUERY PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345

DELETE /dc/{templateCode}/data/{dataCardId}

Delete a single data card

REQUEST

PATH PARAMETERS

Example

DELETE https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345

PATCH /dc/{templateCode}/data/{dataCardId}

Edit existing data card

REQUEST

PATH PARAMETERS

QUERY PARAMETERS

Example

PATCH https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345

BODY

{
   "folderCode": "incident_management",
   "data": {
     "description": {
       "values": [
         {
           "value": "Creating incident"
         }
       ]
     },
     "description": {
       "values": [
         {
           "value": "Description"
         }
       ]
     }
   }
 }

GET /dc/{templateCode}/data/{dataCardId}/{attributeCode}

Get attribute from data card

REQUEST

PATH PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject

PUT /dc/{templateCode}/data/{dataCardId}/{attributeCode}

Update attribute from data card

REQUEST

PATH PARAMETERS

Example

PUT https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject

BODY

{
 "values": [
   {
     "value":"Updating subject"
   }
 ]
}

POST /dc/{templateCode}/data/{dataCardId}/{attributeCode}

Add value to attribute from data card

REQUEST

PATH PARAMETERS
 

Example

POST https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject

BODY

{
 "values": [
   {
     "value":"Adding value to subject"
   }
 ]
}

DELETE /dc/{templateCode}/data/{dataCardId}/{attributeCode}

Clear value of attribute from data card.

REQUEST

PATH PARAMETERS

Example

DELETE https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject

GET /dc/{templateCode}/data/{dataCardId}/{attributeCode}/file/{locationOfExternalData}

Download attachment from data card.

REQUEST

PATH PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject/file/20210512_01

POST /dc/{templateCode}/data/{dataCardId}/{attributeCode}/file

Upload attachment to data card.

REQUEST

PATH PARAMETERS

Example

POST https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject/file/20210512_01 -H "Content-Type: multipart/form-data" -F "fileName=example.png" -F "fileUpload=example.png;type=image/png"

Accessing Templates

GET /dc

Get list of all templates.

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc

GET /dc/{templateCode}

Get template by code.

REQUEST

PATH PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident

How to Test the Interface

GET /echo

Returns the content of "message" query parameter. For testing purposes.

REQUEST

QUERY PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/echo?message=Hello%20world

GET /echo/jwt

Returns the content of "message" query parameter if JWT-token is valid. For testing purposes.

REQUEST

QUERY PARAMETERS

Example

GET https://efecte.efectecloud.com/rest-api/itsm/v1/echo?message=Hello%20world

Troubleshooting

REST API Errors

In case of any errors - caused for example, by failed authorization, erroneous parameters or a badly formatted query – the API will respond with standardized error-response:

 {
 "code": 401,
 "message": "Token was empty or not provided. Token should be provided in AUTHORIZATION header.",
 "error": "Unauthorized",
 "url": "https://efecte.efectecloud.com/itsm/api/v1/dc/incident/data?limit=50&filterId=0",
 "timestamp": "2021-12-21T11:41:22Z"
}

The response will always include “code”, “error”, “url” and “timestamp” and in most of the cases “message”, giving details about the underlying issue.

Possible Errors

Can’t acquire JWT-token from login-endpoint

To get a JWT-token, the user used for login needs to have a role assigned with permission to ‘External API’ -module. If the user does not have the permissions for the External API-module, the login-endpoint response will contain information about insufficient permissions.
If you get unauthorized-response even though the username and password are correct and the role has the right permissions, make sure the account is local ESM-account. 

Attribute isn’t nullable and if you send a “” as value, field isn't empty anymore

String-type attribute contains the following options: string |number | date

With StaticValue: 

• Value - string
• code - string
• nullable - True

Therefore, if you want empty attribute value via REST API, use this syntax:

"email": {
           "values": [
               {
                   "value": null
               }
           ]
       }