UPS Paperless™ Document

JSON Developer Guide

January 06, 2020

Important Information

UPS Developer Kit APIs

Your development of an application using UPS Developer Kit APIs is governed by the UPS Technology
Agreement you entered into with UPS. The following are key legal requirements from these agreements for the
UPS Developer Kit APIs. For more information on all requirements for the UPS Developer Kit APIs, please refer
to the UPS Technology Agreement.
Defined terms used but not defined in this document have the meaning set forth in the UPS Technology
Agreement.

Key Legal Requirements for UPS Developer APIs

Permitted Territories
This document can only be used in the countries of the Permitted Territory as defined in the UPS Technology
Agreement, as applicable.

Use
The application must not be designed to allow distribution of information received through the UPS Developer
Kit APIs to third parties, other than to persons having a bona fide interest in such information (e.g., the shipper,
receiver, or the third party payer, or to your service providers authorized by UPS).

Consent to Use of UPS Mark

 All screens or forms generated by your application including information received through the UPS
Developer Kit APIs must include (1) the UPS Mark positioned in reasonable proximity to the Information and
of an appropriate size to readily identify the source of the Information as UPS and (2) the following language
at the bottom of every screen that displays the UPS Mark: "UPS, the UPS brand mark, and the Color Brown
are trademarks of United Parcel Service of America, Inc. All Rights Reserved." Except as set forth in the
preceding sentence, you have no right to use the UPS Mark without the prior written approval of UPS.
 You shall not use the UPS Mark in association with any third party trademarks in a manner that might
suggest co-branding or otherwise create potential confusion as to source or sponsorship of the application,
or ownership of the UPS Mark.
 The UPS Mark shall be used only as provided by UPS electronically or in hard copy form. The UPS Mark
may not be altered in any manner, including proportions, colors, elements, etc., or animated, morphed or
otherwise distorted in perspective or dimensional appearance.
 The UPS Mark may not be combined with any other symbols, including words, logos, icons, graphics,
photos, slogans, numbers, or other design elements. A minimum amount of empty space must surround the
UPS Mark separating it from any other object, such as type, photography, borders, edges, etc. The required
area of empty space around the UPS Mark must be 1/3x, where x equals the height of the UPS Mark.

Copyright and Proprietary Notice

In your application and any POD Letters you prepare, you must include a prominent reproduction of UPS’s
copyright and proprietary notices in a form and format specified by UPS (See the Copyright section of this
document).

Display of Information
The application must not display information concerning any other provider of shipping services or such other
shipping services on any page, whether comprising one or more frames, displaying information your application
receives from the UPS Developer Kit APIs. Your application must present all data within each field received
through the UPS Developer Kit APIs without amendment, deletion, or modification of any type.

© 2020 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 2
Notice
In all communications with UPS concerning this document, please refer to the document date located on the
cover.

Copyright
© 2020 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
The use, disclosure, reproduction, modification, transfer, or transmittal of this work for any purpose in any form
or by any means without the written permission of United Parcel Service is strictly prohibited.

Trademarks
Some of the UPS corporate applications use United States city, state, and postal code information obtained by
United Parcel Service of America, Inc. under a non-exclusive license from the United States Postal Service.

© 2020 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 3
 Table of Contents
Chapter 1: Introduction ......................................................................................................... 5

Chapter 2: Customer Integration Environment (CIE) ............................................................... 6

JSON Testing and Production URLS ......................................................................................................................6

Chapter 3: JSON Examples ..................................................................................................... 7

DeleteRequest ..........................................................................................................................................................7
DeleteResponse .......................................................................................................................................................7
PushToImageRepositoryRequest ...........................................................................................................................8
PushToImageRepositoryResponse ........................................................................................................................8
UploadRequest .........................................................................................................................................................9
UploadResponse .................................................................................................................................................... 10

Appendix............................................................................................................................. 11
JSON Error Codes .................................................................................................................................................. 11

