Introduction to the ITSM API 

Start with our Core API docs for an introduction to the Kloudless API and more information on connecting user accounts and performing API requests.

Once an account is connected to your application, your application can perform API requests to the ITSM API endpoints listed below.

Here are the supported services, listed with service identifiers:

  • ITSM Services
    • ServiceNow: servicenow

The ITSM API has the following available object types:

  • incident

  • problem

  • change

  • article

  • asset

Each of these objects types is documented below, with their standard Kloudless attributes listed.

In addition, a generic objects endpoint for custom service-specific data or objects not available via a Kloudless ITSM API endpoint is available.


ITSM Incidents 

An incident represents any interruption in normal service operation.

  • id Unique identifier for the Incident

  • change Identifier of the related Change request object

  • problem Identifier of the related Problem object

  • requester User responsible for creating this Incident

  • responder User responding to this incident

  • active Whether the Incident is active or not

  • assignee User assigned to this Incident

  • category Category of the Incident

  • due_date Due date of the Incident

  • escalation Escalation of the Incident

  • impact Effect on business {low, medium, high}

  • priority Importance for service desk to address this incident {low, medium, high, critical}

  • status State of the Incident

  • urgency Extent to which resolution can bear delay {low, medium, high}

  • created ISO 8601 timestamp indicating when the incident was created

  • modified ISO 8601 timestamp indicating when the incident was modified

  • description Details of the Incident

  • type Type of object. always incident

  • api Always itsm

  • raw Underlying object retrieved from the service with all fields, including custom ones

  • href The absolute URL to get the object’s metadata.

List Incidents 

list incidentsGET /accounts/{account_id}/itsm/incidents{?page_size,page}

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of incident objects

  • type Always object_list

  • api Always itsm

  • Parameters
  • page_size
    number (optional) Default: 10 

    Number of objects in each page. For some services, the page_size isn’t respected. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "total": 1,
      "count": 1,
      "page": 1,
      "next_page": null,
      "objects": [
        {
          "api": "itsm",
          "assignee": {
            "type": "user",
            "api": "team",
            "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
            "name": "Vinod Chandru",
            "email": "vinod@kloudless.com"
          },
          "category": "hardware",
          "created": "2017-11-27T09:01:33Z",
          "description": "User can't access email on mail.company.com.",
          "escalation": 0,
          "id": "Fc1GyHgRrEKK0zzPXPyj1MB2UgJlb3Bx72LJ-npTpEWHy4sZmnXUiX3pY-tDyHWwl",
          "impact": "high",
          "modified": "2017-11-27T09:01:33Z",
          "priority": "medium",
          "problem": "F3iGnrn9YFNJ7sqGfh2ofTsF1Hv6WCFdQs8UAZKZC5f0xIRY81hy872UNWxPncRFT",
          "due_date": "2017-10-04T20:15:37Z",
          "requester": {
            "type": "user",
            "api": "team",
            "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDY=",
            "name": "Timothy Liu",
            "email": "timothy@kloudless.com"
          },
          "status": 1,
          "type": "incident",
          "urgency": "medium",
          "href": "https://api.kloudless.com/v1/accounts/123/itsm/incidents/Fc1GyHgRrEKK0zzPXPyj1MB2UgJlb3Bx72LJ-npTpEWHy4sZmnXUiX3pY-tDyHWwl"
        }
      ],
      "type": "object_list",
      "api": "itsm"
    }

Create an Incident 

create an incidentPOST /accounts/{account_id}/itsm/incident

To create an incident, perform a POST request with a JSON object with the following attributes:

  • change Identifier of the related Change request object

  • problem Identifier of the related Problem object

  • requester User responsible for creating this Incident

  • responder User responding to this incident

  • active Whether the Incident is active or not

  • assignee User assigned to this Incident

  • category Category of the Incident

  • due_date Due date of the Incident

  • escalation Escalation of the Incident

  • impact Effect on business {low, medium, high}

  • priority Importance for service desk to address this incident {low, medium, high, critical}

  • status State of the Incident

  • urgency Extent to which resolution can bear delay {low, medium, high}

  • description Details of the Incident

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/itsm/incidents' \
    -XPOST -d '{
        "category": "hardware",
        "due_date": "2017-10-04T20:15:37Z",
        "description": "User can't access email on mail.company.com.",
        "impact": "high",
        "assignee": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "priority": "medium",
        "urgency": "medium",
        "requester": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDY=",
        "active": true,
        "problem": "F3iGnrn9YFNJ7sqGfh2ofTsF1Hv6WCFdQs8UAZKZC5f0xIRY81hy872UNWxPncRFT",
        "escalation": 0
    }'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "category": "hardware",
      "due_date": "2017-10-04T20:15:37Z",
      "description": "User can't access email on mail.company.com.",
      "impact": "high",
      "assignee": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
      "priority": "medium",
      "urgency": "medium",
      "requester": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDY=",
      "problem": "F3iGnrn9YFNJ7sqGfh2ofTsF1Hv6WCFdQs8UAZKZC5f0xIRY81hy872UNWxPncRFT",
      "escalation": 0
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "api": "itsm",
      "assignee": {
        "type": "user",
        "api": "team",
        "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "name": "Vinod Chandru",
        "email": "vinod@kloudless.com"
      },
      "category": "hardware",
      "created": "2017-11-27T09:01:33Z",
      "description": "User can't access email on mail.company.com.",
      "escalation": 0,
      "id": "Fc1GyHgRrEKK0zzPXPyj1MB2UgJlb3Bx72LJ-npTpEWHy4sZmnXUiX3pY-tDyHWwl",
      "impact": "high",
      "modified": "2017-11-27T09:01:33Z",
      "priority": "medium",
      "problem": "F3iGnrn9YFNJ7sqGfh2ofTsF1Hv6WCFdQs8UAZKZC5f0xIRY81hy872UNWxPncRFT",
      "due_date": "2017-10-04T20:15:37Z",
      "requester": {
        "type": "user",
        "api": "team",
        "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDY=",
        "name": "Timothy Liu",
        "email": "timothy@kloudless.com"
      },
      "status": 1,
      "type": "incident",
      "urgency": "medium",
      "href": "https://api.kloudless.com/v1/accounts/123/itsm/incidents/Fc1GyHgRrEKK0zzPXPyj1MB2UgJlb3Bx72LJ-npTpEWHy4sZmnXUiX3pY-tDyHWwl"
    }

