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.
2. Permisssions
To retrieve shipment details, the user must have "Service Tickets-Shipping & Receiving" permission. If you are unaware of your user permissions, contact your Account Administrator.
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 Shipment information
The method can be used to retrieve details of a shipment ticket.
Method | GET |
---|---|
End point | /v1/shipment-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/shipment-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": "WO9342719",
"title": "Server Shipment X101",
"status": "New",
"site": "IAD024",
"description": "New delivery for DFW010",
"courier": "DHL",
"customerReference": "REF05678",
"trackingNumber": "",
"requiresRemoteHandsTicket": "No",
"packageCount": 1,
"isLoadingBayRequired": false,
"estimatedDeliveryDate": "",
"createdOn": "2023-08-29 12:34:47",
"updatedOn": "2023-08-29 13:59:05",
"closedOn": "",
"createdBy": "fsl_test Testing",
"notificationRecipients": "jane_doe@email.com,jake_doe@email.com",
"specialInstructions": "",
"ticketType": "Shipping and Receiving",
"comments": []
}
Payload Description
Field Name | Type | Description |
---|---|---|
id | string(20) | Identifier of the shipments work order. |
title | string(160) | Label on the work order. |
status | string(enum) | Designates the stage of the shipment. values: [New, In Progress, Completed, Cancelled] |
site | string(6) | Identifier of the receiving DLR facility. |
description | string(32k) | Specifies in the work order what items are being shipped to the DLR receiving facility. |
courier | string(20) | Designates what company is delivering the items specified in the shipment work order. |
customerReference | string(40) | Customer Reference number. |
trackingNumber | string(100) | Identifier of the courier order. |
requiresRemoteHandsTicket | string | RemoteHandsTicket Specification. |
packageCount | integer | Number of items being shipped allocated to the work order. |
isLoadingBayRequired | boolean | Indicates if a loading bay is needed. |
estimatedDeliveryDate | string(date-time) | Estimated Date for Scheduled Shipment by the specified Courier. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC] |
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. |
notificationRecipients | string(32k) | Personnel’s email addresses designated to receive notification of shipment and/or delivery date and times. |
specialInstructions | string(32k) | Specifies the special instructions for the shipment. |
ticketType | string(enum) | Type of the ticket. value: [Shipping and Receiving] |
comments | array | Array of comment objects |
The method can be used to retrieve all shipment tickets of the customers account.
Method | GET |
---|---|
End point | /v1/shipment-tickets |
Headers | Authorization, Master-Account-Id, Account-Id |
Query Parameters | site, status, createdBy, size, page |
Body | n/a |
Sample Curl Request
curl --location --request GET 'https://api.digitalrealty.com/v1/shipment-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 receiving facility that received shipments. |
status | false | string(enum) | Filter by state of the shipment. values: [New, In Progress, Completed, Cancelled] |
createdBy | false | string(40) | Filter by user who generated the shipping 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": "WO9346008",
"title": "title sample",
"status": "Cancelled",
"site": "PHX015",
"courier": "DHL",
"requiresRemoteHandsTicket": "",
"createdOn": "2023-09-05 15:26:27",
"updatedOn": "2023-09-05 15:30:57",
"closedOn": "2023-09-05 15:30:57",
"createdBy": "fsl_test Testing"
}
],
"pageable": {
"last": true,
"totalPages": 1,
"totalElements": 25,
"size": 25,
"number": 0,
"numberOfElements": 25,
"first": true,
"empty": false
}
}
Payload Description
Field Name | Type | Description |
---|---|---|
id | string(20) | Identifier of the shipments work order. |
title | string(160) | Label on the work order. |
status | string(enum) | Designates the stage of the shipment. values: [New, In Progress, Completed, Cancelled] |
site | string(6) | Identifier of the receiving DLR facility. |
courier | string(20) |
Designates what company is delivering the items specified in the shipment work order. Note : The courier field will be included in the response if the value is not "Other" . |
requiresRemoteHandsTicket | string | RemoteHandsTicket Specification. |
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 Shipment Ticket
Customer has to create a remote hands ticket if they want DLR remote hands technician to install the equipment or deliver the equipment to customer location. The remote hands request should reference the shipments request number.
The method can be used to create a shipment ticket.
Method | POST |
---|---|
End point | /v1/shipment-tickets |
Headers | Authorization, Master-Account-Id, Account-Id, Content-Type |
Query Parameters | n/a |
Body | title, site, description, courier, customerReference, trackingNumber, packageCount,estimatedDeliveryDate, specialInstructions,isLoadingBayRequired, notificationRecipients |
Sample Curl Request
curl --location --request POST 'https://api.digitalrealty.com/v1/shipment-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": "Server Shipment X101",
"site": "DFW010",
"description": "New delivery for DFW010",
"courier": "DHL",
"customerReference": "REF01234",
"trackingNumber": "TN123",
"packageCount": 1,
"isLoadingBayRequired": false,
"estimatedDeliveryDate": "2022-08-22 10:00:00",
"specialInstructions": "heavy package",
"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 receiving DLR facility. |
description | true | string(32k) | Specifies in the work order what items are being shipped to the DLR receiving facility. |
courier | true | string(20) | Designates what company is delivering the items specified in the shipment work order. |
customerReference | false | string(40) | Customer Reference number. |
trackingNumber | true | string(100) | Customer identifier of the shipment work order. |
packageCount | false | integer | Number of items being shipped allocated to the work order. |
isLoadingBayRequired | false | boolean | Indicates if a loading bay is needed. |
estimatedDeliveryDate | true | string(date) | Estimated Date for Scheduled Shipment by the specified Courier. format: [yyyy-MM-dd] timezone: [UTC] |
specialInstructions | false | string(32k) | Specifies the special instructions for the shipment. |
notificationRecipients | false | string(32k) | Personnel’s email addresses designated to receive notification of shipment and/or delivery date and times. |
Sample JSON Response
{
"id": "WO9342719",
"title": "Server Shipment X101",
"status": "New",
"site": "IAD024",
"description": "New delivery for DFW010",
"courier": "DHL",
"customerReference": "REF05678",
"trackingNumber": "",
"requiresRemoteHandsTicket": "No",
"packageCount": 1,
"isLoadingBayRequired": false,
"estimatedDeliveryDate": "",
"createdOn": "2023-08-29 12:34:47",
"updatedOn": "2023-08-29 13:59:05",
"closedOn": "",
"createdBy": "fsl_test Testing",
"notificationRecipients": "jane_doe@email.com,jake_doe@email.com",
"specialInstructions": "",
"ticketType": "Shipping and Receiving",
"comments": []
}
Payload Description
Field Name | Type | Description |
---|---|---|
id | string(20) | Identifier of the shipments work order. |
title | string(160) | Label on the work order. |
status | string(enum) | Designates the stage of the shipment. values: [New, In Progress, Completed, Cancelled] |
site | string(6) | Identifier of the receiving DLR facility. |
description | string(32k) | Specifies in the work order what items are being shipped to the DLR receiving facility. |
courier | string(20) | Designates what company is delivering the items specified in the shipment work order. |
customerReference | string(40) | Customer Reference number. |
trackingNumber | string(100) | Identifier of the courier order. |
requiresRemoteHandsTicket | string | RemoteHandsTicket Specification. |
packageCount | integer | Number of items being shipped allocated to the work order. |
isLoadingBayRequired | boolean | Indicates if a loading bay is needed. |
estimatedDeliveryDate | string(date-time) | Estimated Date for Scheduled Shipment by the specified Courier. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC] |
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. |
notificationRecipients | string(32k) | Personnel’s email addresses designated to receive notification of shipment and/or delivery date and times. |
specialInstructions | string(32k) | Specifies the special instructions for the shipment. |
ticketType | string(enum) | Type of the ticket. value: [Shipping and Receiving] |
comments | array | Array of comment objects |
6. Update Shipment information
The method can be used to update a shipment ticket while the ticket status is still "New" or "In Progress".
Method | PUT |
---|---|
End point | /v1/shipment-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/shipment-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 '{
"title": "Server Shipment X101",
"site" :"IAD024",
"description": "New delivery for DFW010",
"specialInstructions": "Test",
"courier": "DHL",
"customerReference": "REF05678",
"trackingNumber": "1",
"packageCount": 1,
"isLoadingBayRequired": false,
"estimatedDeliveryDate": "2023-09-11 18:00:00",
"notificationRecipients": "test@email.com,johndoe@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 receiving DLR facility. |
description | true | string(32k) | Specifies in the work order what items are being shipped to the DLR receiving facility. |
specialInstructions | false | string(32k) | Specifies the special instructions for the shipment. |
courier | true | string(20) | Designates what company is delivering the items specified in the shipment work order. |
customerReference | false | string(40) | Customer Reference number. |
trackingNumber | false | string(100) | Identifier of the courier order. |
packageCount | false | integer | Number of items being shipped allocated to the work order. |
isLoadingBayRequired | false | boolean | Indicates if a loading bay is needed. |
estimatedDeliveryDate | false | string(date-time) | Estimated Date for Scheduled Shipment by the specified Courier. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC] |
notificationRecipients | false | string(32k) | Personnel’s email addresses designated to receive notification of shipment and/or delivery date and times. |
Sample JSON Response
{
"id": "WO9342719",
"title": "Server Shipment X101",
"status": "New",
"site": "IAD024",
"description": "New delivery for DFW010",
"courier": "DHL",
"customerReference": "REF05678",
"trackingNumber": "",
"requiresRemoteHandsTicket": "No",
"packageCount": 1,
"isLoadingBayRequired": false,
"estimatedDeliveryDate": "",
"createdOn": "2023-08-29 12:34:47",
"updatedOn": "2023-08-29 13:59:05",
"closedOn": "",
"createdBy": "fsl_test Testing",
"notificationRecipients": "jane_doe@email.com,jake_doe@email.com",
"specialInstructions": "",
"ticketType": "Shipping and Receiving",
"comments": []
}
Payload Description
Field Name | Type | Description |
---|---|---|
id | string(20) | Identifier of the shipments work order. |
title | string(160) | Label on the work order. |
status | string(enum) | Designates the stage of the shipment. values: [New, In Progress, Completed, Cancelled] |
site | string(6) | Identifier of the receiving DLR facility. |
description | string(32k) | Specifies in the work order what items are being shipped to the DLR receiving facility. |
courier | string(20) | Designates what company is delivering the items specified in the shipment work order. |
customerReference | string(40) | Customer Reference number. |
trackingNumber | string(100) | Identifier of the courier order. |
requiresRemoteHandsTicket | string | RemoteHandsTicket Specification. |
packageCount | integer | Number of items being shipped allocated to the work order. |
isLoadingBayRequired | boolean | Indicates if a loading bay is needed. |
estimatedDeliveryDate | string(date-time) | Estimated Date for Scheduled Shipment by the specified Courier. format: [yyyy-MM-dd HH:mm:ss] timezone: [UTC] |
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. |
notificationRecipients | string(32k) | Personnel’s email addresses designated to receive notification of shipment and/or delivery date and times. |
specialInstructions | string(32k) | Specifies the special instructions for the shipment. |
ticketType | string(enum) | Type of the ticket. value: [Shipping and Receiving] |
comments | array | Array of comment objects |
7. Cancel a Shipments Ticket
The method can be used to cancel a shipment ticket while the ticket status is still "New" or "In Progress".
Method | PUT |
---|---|
End point | /v1/shipment-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/shipment-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": "Request no longer needed"
}'
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": "Work Order WO9332376 has been cancelled."
}
Payload Description
Field Name | Type | Description |
---|---|---|
message | string(255) | Acknowledgement message of the cancellation. |
8. 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.