Data Types

All data is sent and received as JSON.

Output : The formatting of values in the responses.
Input : The formatting of input parameters of requests.
References : Composition of references in the responses.
Attachments : Composition of attachments in the requests.

Output

boolean

native

"known_error": true

currency

string : one of the currencies defined in the enumeration

"currency": "usd"

custom fields

array of hashes : each hash has keys id and value

    "custom_fields": [
      {"id": "first_name", "value": "Howard"},
      {"id": "last_name", "value": "Tanner"}
    ]

date

string: yyyy-mm-dd

"start_date": "2011-06-24"

datetime

string: yyyy-mm-ddThh:mm

"start_at": "2010-12-30T23:00"

ISO 8601 format, with a minutes resolution, without timezone.

decimal

string : number with decimals, separated by a dot (.)

"cost_per_hour": "120.5"

duration

integer : with resolution in minutes

"response_target": 240

enum

string : one of the options defined for the enumeration

"status": "registered"

float

native

"rate": 3.2313

integer

native

"nr_of_cores": 3

null

native : all blank fields are included as null instead of being omitted

"solved_at": null

reference

hash : composed of multiple values , or null if the reference is not filled out

"team": {"id": 12, "name": "Service Desk"} "team": null

string, text

native

"name": "Windows for Sales Tracking Production"

timestamp

string: yyyy-mm-ddThh:mm:ssZ

"completed_at": "2010-01-05T23:00:00Z"

ISO 8601 format, with a seconds resolution, with timezone.

time of day

string: hh:mm

"time_from": "08:30"

In military format . 00:00 = midnight at the start of the day, 12:00 = noon, 24:00 = midnight at the end of the day

time zone

string : one of the time zones defined in the enumeration

"time_zone": "Central Time (US & Canada)"

Input

attachments

An array of references to uploaded file attachments

boolean

Truthy values are 1 , T , Y , TRUE , YES , ON . These values are case insensitive, so true , trUE , tRue are all treated as truthy values. Falsy values are anything else, like: false , f , FALSE , F , 0

?known_error=true

enum

One of the options defined for the enumeration

?status=registered

date

yyyy-mm-dd

?start_date=2011-06-24

datetime

yyyy-mm-ddThh:mm

?start_at=2010-12-30T23:00

ISO 8601 format (with a minutes resolution, without timezone)

decimal, float

any number with decimals, separated by a dot (.)

?rate=3.2313

duration

integer : with resolution in minutes

?response_target=150

Alternatively it accepts a string in the format hhh:mm , for example:

?response_target=2:30

integer

any integer (0, 1, 2, …)

?nr_of_cores=3

null

all blank fields should be omitted from the input

reference

the id of the referenced resource, always append _id to the field name

?team_id=12

For arrays of references always append _ids to the field name

  "ci_ids": [1763, 1764]

string, text

any value

?name=Windows%20for%20Sales%20Tracking%20Production

timestamp

yyyy-mm-ddThh:mm:ssZ

?completed_at=2010-01-05T23:00:00Z

ISO 8601 format (with a seconds resolution, with timezone)

time of day

hh:mm

?time_from=08:30

In military format . 00:00 = midnight at the start of the day, 12:00 = noon, 24:00 = midnight at the end of the day

time zone

any valid time zone identifier listed in one of the following sources:

Time zone values from the Time Zone Database are mapped onto the enumeration of time zones in R-Service by their UTC offset.

?time_zone=Europe/Amsterdam

References

A reference to another resource is composed of one or more of the following fields.

Note : In the input , use only the id of the referenced resource and append _id to the field name, e.g. ?team_id=12 . For fields that contain an array of references as input, use the singular field name and append _ids , e.g. service_instance_ids for ‘service_instances’.

ID

All references contain an id property with which the details of the resource can be retrieved using a separate API call.

Note that when a record is opened in the R-Service user interface, the id can be found in the Address bar of the browser. It is the unique identifier at the end of the URL. The id of an account can be found in the user interface by going to the Account Overview section of the Settings console.

For aggregated references (arrays of ~) an id is not returned. Instead, all available fields are contained in aggregated references so that an id is not needed.

Display Properties

The reference will always contain the properties necessary to display the (list of) reference(s) to the end-user. In most cases this will expose the name and/or subject properties, but there are some exceptions like label for Configuration Item references.

Account

When the account of the referenced resource is different from the account of the authenticated user, the account reference will be provided. The account field is itself a reference and will always only show name and id . The name is intended as a display property for the end-user. The id can be used to switch to that account if appropriate, see Multiple Accounts .