Retrieve an Incident 

retrieve an IncidentGET /accounts/{account_id}/itsm/incidents/{incident_id}
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "api": "itsm",
      "assignee": {
        "type": "user",
        "api": "team",
        "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "name": "Vinod Chandru",
        "email": "vinod@kloudless.com"
      },
      "category": "hardware",
      "created": "2017-11-27T09:01:33Z",
      "description": "User can't access email on mail.company.com.",
      "escalation": 0,
      "id": "Fc1GyHgRrEKK0zzPXPyj1MB2UgJlb3Bx72LJ-npTpEWHy4sZmnXUiX3pY-tDyHWwl",
      "impact": "high",
      "modified": "2017-11-27T09:01:33Z",
      "priority": "medium",
      "problem": "F3iGnrn9YFNJ7sqGfh2ofTsF1Hv6WCFdQs8UAZKZC5f0xIRY81hy872UNWxPncRFT",
      "due_date": "2017-10-04T20:15:37Z",
      "requester": {
        "type": "user",
        "api": "team",
        "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDY=",
        "name": "Timothy Liu",
        "email": "timothy@kloudless.com"
      },
      "status": 1,
      "type": "incident",
      "urgency": "medium",
      "href": "https://api.kloudless.com/v1/accounts/123/itsm/incidents/Fc1GyHgRrEKK0zzPXPyj1MB2UgJlb3Bx72LJ-npTpEWHy4sZmnXUiX3pY-tDyHWwl"
    }

Update an Incident 

update an incidentPATCH /accounts/{account_id}/itsm/incidents/{incident_id}

To update an incident, create a JSON object with any of the following properties:

  • change Identifier of the related Change request object

  • problem Identifier of the related Problem object

  • requester User responsible for creating this Incident

  • responder User responding to this Incident

  • active Whether the Incident is active or not

  • assignee User assigned to this Incident

  • category Category of the Incident

  • due_date Due date of the Incident

  • escalation Escalation of the Incident

  • impact Effect on business {low, medium, high}

  • priority Importance for service desk to address this incident {low, medium, high, critical}

  • status State of the Incident

  • urgency Extent to which resolution can bear delay {low, medium, high}

  • description Details of the Incident

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "priority": "medium",
        "description": "User can't access email on mail.company.com."
    }' \
    'https://api.kloudless.com/v1/accounts/123/itsm/incidents/Fc1GyHgRrEKK0zzPXPyj1MB2UgJlb3Bx72LJ-npTpEWHy4sZmnXUiX3pY-tDyHWwl
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "priority": "medium",
      "description": "User can't access email on mail.company.com."
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "api": "itsm",
      "assignee": {
        "type": "user",
        "api": "team",
        "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "name": "Vinod Chandru",
        "email": "vinod@kloudless.com"
      },
      "category": "hardware",
      "created": "2017-11-27T09:01:33Z",
      "description": "User can't access email on mail.company.com.",
      "escalation": 0,
      "id": "Fc1GyHgRrEKK0zzPXPyj1MB2UgJlb3Bx72LJ-npTpEWHy4sZmnXUiX3pY-tDyHWwl",
      "impact": "high",
      "modified": "2017-11-27T09:01:33Z",
      "priority": "medium",
      "problem": "F3iGnrn9YFNJ7sqGfh2ofTsF1Hv6WCFdQs8UAZKZC5f0xIRY81hy872UNWxPncRFT",
      "due_date": "2017-10-04T20:15:37Z",
      "requester": {
        "type": "user",
        "api": "team",
        "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDY=",
        "name": "Timothy Liu",
        "email": "timothy@kloudless.com"
      },
      "status": 1,
      "type": "incident",
      "urgency": "medium",
      "href": "https://api.kloudless.com/v1/accounts/123/itsm/incidents/Fc1GyHgRrEKK0zzPXPyj1MB2UgJlb3Bx72LJ-npTpEWHy4sZmnXUiX3pY-tDyHWwl"
    }

Delete an Incident 

delete an incidentDELETE /accounts/{account_id}/itsm/incidents/{incident_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE 'https://api.kloudless.com/v1/accounts/123/itsm/incidents/Fc1GyHgRrEKK0zzPXPyj1MB2UgJlb3Bx72LJ-npTpEWHy4sZmnXUiX3pY-tDyHWwl'
  • Response  204

ITSM Problems 

A problem is the cause of an error in the IT infrastructure that is usually reported as occurrences of related incidents.

  • id Unique identifier for the Problem

  • change Identifier of related Change request object

  • incident Identifier of related Incident object

  • requester User responsible for creating this Problem

  • responder User responding to this problem

  • active Whether the Problem is active or not

  • assignee User assigned to this Problem

  • category Category of the Problem

  • due_date Due date of the Problem

  • escalation Escalation of the Problem

  • impact Effect on business {low, medium, high}

  • priority Importance for service desk to address this problem {low, medium, high, critical}

  • status State of the Problem

  • urgency Extent to which resolution can bear delay {low, medium, high}

  • created ISO 8601 timestamp indicating when the object was created

  • modified ISO 8601 timestamp indicating when the object was modified

  • description Details of the Problem

  • type Type of object. always problem

  • api Always itsm

  • raw Underlying object retrieved from the service with all fields, including custom ones

  • href The absolute URL to get the object’s metadata.

List Problems 

list problemsGET /accounts/{account_id}/itsm/problems{?page_size,page}

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of problem objects

  • type Always object_list

  • api Always itsm

  • Parameters
  • page_size
    number (optional) Default: 10 

    Number of objects in each page. For some services, the page_size isn’t respected. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "total": 1,
      "count": 1,
      "page": 1,
      "next_page": null,
      "objects": [
        {
          "active": true,
          "api": "itsm",
          "assignee": {
            "type": "user",
            "api": "team",
            "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
            "name": "Vinod Chandru",
            "email": "vinod@kloudless.com"
          },
          "category": "hardware",
          "incident": "FmDt08lzD96wzraSzWVGMwKBJxJ-VChCcGzeQp4YwuPT_DHszkw2rL1WmvBfy6lyQ",
          "created": "2017-11-30T09:22:52Z",
          "description": "SP2 is causing several applications not to work anymore.",
          "escalation": 0,
          "id": "FctP2kuVA1Fr8BHwNlAVMVySl6wfF-oV9y304Ymr8iCcy2xGW8XYdOJN6TxzlpFuY",
          "impact": "high",
          "modified": "2017-11-30T09:22:52Z",
          "priority": "medium",
          "type": "problem",
          "urgency": "medium",
          "href": "https://api.kloudless.com/v1/accounts/123/itsm/problems/FctP2kuVA1Fr8BHwNlAVMVySl6wfF-oV9y304Ymr8iCcy2xGW8XYdOJN6TxzlpFuY"
        }
      ],
      "type": "object_list",
      "api": "itsm"
    }

