How to Guide | Digital Realty

1. Authenticate

Prerequisites

You should have registered in our developer portal. Check this link about how to register an Account.
You should request access to the playground, sandbox and production environment using our Support page. Here is the link to support page to request access to our environments.
You should have an App created in your account to get the client id and client secret. Check this link about how to create an App.

Note : The time data attribute on APIs follows a 24-hour clock starting at 00:00 and ending at 23:59.

Authentication

The bearer token obtained after successful authentication should be passed as credential when calling this API for authentication. Check the Access Token API link for instructions on how to generate your bearer token.

Read the Get Started documentation if you are unaware of your client credentials.

2. Permissions

3. Get Information

Get Account Information

Master account Id and account Id need to be passed in the header for this API call. This is needed to indicate your legal entity.
Refer to the Accounts API for instructions on how to retrieve your account information. You may skip this step if you already know your master account Id and account Id.

Get Site Information

Retrieve the available facility information which are assigned to you. You need the site code to indicate to which facility you want to make a request.
Refer to the Sites API for instructions on how to retrieve your site information. You may skip this step if you already know your sites.

Get Location Information

Retrieve the available location information which are assigned to you. You need the location name to indicate to which location in the facility you want to make a request.
Refer to the Locations API for instructions on how to retrieve your location information. You may skip this step if you already know your locations.

4. Retrieve Remote Hands information

The method can be used to retrieve details of a remote hands ticket.

Method	GET
End point	/v1/remotehands-tickets/{id}
Headers	Authorization, Master-Account-Id, Account-Id
Query Parameters	n/a
Body	n/a

Sample Curl Request

curl --location --request GET 'https://api.digitalrealty.com/v1/remotehands-tickets/<id>' \
--header 'Master-Account-Id: <Master-Account-Id>' \
--header 'Account-Id: <Account-Id>' \
--header 'Authorization: Bearer <access_token>'

Headers

Field Name	Mandatory	Type	Description
Master-Account-Id	true	string	Customer master account identifier.
Account-Id	true	string	Customer account identifier.
Authorization	true	string	Token-based authentication.

Query Parameters

n/a

Body

n/a

Sample JSON Response

{
    "id": "WO9271371",
    "title": "Subject",
    "status": "Cancellation Requested",
    "site": "IAD024",
    "location": "Starbucks Cage F150-B",
    "requestType": "Urgent Work",
    "category": "Equipment troubleshoot or replacement",
    "detailedInstruction": "Description",
    "customerReference": "REF05678",
    "referenceTicket": "WO1234566",
    "cancelReason": "Request no longer needed",
    "createdOn": "2023-05-26 21:07:32",
    "updatedOn": "2023-05-27 13:06:27",
    "closedOn": "",
    "createdBy": "Globa Flag",
    "ticketType": "Remote Hands",
    "notificationRecipients": "jane_doe@email.com, jake_doe@email.com",
    "comments: : []
}

Payload Description

Field Name	Type	Description
id	string(20)	Identifier of the remote hands work order.
title	string(160)	Label on the work order.
status	string(enum)	Designates the stage of the remote Hands request. values: [New, In Progress, Cancellation Requested, Completed, Cancelled]
site	string(6)	Identifier of the DLR facility.
location	string(40)	Identifier of customer premise within DLR facility.
requestType	string(enum)	Type of remote Hands request. values: [check the RequestType Category table]
category	string(enum)	The category of Remote Hands request based on the request type. values: [check the RequestType Category table]
detailedInstruction	string(32k)	Full description of work to be completed.
customerReference	string(40)	Customer Reference number.
referenceTicket	string(20)	Related Digital Realty work order.
cancelReason	string(enum)	Reason of the cancellation. values [ Duplicate request, Request entered in error, Request no longer needed ].
createdOn	string(date-time)	Date on which the work order was generated. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC]
updatedOn	string(date-time)	Last date on which the work order details were modified. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC]
closedOn	string(date-time)	Date on which the work order’s status was marked Completed. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC]
createdBy	string(40)	Designates the user that initially generated the work order.
ticketType	string(enum)	Type of the ticket. value: [Remote Hands]
notificationRecipients	string(32k)	Personnel's email addresses designated to be notified of the request. You can add one or more email addresses in the field by inserting a comma as a separator : "email_1, email_2, email_3".
comments	string	Comments for work order,