© 2020 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 4
UPS Paperless™ Document JSON Developer Guide January 06, 2020

Chapter 1: Introduction
In this document, you will find guidance and instructions for integrating the UPS Paperless™ JSON API
into your application, service, or system.

IMPORTANT:
 If this is your first time working with the UPS Developer Kit, begin with the Introduction to the
UPS Developer Kit guide. This guide serves as the foundation for all API-specific developer guides.
 For additional API, XPath, and Error Code information, refer to the UPS Paperless™ Web Service
Developer Guide.

© 2020 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 5
UPS Paperless™ Document JSON Developer Guide January 06, 2020

Chapter 2: Customer Integration Environment (CIE)

The Customer Integration Environment allows customers to test their application prior to launch. This environment is
intended for integration testing of customer applications with the UPS servers.
Once your application has been thoroughly tested, you should redirect the application to the UPS Production
Environment.

No stress testing should ever be performed by customers against any UPS systems.
To access testing and production sites the user must have an Access Key. You can request an Access Key after
establishing a UPS profile and associating your shipping account.

System Availability
The Customer Integration Environment is available 24 hours a day, 7 days a week. Note the system is occasionally
down for server maintenance.

All API URLs are case sensitive.

JSON Testing and Production URLS

Testing: https://wwwcie.ups.com/rest/PaperlessDocumentAPI
Production: https://filexfer.ups.com/rest/PaperlessDocumentAPI

© 2020 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 6
UPS Paperless™ Document JSON Developer Guide January 06, 2020

Chapter 3: JSON Examples

DeleteRequest
{
"UPSSecurity": {
"UsernameToken": {
"Username": "Your User Id",
"Password": "Your Password"
},
"ServiceAccessToken": {
"AccessLicenseNumber": "Your Access License Number"
}
},
"DeleteRequest": {
"Request": {
"TransactionReference": {
"CustomerContext": "Your Customer Context",
}
},
"ShipperNumber": "Your Shipper Number",
"DocumentID": "2016-01-18-11.01.07.589501"
}
}

DeleteResponse
{
"DeleteResponse": {
"Response": {
"ResponseStatus": {
"Code": "1",
"Description": "Success"
},
"TransactionReference": {
"CustomerContext": "Your Customer Context",
}
}
}
}

© 2020 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 7
UPS Paperless™ Document JSON Developer Guide January 06, 2020

PushToImageRepositoryRequest
{
"UPSSecurity": {
"UsernameToken": {
"Username": "Your User Id",
"Password": "Your Password"
},
"ServiceAccessToken": {
"AccessLicenseNumber": "Your Access License Number"
}
},
"PushToImageRepositoryRequest": {
"Request": {
"TransactionReference": {
"CustomerContext": "Your Customer Context",
}
},
"ShipperNumber": "Your Shipper Number",
"FormsHistoryDocumentID": {
"DocumentID": "2016-01-18-11.01.07.589501"
},
"ShipmentIdentifier": "Your Package Shipment Identifier",
"ShipmentDateAndTime": "2016-01-18-11.01.07",
"ShipmentType": "1",
"TrackingNumber": "Your Package Tracking Number"
}
}

PushToImageRepositoryResponse
{
"PushToImageRepositoryResponse": {
"Response": {
"ResponseStatus": {
"Code": "1",
"Description": "Success"
},
"TransactionReference": {
"CustomerContext": "Your Customer Context",
}
},
"FormsGroupID": "2016-01-18-11.09.01.244847"
}
}

© 2020 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 8
UPS Paperless™ Document JSON Developer Guide January 06, 2020