Create a Problem 

create a problemPOST /accounts/{account_id}/itsm/problem

To create a problem, perform a POST request with a JSON object with the following attributes:

  • change Identifier of related Change request object

  • incident Identifier of related Incident object

  • requester User responsible for creating this Problem

  • responder User responding to this problem

  • active Whether the Problem is active or not

  • assignee User assigned to this Problem

  • category Category of the Problem

  • due_date Due date of the Problem

  • escalation Escalation of the Problem

  • impact Effect on business {low, medium, high}

  • priority Importance for service desk to address this problem {low, medium, high, critical}

  • status State of the Problem

  • urgency Extent to which resolution can bear delay {low, medium, high}

  • description Details of the Problem

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/itsm/problems' \
    -XPOST -d '{
        "incident": "FmDt08lzD96wzraSzWVGMwKBJxJ-VChCcGzeQp4YwuPT_DHszkw2rL1WmvBfy6lyQ",
        "category": "hardware",
        "due_date": "2017-10-04T20:15:37Z",
        "description": "SP2 is causing several applications not to work anymore.",
        "impact": "high",
        "assignee": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "priority": "medium",
        "urgency": "medium",
        "requester": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDY=",
        "problem": "F3iGnrn9YFNJ7sqGfh2ofTsF1Hv6WCFdQs8UAZKZC5f0xIRY81hy872UNWxPncRFT",
        "escalation": 0
    }'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "incident": "FmDt08lzD96wzraSzWVGMwKBJxJ-VChCcGzeQp4YwuPT_DHszkw2rL1WmvBfy6lyQ",
      "category": "hardware",
      "due_date": "2017-10-04T20:15:37Z",
      "description": "SP2 is causing several applications not to work anymore.",
      "impact": "high",
      "assignee": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
      "priority": "medium",
      "urgency": "medium",
      "requester": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDY=",
      "problem": "F3iGnrn9YFNJ7sqGfh2ofTsF1Hv6WCFdQs8UAZKZC5f0xIRY81hy872UNWxPncRFT",
      "escalation": 0
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "active": true,
      "api": "itsm",
      "assignee": {
        "type": "user",
        "api": "team",
        "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "name": "Vinod Chandru",
        "email": "vinod@kloudless.com"
      },
      "category": "hardware",
      "incident": "FmDt08lzD96wzraSzWVGMwKBJxJ-VChCcGzeQp4YwuPT_DHszkw2rL1WmvBfy6lyQ",
      "created": "2017-11-30T09:22:52Z",
      "description": "SP2 is causing several applications not to work anymore.",
      "escalation": 0,
      "id": "FctP2kuVA1Fr8BHwNlAVMVySl6wfF-oV9y304Ymr8iCcy2xGW8XYdOJN6TxzlpFuY",
      "impact": "high",
      "modified": "2017-11-30T09:22:52Z",
      "priority": "medium",
      "type": "problem",
      "urgency": "medium",
      "href": "https://api.kloudless.com/v1/accounts/123/itsm/problems/FctP2kuVA1Fr8BHwNlAVMVySl6wfF-oV9y304Ymr8iCcy2xGW8XYdOJN6TxzlpFuY"
    }

Retrieve a Problem 

retrieve a ProblemGET /accounts/{account_id}/itsm/problems/{problem_id}
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "active": true,
      "api": "itsm",
      "assignee": {
        "type": "user",
        "api": "team",
        "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "name": "Vinod Chandru",
        "email": "vinod@kloudless.com"
      },
      "category": "hardware",
      "incident": "FmDt08lzD96wzraSzWVGMwKBJxJ-VChCcGzeQp4YwuPT_DHszkw2rL1WmvBfy6lyQ",
      "created": "2017-11-30T09:22:52Z",
      "description": "SP2 is causing several applications not to work anymore.",
      "escalation": 0,
      "id": "FctP2kuVA1Fr8BHwNlAVMVySl6wfF-oV9y304Ymr8iCcy2xGW8XYdOJN6TxzlpFuY",
      "impact": "high",
      "modified": "2017-11-30T09:22:52Z",
      "priority": "medium",
      "type": "problem",
      "urgency": "medium",
      "href": "https://api.kloudless.com/v1/accounts/123/itsm/problems/FctP2kuVA1Fr8BHwNlAVMVySl6wfF-oV9y304Ymr8iCcy2xGW8XYdOJN6TxzlpFuY"
    }

Update a Problem 

update a problemPATCH /accounts/{account_id}/itsm/problems/{problem_id}