The method can be used to retrieve all remote hands tickets of the customers account.

Method	GET
End point	/v1/remotehands-tickets
Headers	Authorization, Master-Account-Id, Account-Id
Query Parameters	site, status, requestType, category, createdBy, size, page
Body	n/a

Sample Curl Request

curl --location --request GET 'https://api.digitalrealty.com/v1/remotehands-tickets' \
--header 'Master-Account-Id: <Master-Account-Id>' \
--header 'Account-Id: <Account-Id>' \
--header 'Authorization: Bearer <access_token>'

Headers

Field Name	Mandatory	Type	Description
Master-Account-Id	true	string	Customer master account identifier.
Account-Id	true	string	Customer account identifier.
Authorization	true	string	Token-based authentication.

Query Parameters

Field Name	Mandatory	Type	Description
site	false	string(6)	Filter by the DLR facility that handles the request.
status	false	string(enum)	Filter by state of the remote hands. values: [New, In Progress, Cancellation Requested, Completed, Cancelled]
requestType	false	string(enum)	Filter by the type of remote Hands request. values: [check the RequestType Category table]
category	false	string(enum)	Filter by the category of Remote Hands request based on the request type. values: [check the RequestType Category table]
createdBy	false	string(40)	Filter by user who generated the work order.
size	false	integer	The maximum number of search results to return. Default value: 25
page	false	integer	The page number of the returning search results. Default value: 0

Body

n/a

Sample JSON Response

{
    "content": [
        {
            "id": "WO9331924",
            "title": "Remote Hands Title",
            "status": "New",
            "site": "PHX015",
            "location": "",
            "category": "Existing cross connect or connectivity testing",
            "requestType": "Planned Work",
            "createdOn": "2023-08-03 16:58:01",
            "updatedOn": "2023-08-03 16:58:01",
            "closedOn": "",
            "createdBy": "portaluser QATest"
        }
    ],
    "pageable": {
        "last": false,
        "totalPages": 433,
        "totalElements": 10818,
        "size": 25,
        "number": 0,
        "numberOfElements": 25,
        "first": true,
        "empty": false
    }
}

Payload Description

Field Name	Type	Description
id	string(20)	Identifier of the remote hands work order.
title	string(160)	Label on the work order.
status	string(enum)	Designates the stage of the remote Hands request. values: [New, In Progress, Cancellation Requested, Completed, Cancelled]
site	string(6)	Identifier of the DLR facility.
location	string(40)	Identifier of customer premise within DLR facility.
category	string(enum)	The category of Remote Hands request based on the request type. values: [check the RequestType Category table]
requestType	string(enum)	Type of remote Hands request. values: [check the RequestType Category table]
createdOn	string(date-time)	Date on which the work order was generated. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC]
updatedOn	string(date-time)	Last date on which the work order details were modified. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC]
closedOn	string(date-time)	Date on which the work order’s status was marked Completed. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC]
createdBy	string(40)	Designates the user that initially generated the work order.

5. Create a Remote Hands Request

The method can be used to post a remote hands request ticket.

Method	POST
End point	/v1/remotehands-tickets
Headers	Authorization, Master-Account-Id, Account-Id, Content-Type
Query Parameters	n/a
Body	title, site, location, requestType, category, detailedInstruction, customerReference, referenceTicket, notificationRecipients

Sample Curl Request

curl --location --request POST 'https://api.digitalrealty.com/v1/remotehands-tickets' \
--header 'Master-Account-Id: <Master-Account-Id>' \
--header 'Account-Id: <Account-Id>' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "Test Connect Cisco Server",
  "site": "IAD024",
  "location": "Starbucks Cage F150-B",
  "requestType": "Planned Work",
  "category": "Existing cross connect or connectivity testing",
  "detailedInstruction": "Please test the connection of the Cisco server",
  "customerReference": "REF01234",
  "referenceTicket": "WO1234566",
  "notificationRecipients": "jane_doe@email.com,jake_doe@email.com"
}'

Headers