If a resource or reference to a resource does not expose an account field, the account of the resource is equal to the account of the authenticated user.

The following example shows a request that is completed by a member of the Service Desk team from a different account (Virtual Support).

 $ curl -H "Authorization: Bearer <oauth-token>" https://api.r-service.tech/v1/requests/70384

Status: 200 OK

{
  "id": 70384,
  "status": "completed",
  "service_instance": {
    "name": "Time Off Request Production",
    "id": 97
  },
  "team": {
    "name": "Service Desk",
    "account": {
      "name": "VirtualSupport",
      "id": "virtualsupport"
    },
    "id": 2
  },
  "member": {
    "name": "Krish Hanuang",
    "account": {
      "name": "VirtualSupport",
      "id": "virtualsupport"
    },
    "id": 16
  }
}

Not all request fields are shown above to keep the example simple.

Source ID

When references to resources with a Source ID are retrieved from the API, the sourceID field will always be provided.

 $ curl -H "Authorization: Bearer <oauth-token>" https://api.r-service.tech/v1/requests?per_page=1

Status: 200 OK

[
  {
    "subject": "NewRequest",
    "category": "compliment",
    "status": "assigned",
    "sourceID": "N1C3AP1"
  }
]

Not all request fields are shown above to keep the example simple.

See source for more information on the usage of the sourceID field.

Disabled

In case a referenced resource is disabled, the disabled: true property will be provided. When a referenced resource is enabled, the disabled property is omitted.

 $ curl -H "Authorization: Bearer <oauth-token>" https://api.r-service.tech/v1/services/23

Status: 200 OK

{
  "id": 23,
  "name": "Short Term Production Planner",
  "created_at": "2016-03-10T02:05:27-06:00",
  "updated_at": "2016-03-10T02:10:51-06:00",
  "sourceID": null,
  "support_team": {
    "name": "Application Development",
    "id": 7
  },
  "provider": {
    "name": "Widget Data Center, External IT",
    "id": 30,
    "disabled": true
  }
}

Attachments

Various rich text fields in R-Service can hold attachments. They may contain inline image or video files, and some of them can have attachments listed externally, in which case in the R-Service UI these are displayed at the bottom of the text represented with a paperclip in front of each attachment.

Adding attachments and inline image or video files to rich text fields is a three-step process:

Get access to the R-Service storage facility
Upload the files
Add references to the uploaded files to a rich text field

These steps are explained in more detail hereunder for a scenario where a request is created with an attachment linked to the first note. For this example you will need a Personal Access Token with Create access to Requests.

Tip : Using the one of the R-Service API clients (SDKs) can make the process to upload attachments easier. The SDKs have specialized functionality to facilitate the steps described below. Please see the relevant documentation of the SDK for ruby or the .Net SDK for more details.

Remarks:

Depending on your environment (Windows or UNIX), the syntax of the curl commands hereunder will be slightly different. On a UNIX system , you need to escape the $ sign like -F "key=attachments/5/.../\${filename}" \ . On a Windows system you need to remove the backslash \ at the end of each line, use double quotes, and escape any quotes within the double quotes.

Step 1. Get access to the R-Service storage facility

 $ curl -H "Authorization: Bearer <oauth-token>" \
        -H "account: <accountID>" \
        -X GET \
        "https://api.r-service.tech/v1/attachments/storage"

The response will contain the storage upload details:

Status: 200 OK

{
  "size_limit": 2147483648,
  "allowed_extensions": [
    "csv",
    "gif",
    "png",
    "log",
    "pdf"
  ],
  "provider": "s3",
  "upload_uri": "https://R-Service.s3-accelerate.dualstack.amazonaws.com/",
  "s3": {
    "acl": "private",
    "key": "attachments/5/.../${filename}",
    "policy": "eyJ...V19",
    "success_action_status": 201,
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-credential": "AKIA...aws4_request",
    "x-amz-date": "20201115T000000Z",
    "x-amz-server-side-encryption": "AES256",
    "x-amz-signature": "5a0...ae5"
  }
}

In an on-premise environment the storage upload details might look like this instead:

Status: 200 OK

{
  "size_limit": 20971520,
  "allowed_extensions": [
    "csv",
    "gif",
    "png",
    "log",
    "pdf"
  ],
  "provider": "local",
  "upload_uri": "https://api.example.com/v1/attachments",
  "local": {
    "key": "attachments/5/.../${filename}",
    "x-R-Service-expiration": "2020-11-30T02:18:17Z",
    "x-R-Service-signature": "6dd...d0f"
  }
}