To update a problem, create a JSON object with any of the following properties:

  • change Identifier of related Change request object

  • incident Identifier of related Incident object

  • requester User responsible for creating this Problem

  • responder User responding to this problem

  • active Whether the Problem is active or not

  • assignee User assigned to this Problem

  • category Category of the Problem

  • due_date Due date of the Problem

  • escalation Escalation of the Problem

  • impact Effect on business {low, medium, high}

  • priority Importance for service desk to address this problem {low, medium, high, critical}

  • status State of the Problem

  • urgency Extent to which resolution can bear delay {low, medium, high}

  • description Details of the Problem

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "description": "SP2 is causing several applications not to work anymore.",
        "impact": "high"
    }' \
    'https://api.kloudless.com/v1/accounts/123/itsm/problems/FctP2kuVA1Fr8BHwNlAVMVySl6wfF-oV9y304Ymr8iCcy2xGW8XYdOJN6TxzlpFuY
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "description": "SP2 is causing several applications not to work anymore.",
      "impact": "high"
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "active": true,
      "api": "itsm",
      "assignee": {
        "type": "user",
        "api": "team",
        "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "name": "Vinod Chandru",
        "email": "vinod@kloudless.com"
      },
      "category": "hardware",
      "incident": "FmDt08lzD96wzraSzWVGMwKBJxJ-VChCcGzeQp4YwuPT_DHszkw2rL1WmvBfy6lyQ",
      "created": "2017-11-30T09:22:52Z",
      "description": "SP2 is causing several applications not to work anymore.",
      "escalation": 0,
      "id": "FctP2kuVA1Fr8BHwNlAVMVySl6wfF-oV9y304Ymr8iCcy2xGW8XYdOJN6TxzlpFuY",
      "impact": "high",
      "modified": "2017-11-30T09:22:52Z",
      "priority": "medium",
      "type": "problem",
      "urgency": "medium",
      "href": "https://api.kloudless.com/v1/accounts/123/itsm/problems/FctP2kuVA1Fr8BHwNlAVMVySl6wfF-oV9y304Ymr8iCcy2xGW8XYdOJN6TxzlpFuY"
    }

Delete a Problem 

delete a problemDELETE /accounts/{account_id}/itsm/problems/{problem_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE 'https://api.kloudless.com/v1/accounts/123/itsm/problems/FctP2kuVA1Fr8BHwNlAVMVySl6wfF-oV9y304Ymr8iCcy2xGW8XYdOJN6TxzlpFuY'
  • Response  204

ITSM Changes 

A change is any modification to the IT environment. A change illustrates the life-cycle of the people-side of change.

  • id Unique identifier for the Change

  • problem Identifier of related Problem object

  • incident Identifier of related Incident object

  • requester User responsible for creating this Change

  • responder User responding to this change

  • active Whether the Change is active or not

  • assignee User assigned to this Change

  • category Category of the Change

  • end_date End date of the Change

  • escalation Escalation of the Change

  • impact Effect on business {low, medium, high}

  • priority Importance for service desk to address this change {low, medium, high, critical}

  • risk Risk of the Change

  • start_date Start date of Change

  • status State of the Change

  • urgency Extent to which resolution can bear delay {low, medium, high}

  • created ISO 8601 timestamp indicating when the object was created

  • modified ISO 8601 timestamp indicating when the object was modified

  • description Details of the Change

  • type Type of object. Always “change”

  • api Always itsm

  • raw Underlying object retrieved from the service with all fields, including custom ones

  • href The absolute URL to get the object’s metadata.

List Changes 

list changesGET /accounts/{account_id}/itsm/changes{?page_size,page}

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of change objects

  • type Always object_list

  • api Always itsm

  • Parameters
  • page_size
    number (optional) Default: 10 

    Number of objects in each page. For some services, the page_size isn’t respected. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "total": 1,
      "count": 1,
      "page": 1,
      "next_page": null,
      "objects": [
        {
          "active": true,
          "api": "itsm",
          "assignee": {
            "type": "user",
            "api": "team",
            "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
            "name": "Vinod Chandru",
            "email": "vinod@kloudless.com"
          },
          "category": "Software",
          "created": "2017-12-01T09:43:50Z",
          "description": "We are going to put another 100 GB drive on the floor 2 server",
          "escalation": 1,
          "id": "FpTGcOSmGFokkYe0ruf4SuQdJ7JjACRI6S4mg6myJ-uR9t3hxp1XVtEMBxP6E1je9",
          "impact": "low",
          "modified": "2017-12-01T09:43:50Z",
          "priority": "high",
          "start_date": "2017-12-01T15:10:00Z",
          "end_date": "2017-12-01T15:20:00Z",
          "status": 0,
          "type": "change",
          "urgency": "high",
          "href": "https://api.kloudless.com/v1/accounts/123/itsm/changes/FpTGcOSmGFokkYe0ruf4SuQdJ7JjACRI6S4mg6myJ-uR9t3hxp1XVtEMBxP6E1je9"
        }
      ],
      "type": "object_list",
      "api": "itsm"
    }

Create a Change 

create a changePOST /accounts/{account_id}/itsm/change

To create a change, perform a POST request with a JSON object with the following attributes:

  • problem Identifier of related Problem object

  • incident Identifier of related Incident object

  • requester User responsible for creating this Change

  • responder User responding to this change

  • active Whether the Change is active or not

  • assignee User assigned to this Change

  • category Category of the Change

  • end_date End date of the Change

  • escalation Escalation of the Change

  • impact Effect on business {low, medium, high}

  • priority Importance for service desk to address this change {low, medium, high, critical}

  • risk Risk of the Change

  • start_date Start date of Change

  • status State of the Change

  • urgency Extent to which resolution can bear delay {low, medium, high}

  • description Details of the Change

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/itsm/changes' \
    -XPOST -d '{
        "category": "Software",
        "impact": "low",
        "description": "We are going to put another 100 GB drive on the floor 2 server",
        "start_date": "2017-12-01T15:10:00Z",
        "end_date": "2017-12-01T15:20:00Z",
        "priority": "high",
        "assignee": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "incident": "",
        "status": 0,
        "urgency": "high",
        "problem": "",
        "escalation": 1 
    }'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "category": "Software",
      "impact": "low",
      "description": "We are going to put another 100 GB drive on the floor 2 server",
      "start_date": "2017-12-01T15:10:00Z",
      "end_date": "2017-12-01T15:20:00Z",
      "priority": "high",
      "assignee": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
      "incident": "",
      "status": 0,
      "urgency": "high",
      "problem": "",
      "escalation": 1
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "active": true,
      "api": "itsm",
      "assignee": {
        "type": "user",
        "api": "team",
        "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "name": "Vinod Chandru",
        "email": "vinod@kloudless.com"
      },
      "category": "Software",
      "created": "2017-12-01T09:43:50Z",
      "description": "We are going to put another 100 GB drive on the floor 2 server",
      "escalation": 1,
      "id": "FpTGcOSmGFokkYe0ruf4SuQdJ7JjACRI6S4mg6myJ-uR9t3hxp1XVtEMBxP6E1je9",
      "impact": "low",
      "modified": "2017-12-01T09:43:50Z",
      "priority": "high",
      "start_date": "2017-12-01T15:10:00Z",
      "end_date": "2017-12-01T15:20:00Z",
      "status": 0,
      "type": "change",
      "urgency": "high",
      "href": "https://api.kloudless.com/v1/accounts/123/itsm/changes/FpTGcOSmGFokkYe0ruf4SuQdJ7JjACRI6S4mg6myJ-uR9t3hxp1XVtEMBxP6E1je9"
    }