Field Name	Mandatory	Type	Description
Master-Account-Id	true	string	Customer master account identifier.
Account-Id	true	string	Customer account identifier.
Authorization	true	string	Token-based authentication.
Content-Type	true	string	Indicates the request body format. value: [application/json]

Query Parameters

n/a

Body

Field Name	Mandatory	Type	Description
title	true	string(160)	Label on the work order.
site	true	string(6)	Identifier of the DLR facility.
location	false	string(40)	Identifier of customer premise within DLR facility. (Suite, Floor)
requestType	true	string(enum)	Type of remote Hands request. values: [check the RequestType Category table]
category	true	string(enum)	The category of Remote Hands request based on the request type. values: [check the RequestType Category table]
detailedInstruction	false	string(32k)	Full description of work to be completed.
customerReference	false	string(40)	Customer Reference number.
referenceTicket	false	string(20)	Related Digital Realty work order.
notificationRecipients	false	string(32k)	Personnel's email addresses designated to be notified of the request. You can add one or more email addresses in the field by inserting a comma as a separator : "email_1, email_2, email_3".

Sample JSON Response

{
    "id": "WO9271371",
    "title": "Subject",
    "status": "Cancellation Requested",
    "site": "IAD024",
    "location": "Starbucks Cage F150-B",
    "requestType": "Urgent Work",
    "category": "Equipment troubleshoot or replacement",
    "detailedInstruction": "Description",
    "customerReference": "REF05678",
    "referenceTicket": "WO1234566",
    "cancelReason": "Request no longer needed",
    "createdOn": "2023-05-26 21:07:32",
    "updatedOn": "2023-05-27 13:06:27",
    "closedOn": "",
    "createdBy": "Globa Flag",
    "ticketType": "Remote Hands",
    "notificationRecipients": "jane_doe@email.com, jake_doe@email.com"
}

Payload Description

Field Name	Type	Description
id	string(20)	Identifier of the remote hands work order.
title	string(160)	Label on the work order.
status	string(enum)	Designates the stage of the remote Hands request. values: [New, In Progress, Cancellation Requested, Completed, Cancelled]
site	string(6)	Identifier of the DLR facility.
location	string(40)	Identifier of customer premise within DLR facility.
requestType	string(enum)	Type of remote Hands request. values: [check the RequestType Category table]
category	string(enum)	The category of Remote Hands request based on the request type. values: [check the RequestType Category table]
detailedInstruction	string(32k)	Full description of work to be completed.
customerReference	string(40)	Customer Reference number.
referenceTicket	string(20)	Related Digital Realty work order.
cancelReason	string(enum)	Reason of the cancellation. values [ Duplicate request, Request entered in error, Request no longer needed ].
createdOn	string(date-time)	Date on which the work order was generated. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC]
updatedOn	string(date-time)	Last date on which the work order details were modified. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC]
closedOn	string(date-time)	Date on which the work order’s status was marked Completed. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC]
createdBy	string(40)	Designates the user that initially generated the work order.
ticketType	string(enum)	Type of the ticket. value: [Remote Hands]
notificationRecipients	string(32k)	Personnel's email addresses designated to be notified of the request. You can add one or more email addresses in the field by inserting a comma as a separator : "email_1, email_2, email_3".

6. Update Remote Hands Information

The method can be used to update a remote hands ticket while the ticket status is still "New" or "In Progress".

Method	PUT
End point	/v1/remotehands-tickets/{id}
Headers	Authorization, Master-Account-Id, Account-Id, Content-Type
Query Parameters	n/a
Body	customerReference, notificationRecipients

Sample Curl Request

curl --location --request PUT 'https://api.digitalrealty.com//v1/remotehands-tickets/<id>' \
--header 'Master-Account-Id: <Master-Account-Id>' \
--header 'Account-Id: <Account-Id>' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "customerReference": "REF01234",
  "notificationRecipients": "jane_doe@email.com, jake_doe@email.com"
}'

Headers

Field Name	Mandatory	Type	Description
Master-Account-Id	true	string	Customer master account identifier.
Account-Id	true	string	Customer account identifier.
Authorization	true	string	Token-based authentication.
Content-Type	true	string	Indicates the request body format. value: [application/json]