Step 2. Upload the files

Upload the actual file(s) to the R-Service storage facility. Post the file(s) to the value presented in upload_uri, and post all parameter presented in the s3 or local scope, preceded by the Content-Type of the file, and provide the file data last. For example:

 $ curl -F "Content-Type=plain/text" \
        -F "acl=private" \
        -F "key=attachments/5/.../\${filename}" \
        -F "policy=eyJ...V19" \
        -F "success_action_status=201" \
        -F "x-amz-algorithm=AWS4-HMAC-SHA256" \
        -F "x-amz-credential=AKIA...aws4_request" \
        -F "x-amz-date=20201115T000000Z" \
        -F "x-amz-server-side-encryption=AES256" \
        -F "x-amz-signature=5a0...ae5" \
        -F "file=@helloworld.txt" \
        "https://R-Service.s3-accelerate.dualstack.amazonaws.com/"

Or, in an on-premise environment:

 $ curl -H "Authorization: Bearer <token>" \
        -H "account: <accountID>" \
        -F "Content-Type=plain/text" \
        -F "key=attachments/5/.../\${filename}" \
        -F "x-R-Service-expiration=2020-11-30T02:18:17Z" \
        -F "x-R-Service-signature=6dd...d0f" \
        -F "file=@helloworld.txt" \
        "https://api.example.com/v1/attachments"

Remarks:

cURL interprets -F “file=@...” and reads the helloworld.txt from your disk (located in the directory where curl is executed) and sends it as form-encoded data to the server.
The response in the s3 scope needs some reformatting to be used in a curl statement. Remove the comma , between parameters and make sure the parameters are preceded by -F . The parameter is formatted as "attribute=value" instead of "attribute": "value" . Make sure to format "success_action_status": 201 , as -F "success_action_status=201" .

The response from the above command might look like this:

Status: 201 Created

  <?xml version="1.0"?>
  <PostResponse>
    <Location>https://R-Service.s3-accelerate.dualstack.amazonaws.com/attachments%2F5%2F2020%2F11%2F15%2F6%2F1605413834-431xxxc1be%%2Fhelloworld.txt</Location>
    <Bucket>R-Service</Bucket>
    <Key>attachments/5/2020/11/15/6/1605413834-431xxxcc1be/helloworld.txt</Key>
    <ETag>"9008d115b2d05a7ca6b495fd0cb998df"</ETag>
  </PostResponse>

Or, in an on-premise environment:

Status: 200 OK

{
  "key": "attachments/5/.../helloworld.txt"
}

Step 3. Add references to the uploaded files to a note

Create the new request and add all attachments in the note_attachments parameter:

 $ curl -H "Authorization: Bearer <token>" \
        -H "account: <accountID>" \
        -X POST \
        -d '{
          "requested_for_id": 51,
          "subject": "Test",
          "category": "other",
          "note": "Attachment test",
          "note_attachments": [ {"key": "attachments/5/.../helloworld.txt", "filesize": "16"} ]
        }' \
        "https://api.r-service.tech/v1/requests"

Remarks:

The value of key that is passed into the notes_attachments parameter should match the string from the <Key>...</Key> XML response. In an on-premise environment it should match the value key that was in the JSON response.
The filesize parameter is optional.
You will need to add the other parameters for creating a valid Request, such as requested_for_id and category , see Create a Request .

Inline attachments

To add an inline attachment to a rich text field the same process as described above is followed, except in the last step the attachment needs to be marked as inline , and a reference needs to be added within the rich text field using the special markdown syntax: ![](<key>) . For example:

 $ curl -H "Authorization: Bearer <token>" \
        -H "account: <accountID>" \
        -X POST \
        -d '{
          "requested_for_id": 51,
          "subject": "Test",
          "category": "other",
          "note_attachments": [ {"key": "attachments/5/.../helloworld.txt", "inline": true, "filesize": "16"} ],
          "note": "This is an inline attachment ![](attachments/5/.../helloworld.txt)"
        }' \
        "https://api.r-service.tech/v1/requests"

Removing an attachment

To remove an attachment from a field, use the _destroy attribute.

For example, suppose that the information field of person 123 has an attachment with key attachments/5/.../helloworld.txt . To remove it, execute the following:

 $ curl -H "Authorization: Bearer <token>" \
        -H "account: <accountID>" \
        -X PATCH \
        -d '{
          "information_attachments": [ {"key": "attachments/5/.../helloworld.txt", "_destroy": true } ]
        }' \
        "https://api.r-service.tech/v1/people/123"