Retrieve a Change 

retrieve a ChangeGET /accounts/{account_id}/itsm/changes/{change_id}
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "active": true,
      "api": "itsm",
      "assignee": {
        "type": "user",
        "api": "team",
        "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "name": "Vinod Chandru",
        "email": "vinod@kloudless.com"
      },
      "category": "Software",
      "created": "2017-12-01T09:43:50Z",
      "description": "We are going to put another 100 GB drive on the floor 2 server",
      "escalation": 1,
      "id": "FpTGcOSmGFokkYe0ruf4SuQdJ7JjACRI6S4mg6myJ-uR9t3hxp1XVtEMBxP6E1je9",
      "impact": "low",
      "modified": "2017-12-01T09:43:50Z",
      "priority": "high",
      "start_date": "2017-12-01T15:10:00Z",
      "end_date": "2017-12-01T15:20:00Z",
      "status": 0,
      "type": "change",
      "urgency": "high",
      "href": "https://api.kloudless.com/v1/accounts/123/itsm/changes/FpTGcOSmGFokkYe0ruf4SuQdJ7JjACRI6S4mg6myJ-uR9t3hxp1XVtEMBxP6E1je9"
    }

Update a Change 

update a changePATCH /accounts/{account_id}/itsm/changes/{change_id}

To update a change, create a JSON object with any of the following properties:

  • problem Identifier of related Problem object

  • incident Identifier of related Incident object

  • requester User responsible for creating this Change

  • responder User responding to this change

  • active Whether the Change is active or not

  • assignee User assigned to this Change

  • category Category of the Change

  • end_date End date of the Change

  • escalation Escalation of the Change

  • impact Effect on business {low, medium, high}

  • priority Importance for service desk to address this change {low, medium, high, critical}

  • risk Risk of the Change

  • start_date Start date of Change

  • status State of the Change

  • urgency Extent to which resolution can bear delay {low, medium, high}

  • description Details of the Change

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "escalation": 1,
        "impact": "low"
    }' \
    'https://api.kloudless.com/v1/accounts/123/itsm/changes/FpTGcOSmGFokkYe0ruf4SuQdJ7JjACRI6S4mg6myJ-uR9t3hxp1XVtEMBxP6E1je9
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "escalation": 1,
      "impact": "low"
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "active": true,
      "api": "itsm",
      "assignee": {
        "type": "user",
        "api": "team",
        "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "name": "Vinod Chandru",
        "email": "vinod@kloudless.com"
      },
      "category": "Software",
      "created": "2017-12-01T09:43:50Z",
      "description": "We are going to put another 100 GB drive on the floor 2 server",
      "escalation": 1,
      "id": "FpTGcOSmGFokkYe0ruf4SuQdJ7JjACRI6S4mg6myJ-uR9t3hxp1XVtEMBxP6E1je9",
      "impact": "low",
      "modified": "2017-12-01T09:43:50Z",
      "priority": "high",
      "start_date": "2017-12-01T15:10:00Z",
      "end_date": "2017-12-01T15:20:00Z",
      "status": 0,
      "type": "change",
      "urgency": "high",
      "href": "https://api.kloudless.com/v1/accounts/123/itsm/changes/FpTGcOSmGFokkYe0ruf4SuQdJ7JjACRI6S4mg6myJ-uR9t3hxp1XVtEMBxP6E1je9"
    }

Delete a Change 

delete a changeDELETE /accounts/{account_id}/itsm/changes/{change_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE 'https://api.kloudless.com/v1/accounts/123/itsm/changes/FpTGcOSmGFokkYe0ruf4SuQdJ7JjACRI6S4mg6myJ-uR9t3hxp1XVtEMBxP6E1je9'
  • Response  204

ITSM Articles 

An article is a knowledge base article to share information across the organization.

  • id Unique identifier for the Article

  • author User responsible for creating this Article

  • active Whether the Article is active or not

  • category Category of the Article

  • rating Rating of the Article

  • roles Who can see the Article

  • topic Topic of the Article

  • text Text of the Article

  • created ISO 8601 timestamp indicating when the object was created

  • modified ISO 8601 timestamp indicating when the object was modified

  • description Details of the Article

  • type Type of object. Always “article”

  • api Always itsm

  • raw Underlying object retrieved from the service with all fields, including custom ones

  • href The absolute URL to get the object’s metadata.

List Articles 

list articlesGET /accounts/{account_id}/itsm/articles{?page_size,page}

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of article objects

  • type Always object_list

  • api Always itsm

  • Parameters
  • page_size
    number (optional) Default: 10 

    Number of objects in each page. For some services, the page_size isn’t respected. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "total": 1,
      "count": 1,
      "page": 1,
      "next_page": null,
      "objects": [
        {
          "active": true,
          "api": "itsm",
          "author": {
            "type": "user",
            "api": "team",
            "id": "uNDZkMTRmMDRhOWZlMTk4MTAxNDJlNDBjNmIwNzE1MTI=",
            "name": "David Thorman",
            "email": "dthorman@kloudless.com"
          },
          "created": "2017-12-02T08:49:41Z",
          "description": "detail steps on how to set up the dev env",
          "id": "FkBoZX_HGUZMd9hYgvGl0nHAt8D1z-qJLezuKU3-CCNRJxXWBdfJkfjiTW_IGvt9o",
          "modified": "2017-12-02T08:49:41Z",
          "text": "<p>Follow the instructions below</p>",
          "topic": "Development environment set up manual",
          "type": "article",
          "href": "https://api.kloudless.com/v1/accounts/123/itsm/articles/FkBoZX_HGUZMd9hYgvGl0nHAt8D1z-qJLezuKU3-CCNRJxXWBdfJkfjiTW_IGvt9o"
        }
      ],
      "type": "object_list",
      "api": "itsm"
    }