Query Parameters

n/a

Body

Field Name	Mandatory	Type	Description
customerReference	false	string(40)	Customer Reference number.
notificationRecipients	false	string(32k)	Personnel's email addresses designated to be notified of the request. You can add one or more email addresses in the field by inserting a comma as a separator : "email_1, email_2, email_3".

n/a

Sample JSON Response

{
    "id": "WO9271371",
    "title": "Subject",
    "status": "Cancellation Requested",
    "site": "IAD024",
    "location": "Starbucks Cage F150-B",
    "requestType": "Urgent Work",
    "category": "Equipment troubleshoot or replacement",
    "detailedInstruction": "Description",
    "customerReference": "REF05678",
    "referenceTicket": "WO1234566",
    "cancelReason": "Request no longer needed",
    "createdOn": "2023-05-26 21:07:32",
    "updatedOn": "2023-05-27 13:06:27",
    "closedOn": "",
    "createdBy": "Globa Flag",
    "ticketType": "Remote Hands",
    "notificationRecipients": "jane_doe@email.com, jake_doe@email.com",
    "comments": []
}

Payload Description

Field Name	Type	Description
id	string(20)	Identifier of the remote hands work order.
title	string(160)	Label on the work order.
status	string(enum)	Designates the stage of the remote Hands request. values: [New, In Progress, Cancellation Requested, Completed, Cancelled]
site	string(6)	Identifier of the DLR facility.
location	string(40)	Identifier of customer premise within DLR facility.
requestType	string(enum)	Type of remote Hands request. values: [check the RequestType Category table]
category	string(enum)	The category of Remote Hands request based on the request type. values: [check the RequestType Category table]
detailedInstruction	string(32k)	Full description of work to be completed.
customerReference	string(40)	Customer Reference number.
referenceTicket	string(20)	Related Digital Realty work order.
cancelReason	string(enum)	Reason of the cancellation. values [ Duplicate request, Request entered in error, Request no longer needed ].
createdOn	string(date-time)	Date on which the work order was generated. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC]
updatedOn	string(date-time)	Last date on which the work order details were modified. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC]
closedOn	string(date-time)	Date on which the work order’s status was marked Completed. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC]
createdBy	string(40)	Designates the user that initially generated the work order.
ticketType	string(enum)	Type of the ticket. value: [Remote Hands]
notificationRecipients	string(32k)	Personnel's email addresses designated to be notified of the request. You can add one or more email addresses in the field by inserting a comma as a separator : "email_1, email_2, email_3".
comments	string	Comments for work order,

7. Cancel a Remote Hands Request

The method can be used to make a request to cancel a remote hands ticket while the ticket status is still "New" or "In Progress".

Method	PUT
End point	/v1/remotehands-tickets/{id}/cancel
Headers	Authorization, Master-Account-Id, Account-Id, Content-Type
Query Parameters	n/a
Body	cancelReason

Sample Curl Request

curl --location --request PUT 'https://api.digitalrealty.com/v1/remotehands-tickets/<id>/cancel' \
--header 'Master-Account-Id: <Master-Account-Id>' \
--header 'Account-Id: <Account-Id>' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "cancelReason": "Duplicate request"
}'

Headers

Field Name	Mandatory	Type	Description
Master-Account-Id	true	string	Customer master account identifier.
Account-Id	true	string	Customer account identifier.
Authorization	true	string	Token-based authentication.
Content-Type	true	string	Indicates the request body format. value: [application/json]

Query Parameters

n/a

Body

Field Name	Mandatory	Type	Description
cancelReason	false	string(enum)	Reason of the cancellation. values: [Duplicate request, Request entered in error, Request no longer needed] default: [Request no longer needed]

Sample JSON Response

{
    "message": "We have received your request for cancellation of workorder 'WO9342535'. We will be in contact shortly. Please be aware that fees might still apply to this request if work has already started."
}

Payload Description

Field Name	Type	Description
message	string(255)	Acknowledgement message of the cancellation.

8. Get Remote Hands Category

Retrieve the available remote hands categories supported by Digital Realty. The categories are related to the request types. The category used must part of the request type used.