UploadRequest
{
"UPSSecurity": {
"UsernameToken": {
"Username": "Your User Id",
"Password": "Your Password"
},
"ServiceAccessToken": {
"AccessLicenseNumber": "Your Access License Number"
}
},
"UploadRequest": {
"ShipperNumber": "Your Shipper Number",
"Request": {
"TransactionReference": {
}
},
"UserCreatedForm": {
"UserCreatedFormFileName": "TestFile.txt",
"UserCreatedFormFileFormat": "txt",
"UserCreatedFormDocumentType": "013",
"UserCreatedFormFile":
"Tm90aWNlDQpJbiBhbGwgY29tbXVuaWNhdGlvbnMgd2l0aCBVUFMgY29uY2VybmluZyB0aGlzIG
Rv
Y3VtZW50LCBwbGVhc2UgcmVmZXIgdG8gdGhlIGRvY3VtZW50IGRhdGUgbG9jYXRlZCBvbiB0aGUg
Y292ZXIuDQpDb3B5cmlnaHQNClRoZSB1c2UsIGRpc2Nsb3N1cmUsIHJlcHJvZHVjdGlvbiwgbW9k
aWZpY2F0aW9uLCB0cmFuc2Zlciwgb3IgdHJhbnNtaXR0YWwgb2YgdGhpcyB3b3JrIGZvciBhbnkg
cHVycG9zZSBpbiBhbnkgZm9ybSBvciBieSBhbnkgbWVhbnMgd2l0aG91dCB0aGUgd3JpdHRlbiBw
ZXJtaXNzaW9uIG9mIFVuaXRlZCBQYXJjZWwgU2VydmljZSBpcyBzdHJpY3RseSBwcm9oaWJpdGVk
Lg0KwqkgQ29weXJpZ2h0IDIwMTYgVW5pdGVkIFBhcmNlbCBTZXJ2aWNlIG9mIEFtZXJpY2EsIElu
Yy4gQWxsIFJpZ2h0cyBSZXNlcnZlZC4NClRyYWRlbWFya3MNClVQUyBPbkxpbmXCriBpcyBhIHJl
Z2lzdGVyZWQgdHJhZGVtYXJrIG9mIFVuaXRlZCBQYXJjZWwgU2VydmljZSBvZiBBbWVyaWNhLCBJ
bmMuIEFsbCBvdGhlciB0cmFkZW1hcmtzIGFyZSB0aGUgcHJvcGVydHkgb2YgdGhlaXIgcmVzcGVj
dGl2ZSBvd25lcnMuDQpTb21lIG9mIHRoZSBVUFMgY29ycG9yYXRlIGFwcGxpY2F0aW9ucyB1c2Ug
VS5TLiBjaXR5LCBzdGF0ZSwgYW5kIHBvc3RhbCBjb2RlIGluZm9ybWF0aW9uIG9idGFpbmVkIGJ5
IFVuaXRlZCBQYXJjZWwgU2VydmljZSBvZiBBbWVyaWNhLCBJbmMuIHVuZGVyIGEgbm9uLWV4Y2x1
c2l2ZSBsaWNlbnNlIGZyb20gdGhlIFVuaXRlZCBTdGF0ZXMgUG9zdGFsIFNlcnZpY2UuIA0K"
}
}
}

© 2020 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 9
UPS Paperless™ Document JSON Developer Guide January 06, 2020

UploadResponse
{
"UploadResponse": {
"Response": {
"ResponseStatus": {
"Code": "1",
"Description": "Success"
},
"TransactionReference": {
}
},
"FormsHistoryDocumentID": {
"DocumentID": "2016-01-18-11.01.07.589501"
}
}
}

© 2020 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 10
UPS Paperless™ Document JSON Developer Guide January 06, 2020

Appendix
JSON Error Codes
Code Description
1 Unrecognized Error
Any error, other than those listed below, causing an issue with the request.
 Verify the request headers are correct.
 Retry the request again later
2 Unknown Operation
The UPS system does not understand the operation and is unable to forward the request to the
correct API.
 Verify the request headers are correct.
 Check request structure.
3 Network Error
Transient error indicating the network is hindering request submission.
 Retry the request again later.
4 JSON Syntax Error
Indicates a problem with the JSON syntax.
 Verify your request syntax is correct.

© 2020 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 11