Create an Article 

create an articlePOST /accounts/{account_id}/itsm/article

To create an article, perform a POST request with a JSON object with the following attributes:

  • author User responsible for creating this Article

  • active Whether the Article is active or not

  • category Category of the Article

  • rating Rating of the Article

  • roles Who can see the Article

  • topic Topic of the Article

  • text Text of the Article

  • description Details of the Article

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/itsm/articles' \
    -XPOST -d '{
        "category": "Software",
        "description": "detail steps on how to set up the dev env",
        "author": "uNDZkMTRmMDRhOWZlMTk4MTAxNDJlNDBjNmIwNzE1MTI=",
        "text": "<p>Follow the instructions below</p>",
        "topic": "Development environment set up manual"
    }'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "category": "Software",
      "description": "detail steps on how to set up the dev env",
      "author": "uNDZkMTRmMDRhOWZlMTk4MTAxNDJlNDBjNmIwNzE1MTI=",
      "text": "<p>Follow the instructions below</p>",
      "topic": "Development environment set up manual"
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "active": true,
      "api": "itsm",
      "author": {
        "type": "user",
        "api": "team",
        "id": "uNDZkMTRmMDRhOWZlMTk4MTAxNDJlNDBjNmIwNzE1MTI=",
        "name": "David Thorman",
        "email": "dthorman@kloudless.com"
      },
      "created": "2017-12-02T08:49:41Z",
      "description": "detail steps on how to set up the dev env",
      "id": "FkBoZX_HGUZMd9hYgvGl0nHAt8D1z-qJLezuKU3-CCNRJxXWBdfJkfjiTW_IGvt9o",
      "modified": "2017-12-02T08:49:41Z",
      "text": "<p>Follow the instructions below</p>",
      "topic": "Development environment set up manual",
      "type": "article",
      "href": "https://api.kloudless.com/v1/accounts/123/itsm/articles/FkBoZX_HGUZMd9hYgvGl0nHAt8D1z-qJLezuKU3-CCNRJxXWBdfJkfjiTW_IGvt9o"
    }

Retrieve an Article 

retrieve an ArticleGET /accounts/{account_id}/itsm/articles/{article_id}
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "active": true,
      "api": "itsm",
      "author": {
        "type": "user",
        "api": "team",
        "id": "uNDZkMTRmMDRhOWZlMTk4MTAxNDJlNDBjNmIwNzE1MTI=",
        "name": "David Thorman",
        "email": "dthorman@kloudless.com"
      },
      "created": "2017-12-02T08:49:41Z",
      "description": "detail steps on how to set up the dev env",
      "id": "FkBoZX_HGUZMd9hYgvGl0nHAt8D1z-qJLezuKU3-CCNRJxXWBdfJkfjiTW_IGvt9o",
      "modified": "2017-12-02T08:49:41Z",
      "text": "<p>Follow the instructions below</p>",
      "topic": "Development environment set up manual",
      "type": "article",
      "href": "https://api.kloudless.com/v1/accounts/123/itsm/articles/FkBoZX_HGUZMd9hYgvGl0nHAt8D1z-qJLezuKU3-CCNRJxXWBdfJkfjiTW_IGvt9o"
    }

Update an Article 

update an articlePATCH /accounts/{account_id}/itsm/articles/{article_id}

To update an article, create a JSON object with any of the following properties:

  • author User responsible for creating this Article

  • active Whether the Article is active or not

  • category Category of the Article

  • rating Rating of the Article

  • roles Who can see the Article

  • topic Topic of the Article

  • text Text of the Article

  • description Details of the Article

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "text": "<p>Follow the instructions below</p>"
    }' \
    'https://api.kloudless.com/v1/accounts/123/itsm/articles/FkBoZX_HGUZMd9hYgvGl0nHAt8D1z-qJLezuKU3-CCNRJxXWBdfJkfjiTW_IGvt9o
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "text": "<p>Follow the instructions below</p>"
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "active": true,
      "api": "itsm",
      "author": {
        "type": "user",
        "api": "team",
        "id": "uNDZkMTRmMDRhOWZlMTk4MTAxNDJlNDBjNmIwNzE1MTI=",
        "name": "David Thorman",
        "email": "dthorman@kloudless.com"
      },
      "created": "2017-12-02T08:49:41Z",
      "description": "detail steps on how to set up the dev env",
      "id": "FkBoZX_HGUZMd9hYgvGl0nHAt8D1z-qJLezuKU3-CCNRJxXWBdfJkfjiTW_IGvt9o",
      "modified": "2017-12-02T08:49:41Z",
      "text": "<p>Follow the instructions below</p>",
      "topic": "Development environment set up manual",
      "type": "article",
      "href": "https://api.kloudless.com/v1/accounts/123/itsm/articles/FkBoZX_HGUZMd9hYgvGl0nHAt8D1z-qJLezuKU3-CCNRJxXWBdfJkfjiTW_IGvt9o"
    }

Delete an Article 