You may skip this step if you already know the remote hands category.

Method	GET
End point	/v1/remotehands-tickets/categories
Headers	Authorization, Master-Account-Id, Account-Id
Query Parameters	requestType
Body	n/a

Sample Curl Request

curl --location --request GET 'https://api.digitalrealty.com/v1/remotehands-tickets/categories' \
--header 'Master-Account-Id: <Master-Account-Id>' \
--header 'Account-Id: <Account-Id>' \
--header 'Authorization: Bearer <access_token>'

Headers

Field Name	Mandatory	Type	Description
Master-Account-Id	true	string	Customer master account identifier.
Account-Id	true	string	Customer account identifier.
Authorization	true	string	Token-based authentication.

Query Parameters

Field Name	Mandatory	Type	Description
requestType	false	string(enum)	Type of remote Hands request. values: [Urgent work, Planned work]

Body

n/a

Sample JSON Response

{
    "result": [
        {
            "requestType": {
                "name": "Planned Work",
                "categories": [
                    {
                        "name": "Existing cross connect or connectivity testing"
                    },
                    {
                        "name": "Customer premise cabling"
                    },
                    {
                        "name": "Tape swaps"
                    },
                    {
                        "name": "Equipment installation"
                    },
                    {
                        "name": "Equipment de-installation"
                    },
                    {
                        "name": "Dedicated escort"
                    },
                    {
                        "name": "Auditing"
                    },
                    {
                        "name": "Other"
                    }
                ]
            }
        },
        {
            "requestType": {
                "name": "Urgent Work",
                "categories": [
                    {
                        "name": "Existing cross connect or connectivity testing"
                    },
                    {
                        "name": "KVM (keyboard, video, mouse) assistance"
                    },
                    {
                        "name": "Equipment troubleshoot or replacement"
                    },
                    {
                        "name": "Power cycle or reboot"
                    },
                    {
                        "name": "Other"
                    }
                ]
            }
        }
    ]
}

Payload Description

Field Name	Type	Description
requestType - name	string(enum)	Name of the Remote Hands Type values: [check the RequestType Category table]
categories - name	string(enum)	Name of the Remote Hands Category values: [check the RequestType Category table]

9. Add a Comment or Attachment

Add Comments

Add comments to an existing work order. Multiple comments can be added to a work order as long as the status of the order is not closed or cancelled. Refer to the Comments API instructions on how to add comments. You may skip this step if you already know how to add comments.

Add Attachments

Add attachments to an existing work order. Multiple attachments can be added to a work order as long as the status of the order is not closed or cancelled. Refer to the Attachments API for instructions on how to add attachments. You may skip this step if you already know how to add attachments.

RequestType Category table

RequestType	Category
Planned Work	Existing cross connect or connectivity testing
	Customer premise cabling
	Tape swaps
	Equipment installation
	Equipment de-installation
	Dedicated escort
	Auditing
	Other
Urgent Work	Existing cross connect or connectivity testing
	KVM (keyboard, video, mouse) assistance
	Equipment troubleshoot or replacement
	Power cycle or reboot
	Other

Response Codes

Please check the Response Codes overview in case of any issues.

1. Authenticate

Prerequisites

Authentication

2. Permissions

3. Get Information

Get Account Information

Get Site Information

Get Location Information

4. Retrieve Remote Hands information

Sample Curl Request

Headers

Query Parameters

Body

Sample JSON Response

Payload Description

Sample Curl Request

Headers

Query Parameters

Body

Sample JSON Response

Payload Description

5. Create a Remote Hands Request

Sample Curl Request

Headers

Query Parameters

Body

Sample JSON Response

Payload Description

6. Update Remote Hands Information

Sample Curl Request

Headers

Query Parameters

Body

Sample JSON Response

Payload Description

7. Cancel a Remote Hands Request

Sample Curl Request

Headers

Query Parameters

Body

Sample JSON Response

Payload Description

8. Get Remote Hands Category

Sample Curl Request

Headers

Query Parameters

Body

Sample JSON Response

Payload Description

9. Add a Comment or Attachment

Add Comments

Add Attachments

RequestType Category table

Response Codes

Need Help?