delete an articleDELETE /accounts/{account_id}/itsm/articles/{article_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE 'https://api.kloudless.com/v1/accounts/123/itsm/articles/FkBoZX_HGUZMd9hYgvGl0nHAt8D1z-qJLezuKU3-CCNRJxXWBdfJkfjiTW_IGvt9o'
  • Response  204

ITSM Assets 

An asset is any of the physical, technological, contractual, and financial aspects of information technology assets.

  • id Unique identifier for the Asset

  • active Whether the Asset is active or not

  • assignee User assigned to this Asset

  • department Identifier of related department

  • model Model of the Asset

  • name Name of the Asset

  • quantity Quantity of the asset

  • created ISO 8601 timestamp indicating when the object was created

  • modified ISO 8601 timestamp indicating when the object was modified

  • description Details of the Asset

  • type Type of object. always “asset”

  • api Always itsm

  • raw Underlying object retrieved from the service with all fields, including custom ones

  • href The absolute URL to get the object’s metadata.

List Assets 

list assetsGET /accounts/{account_id}/itsm/assets{?page_size,page}

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of asset objects

  • type Always object_list

  • api Always itsm

  • Parameters
  • page_size
    number (optional) Default: 10 

    Number of objects in each page. For some services, the page_size isn’t respected. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "total": 1,
      "count": 1,
      "page": 1,
      "next_page": null,
      "objects": [
        {
          "api": "itsm",
          "assignee": {
            "type": "user",
            "api": "team",
            "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
            "name": "Vinod Chandru",
            "email": "vinod@kloudless.com"
          },
          "created": "2017-12-03T14:41:44Z",
          "department": "221f79b7c6112284005d646b76ab978c",
          "id": "F2MLXtBS9d2ffbhco2CiHvVj9bSCiGAVlAG29GJWwt6GN98QRJmDEuL2KnzLfXUO3",
          "model": "f10008893710200044e0bfc8bcbe5d80",
          "modified": "2017-12-03T14:41:44Z",
          "name": "Samsung SyncMaster 24\" Class BackLight LED",
          "quantity": 1,
          "type": "asset",
          "href": "https://api.kloudless.com/v1/accounts/123/itsm/assets/F2MLXtBS9d2ffbhco2CiHvVj9bSCiGAVlAG29GJWwt6GN98QRJmDEuL2KnzLfXUO3"
        }
      ],
      "type": "object_list",
      "api": "itsm"
    }

Create an Asset 

create an assetPOST /accounts/{account_id}/itsm/asset

To create an asset, perform a POST request with a JSON object with the following attributes:

  • active: Whether the Asset is active or not

  • assignee: User assigned to Asset

  • department: Identifier of related department

  • model: Model of the Asset

  • name: Name of the Asset

  • quantity: Quantity of the asset

  • description: Details of the Asset

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/itsm/assets' \
    -XPOST -d '{
        "assignee": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "model": "f10008893710200044e0bfc8bcbe5d80",
        "name": "Samsung SyncMaster 24\" Class BackLight LED",
        "quantity": 1
    }'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "assignee": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
      "model": "f10008893710200044e0bfc8bcbe5d80",
      "name": "Samsung SyncMaster 24\" Class BackLight LED",
      "quantity": 1
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "api": "itsm",
      "assignee": {
        "type": "user",
        "api": "team",
        "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "name": "Vinod Chandru",
        "email": "vinod@kloudless.com"
      },
      "created": "2017-12-03T14:41:44Z",
      "department": "221f79b7c6112284005d646b76ab978c",
      "id": "F2MLXtBS9d2ffbhco2CiHvVj9bSCiGAVlAG29GJWwt6GN98QRJmDEuL2KnzLfXUO3",
      "model": "f10008893710200044e0bfc8bcbe5d80",
      "modified": "2017-12-03T14:41:44Z",
      "name": "Samsung SyncMaster 24\" Class BackLight LED",
      "quantity": 1,
      "type": "asset",
      "href": "https://api.kloudless.com/v1/accounts/123/itsm/assets/F2MLXtBS9d2ffbhco2CiHvVj9bSCiGAVlAG29GJWwt6GN98QRJmDEuL2KnzLfXUO3"
    }

Retrieve an Asset 

retrieve an AssetGET /accounts/{account_id}/itsm/assets/{asset_id}
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "api": "itsm",
      "assignee": {
        "type": "user",
        "api": "team",
        "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "name": "Vinod Chandru",
        "email": "vinod@kloudless.com"
      },
      "created": "2017-12-03T14:41:44Z",
      "department": "221f79b7c6112284005d646b76ab978c",
      "id": "F2MLXtBS9d2ffbhco2CiHvVj9bSCiGAVlAG29GJWwt6GN98QRJmDEuL2KnzLfXUO3",
      "model": "f10008893710200044e0bfc8bcbe5d80",
      "modified": "2017-12-03T14:41:44Z",
      "name": "Samsung SyncMaster 24\" Class BackLight LED",
      "quantity": 1,
      "type": "asset",
      "href": "https://api.kloudless.com/v1/accounts/123/itsm/assets/F2MLXtBS9d2ffbhco2CiHvVj9bSCiGAVlAG29GJWwt6GN98QRJmDEuL2KnzLfXUO3"
    }

Update an Asset 

update an assetPATCH /accounts/{account_id}/itsm/assets/{asset_id}

To update an asset, create a JSON object with any of the following properties:

  • active: Whether the Asset is active or not

  • assignee: User assigned to Asset

  • department: Identifier of related department

  • model: Model of the Asset

  • name: Name of the Asset

  • quantity: Quantity of the asset

  • description: Details of the Asset

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "quantity": 1
    }' \
    'https://api.kloudless.com/v1/accounts/123/itsm/assets/F2MLXtBS9d2ffbhco2CiHvVj9bSCiGAVlAG29GJWwt6GN98QRJmDEuL2KnzLfXUO3'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "quantity": 1
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "api": "itsm",
      "assignee": {
        "type": "user",
        "api": "team",
        "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "name": "Vinod Chandru",
        "email": "vinod@kloudless.com"
      },
      "created": "2017-12-03T14:41:44Z",
      "department": "221f79b7c6112284005d646b76ab978c",
      "id": "F2MLXtBS9d2ffbhco2CiHvVj9bSCiGAVlAG29GJWwt6GN98QRJmDEuL2KnzLfXUO3",
      "model": "f10008893710200044e0bfc8bcbe5d80",
      "modified": "2017-12-03T14:41:44Z",
      "name": "Samsung SyncMaster 24\" Class BackLight LED",
      "quantity": 1,
      "type": "asset",
      "href": "https://api.kloudless.com/v1/accounts/123/itsm/assets/F2MLXtBS9d2ffbhco2CiHvVj9bSCiGAVlAG29GJWwt6GN98QRJmDEuL2KnzLfXUO3"
    }

Delete an Asset 

delete an assetDELETE /accounts/{account_id}/itsm/assets/{asset_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE 'https://api.kloudless.com/v1/accounts/123/itsm/assets/F2MLXtBS9d2ffbhco2CiHvVj9bSCiGAVlAG29GJWwt6GN98QRJmDEuL2KnzLfXUO3'
  • Response  204

ITSM Objects 

The ITSM Objects endpoints allow operations on any generic object provided by the ITSM service by transmitting and receiving raw data via Kloudless. These objects include both standard and custom objects defined in the service.

  • id Unique identifier for the object

  • type Type of object. always “object”

  • api Always itsm

  • raw Underlying object retrieved from the service with all fields, including custom ones

  • href The absolute URL to get the object’s metadata.

Querying the objects endpoint requires a query parameter raw_type to query the service for objects of that type.

List Objects 

list objectsGET /accounts/{account_id}/itsm/objects{?page_size,page}

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of objects

  • type Always object_list

  • api Always itsm

  • Parameters
  • page_size
    number (optional) Default: 10 

    Number of objects in each page. For some services, the page_size isn’t respected. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
        "api": "itsm",
        "type": "object",
        "raw": {
            "object": {
                ...
            },
            "type": "sys_user",
            "id": "02826bf03710200044e0bfc8bcbe5d3f"
        },
        "id": "F4vXMrEqeBUal2U3ShiyBHGbcz8mHkYBlGECV22VFwaY-MnHmJUq5QDMUyRKSSryv"
        "href": "https://api.kloudless.com/v1/accounts/123/itsm/objects/F4vXMrEqeBUal2U3ShiyBHGbcz8mHkYBlGECV22VFwaY-MnHmJUq5QDMUyRKSSryv?raw_type=sys_user"
    }

Create an Object 

create an objectPOST /accounts/{account_id}/itsm/object

To create an object, perform a POST request with a JSON object with the attributes that are defined by the upstream service.

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/itsm/objects?raw_type=sys_user' \
    -XPOST -d '{
        "first_name": "Yu Ming",
        "last_name": "Lu",
        "email": "ymlu@kloudless.com"
    }'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "first_name": "Yu Ming",
      "last_name": "Lu",
      "email": "ymlu@kloudless.com"
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
        "api": "itsm",
        "type": "object",
        "raw": {
            "object": {
                ...
            },
            "type": "sys_user",
            "id": "02826bf03710200044e0bfc8bcbe5d3f"
        },
        "id": "F4vXMrEqeBUal2U3ShiyBHGbcz8mHkYBlGECV22VFwaY-MnHmJUq5QDMUyRKSSryv"
        "href": "https://api.kloudless.com/v1/accounts/123/itsm/objects/F4vXMrEqeBUal2U3ShiyBHGbcz8mHkYBlGECV22VFwaY-MnHmJUq5QDMUyRKSSryv?raw_type=sys_user"
    }

Retrieve an Object 

retrieve an ObjectGET /accounts/{account_id}/itsm/objects/{object_id}
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
        "api": "itsm",
        "type": "object",
        "raw": {
            "object": {
                ...
            },
            "type": "sys_user",
            "id": "02826bf03710200044e0bfc8bcbe5d3f"
        },
        "id": "F4vXMrEqeBUal2U3ShiyBHGbcz8mHkYBlGECV22VFwaY-MnHmJUq5QDMUyRKSSryv"
        "href": "https://api.kloudless.com/v1/accounts/123/itsm/objects/F4vXMrEqeBUal2U3ShiyBHGbcz8mHkYBlGECV22VFwaY-MnHmJUq5QDMUyRKSSryv?raw_type=sys_user"
    }

Update an Object 

update an objectPATCH /accounts/{account_id}/itsm/objects/{object_id}

To update an object, create a JSON object with any of the following properties:

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "first_name": "Yu-Ming"
    }' \
    'https://api.kloudless.com/v1/accounts/123/itsm/objects/F4vXMrEqeBUal2U3ShiyBHGbcz8mHkYBlGECV22VFwaY-MnHmJUq5QDMUyRKSSryv?raw_type=sys_user'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "first_name": "Yu-Ming"
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
        "api": "itsm",
        "type": "object",
        "raw": {
            "object": {
                ...
            },
            "type": "sys_user",
            "id": "02826bf03710200044e0bfc8bcbe5d3f"
        },
        "id": "F4vXMrEqeBUal2U3ShiyBHGbcz8mHkYBlGECV22VFwaY-MnHmJUq5QDMUyRKSSryv"
        "href": "https://api.kloudless.com/v1/accounts/123/itsm/objects/F4vXMrEqeBUal2U3ShiyBHGbcz8mHkYBlGECV22VFwaY-MnHmJUq5QDMUyRKSSryv?raw_type=sys_user"
    }

Delete an Object 

delete an objectDELETE /accounts/{account_id}/itsm/objects/{object_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE 'https://api.kloudless.com/v1/accounts/123/itsm/objects/F4vXMrEqeBUal2U3ShiyBHGbcz8mHkYBlGECV22VFwaY-MnHmJUq5QDMUyRKSSryv?raw_type=sys_user'
  • Response  204

Activity Monitoring 

Track changes to objects via the Events API and webhooks.

Events API required: These endpoints require your Kloudless subscription to include access to the Events API.


Users and Groups 

The Team API provides information on users and groups.