Paperless

The Paperless Documents API allows users to upload specific trade documents for paperless processing of international shipments.
The /upload endpoint of the API requires document details, including file name, file format, and document type (such as authorization form, commercial invoice, certificate of origin, export license, etc).
The /image endpoint helps users upload document images as support documents for shipping
The /delete endpoint of the API helps delete a specific document the user has uploaded.

Reference

Try out UPS APIs with example requests using Postman. Explore API documentation and sample applications through GitHub.

Upload Paperless Document

The Paperless Document API web service allows the users to upload,delete and push to image repository their own customized trade documents for customs clearance to Forms History.

SecurityOAuth2

Request

path Parameters

version

required

string

Default: "v2"

Version of API

Valid values:

v2

header Parameters

transId	string An identifier unique to the request. Length 32
transactionSrc	string Default: testing An identifier of the client/source application that is making the request.Length 512
ShipperNumber required	string Shipper Number

Request Body schema: application/json

Generate sample code for popular API requests by selecting an example below. To view a full sample request and response, first click "Authorize" and enter your application credentials, then populate the required parameters above and click "Try it out".

<= 1

required

object (UploadRequest) <= 1

Paperless Document API Request container for uploading User Created Forms.

required

object (UploadRequest_Request) <= 1

Contains Paperless Document API upload request criteria components.

RequestOption	string = 1 characters Enables the user to specify optional processing. Currently, there is no optional process in Paperless Document API.
SubVersion	string <= 1 Not Used.
	object (components-schemas-Request_TransactionReference) <= 1 TransactionReference identifies transactions between client and server.

ShipperNumber

required

string = 6 characters <= 1

The Shipper's UPS Account Number. Your UPS Account Number must have 'Upload Forms Created Offline' enabled to use this webservice.

required

Array of objects (UploadRequest_UserCreatedForm) <= 13

Array

UserCreatedFormFileName required	string [ 1 .. 300 ] characters <= 1 The name of the file.
UserCreatedFormFile required	string <= 1 The user created form file. The maximum allowable size of each file is restricted to 10 MB. Should be a base64 encoded string. Note: The maximum allowable size of each file is restriced to 1MB in CIE (Customer Integration Environment).
UserCreatedFormFileFormat required	string [ 3 .. 4 ] characters <= 1 The UserCreatedForm file format. The allowed file formats are bmp, doc, gif, jpg, pdf, png, rtf, tif, txt and xls. The only exceptions for having file format of length 4 character are docx and xlsx. All other file formats needs to be of length 3.
UserCreatedFormDocumentType required	string = 3 characters <= 13 The type of documents in UserCreatedForm file. The allowed document types are 001 - Authorization Form, 002 - Commercial Invoice, 003 - Certificate of Origin, 004 - Export Accompanying Document, 005 - Export License, 006 - Import Permit, 007 - One Time NAFTA, 008 - Other Document, 009 - Power of Attorney, 010 - Packing List, 011 - SED Document, 012 - Shipper's Letter of Instruction, 013 - Declaration. The total number of documents allowed per file or per shipment is 13. Each document type needs to be three digits.

Responses

200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

post/paperlessdocuments/{version}/upload

Request samples

application/json

{"UploadRequest": {"Request": {"TransactionReference": {"CustomerContext": ""
}
},
"UserCreatedForm": {"UserCreatedFormFileName": "TestFile.txt",
"UserCreatedFormFileFormat": "txt",
"UserCreatedFormDocumentType": "013",
"UserCreatedFormFile": "Tm90aWNlDQpJbiBhbGwgY29tbXVuaWNhdGlvbnMgd2l0aCBVUFMgY29uY2VybmluZyB0aGlzIGRvY3VtZW50LCBwbGVhc2UgcmVmZXIgdG8gdGhlIGRvY3VtZW50IGRhdGUgbG9jYXRlZCBvbiB0aGUgY292ZXIuDQpDb3B5cmlnaHQNClRoZSB1c2UsIGRpc2Nsb3N1cmUsIHJlcHJvZHVjdGlvbiwgbW9kaWZpY2F0aW9uLCB0cmFuc2Zlciwgb3IgdHJhbnNtaXR0YWwgb2YgdGhpcyB3b3JrIGZvciBhbnkgcHVycG9zZSBpbiBhbnkgZm9ybSBvciBieSBhbnkgbWVhbnMgd2l0aG91dCB0aGUgd3JpdHRlbiBwZXJtaXNzaW9uIG9mIFVuaXRlZCBQYXJjZWwgU2VydmljZSBpcyBzdHJpY3RseSBwcm9oaWJpdGVkLg0KwqkgQ29weXJpZ2h0IDIwMTYgVW5pdGVkIFBhcmNlbCBTZXJ2aWNlIG9mIEFtZXJpY2EsIEluYy4gQWxsIFJpZ2h0cyBSZXNlcnZlZC4NClRyYWRlbWFya3MNClVQUyBPbkxpbmXCriBpcyBhIHJlZ2lzdGVyZWQgdHJhZGVtYXJrIG9mIFVuaXRlZCBQYXJjZWwgU2VydmljZSBvZiBBbWVyaWNhLCBJbmMuIEFsbCBvdGhlciB0cmFkZW1hcmtzIGFyZSB0aGUgcHJvcGVydHkgb2YgdGhlaXIgcmVzcGVjdGl2ZSBvd25lcnMuDQpTb21lIG9mIHRoZSBVUFMgY29ycG9yYXRlIGFwcGxpY2F0aW9ucyB1c2UgVS5TLiBjaXR5LCBzdGF0ZSwgYW5kIHBvc3RhbCBjb2RlIGluZm9ybWF0aW9uIG9idGFpbmVkIGJ5IFVuaXRlZCBQYXJjZWwgU2VydmljZSBvZiBBbWVyaWNhLCBJbmMuIHVuZGVyIGEgbm9uLWV4Y2x1c2l2ZSBsaWNlbnNlIGZyb20gdGhlIFVuaXRlZCBTdGF0ZXMgUG9zdGFsIFNlcnZpY2UuIA0K"
}
}
}

Response samples

200
400
401
403
429

application/json

{"UploadResponse": {"Response": {"ResponseStatus": {"Code": "s",
"Description": "string"
},
"Alert": [{"Code": "string",
"Description": "string"
}
],
"TransactionReference": {"CustomerContext": "string"
}
},
"FormsHistoryDocumentID": {"DocumentID": ["string"
]
}
}
}

Paperless Document Push Image

The Paperless Document API web service allows the users to upload their own customized trade documents for customs clearance to Forms History.

SecurityOAuth2

Request

path Parameters

version

required

string

Default: "v2"

Version of API

Valid values:

v2

header Parameters

transId	string An identifier unique to the request. Length 32
transactionSrc	string Default: testing An identifier of the client/source application that is making the request.Length 512
ShipperNumber required	string Shipper Number

Request Body schema: application/json

Generate sample code for popular API requests by selecting an example below. To view a full sample request and response, first click "Authorize" and enter your application credentials, then populate the required parameters above and click "Try it out".

<= 1

required

object (PushToImageRepositoryRequest) <= 1

Paperless Document API request container for push to Image Repository.

required

object (PushToImageRepositoryRequest_Request) <= 1

Contains Paperless Document API PushToImageRepository request criteria components.

RequestOption	string = 1 characters Enables the user to specify optional processing. Currently, there is no optional process in Paperless Document API.
SubVersion	string <= 1 Not Used.
	object (components-schemas-Request_TransactionReference) <= 1 TransactionReference identifies transactions between client and server.

ShipperNumber

required

string = 6 characters <= 1

The Shipper's UPS Account Number. Your UPS Account Number must have 'Upload Forms Created Offline' enabled to use this webservice.

required

object (PushToImageRepositoryRequest_FormsHistoryDocumentID) <= 13

The container for DocumentID(s).

DocumentID

required

Array of strings = 26 characters <= 13

DocumentID represents a document uploaded to Forms History.

FormsGroupID

string = 26 characters <= 1

FormsGroupID would be required in Push Request if user needs to update uploaded DocumentID(s) in Forms History.

ShipmentIdentifier

required

string [ 1 .. 19 ] characters <= 1

Shipment Identifier is required for this request.

ShipmentDateAndTime

string <= 1

The date and time of the processed shipment. Required only for small package shipments. The valid format is yyyy-MM-dd-HH.mm.ss

ShipmentType

required

string = 1 characters <= 1

Valid values are: 1 = small package, 2 = freight.

PRQConfirmationNumber

string [ 9 .. 30 ] characters <= 1

PRQ Confirmation being specified by client. Required for freight shipments.

TrackingNumber

Array of strings [ 7 .. 20 ] characters

UPS Tracking Number associated with this shipment. Required only for small package shipment.

Responses

200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

post/paperlessdocuments/{version}/image

Request samples

application/json

{"PushToImageRepositoryRequest": {"Request": {"TransactionReference": {"CustomerContext": "Your Customer Context"
}
},
"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"
}
}

Response samples

200
400
401
403
429

application/json

{"PushToImageRepositoryResponse": {"Response": {"ResponseStatus": {"Code": "s",
"Description": "string"
},
"Alert": [{"Code": "string",
"Description": "string"
}
],
"TransactionReference": {"CustomerContext": "string"
}
},
"FormsGroupID": "stringstringstringstringst"
}
}

Delete Paperless Document

The Paperless Document API web service allows the users to upload their own customized trade documents for customs clearance to Forms History.

SecurityOAuth2

Request

path Parameters

version

required

string

Default: "v2"

Version of API

Valid values:

v2

header Parameters

transId	string An identifier unique to the request. Length 32
transactionSrc	string Default: testing An identifier of the client/source application that is making the request.Length 512
ShipperNumber required	string Your Shipper Number
DocumentId required	string DocumentId representing uploaded document to Forms History. Only one DocumentID will be accepted for delete request.

Responses

200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

delete/paperlessdocuments/{version}/DocumentId/ShipperNumber

Request samples

Response samples

200
400
401
403
429

application/json

{"DeleteResponse": {"Response": {"ResponseStatus": {"Code": "s",
"Description": "string"
},
"Alert": [{"Code": "string",
"Description": "string"
}
],
"TransactionReference": {"CustomerContext": "string"
}
}
}
}

Upload Paperless DocumentDeprecated

The Paperless Document API web service allows the users to upload,delete and push to image repository their own customized trade documents for customs clearance to Forms History.

SecurityOAuth2

Request

path Parameters

deprecatedVersion

required

string

Default: "v1"

Version of API

Valid values:

v1

header Parameters

transId	string An identifier unique to the request. Length 32
transactionSrc	string Default: testing An identifier of the client/source application that is making the request.Length 512
ShipperNumber required	string Shipper Number

Request Body schema: application/json

Generate sample code for popular API requests by selecting an example below. To view a full sample request and response, first click "Authorize" and enter your application credentials, then populate the required parameters above and click "Try it out".

<= 1

required

object (UploadRequest) <= 1

Paperless Document API Request container for uploading User Created Forms.

required

object (UploadRequest_Request) <= 1

Contains Paperless Document API upload request criteria components.

RequestOption	string = 1 characters Enables the user to specify optional processing. Currently, there is no optional process in Paperless Document API.
SubVersion	string <= 1 Not Used.
	object (components-schemas-Request_TransactionReference) <= 1 TransactionReference identifies transactions between client and server.

ShipperNumber

required

string = 6 characters <= 1

The Shipper's UPS Account Number. Your UPS Account Number must have 'Upload Forms Created Offline' enabled to use this webservice.

required

Array of objects (UploadRequest_UserCreatedForm) <= 13

Array

UserCreatedFormFileName required	string [ 1 .. 300 ] characters <= 1 The name of the file.
UserCreatedFormFile required	string <= 1 The user created form file. The maximum allowable size of each file is restricted to 10 MB. Should be a base64 encoded string. Note: The maximum allowable size of each file is restriced to 1MB in CIE (Customer Integration Environment).
UserCreatedFormFileFormat required	string [ 3 .. 4 ] characters <= 1 The UserCreatedForm file format. The allowed file formats are bmp, doc, gif, jpg, pdf, png, rtf, tif, txt and xls. The only exceptions for having file format of length 4 character are docx and xlsx. All other file formats needs to be of length 3.
UserCreatedFormDocumentType required	string = 3 characters <= 13 The type of documents in UserCreatedForm file. The allowed document types are 001 - Authorization Form, 002 - Commercial Invoice, 003 - Certificate of Origin, 004 - Export Accompanying Document, 005 - Export License, 006 - Import Permit, 007 - One Time NAFTA, 008 - Other Document, 009 - Power of Attorney, 010 - Packing List, 011 - SED Document, 012 - Shipper's Letter of Instruction, 013 - Declaration. The total number of documents allowed per file or per shipment is 13. Each document type needs to be three digits.

Responses

200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

post/paperlessdocuments/{deprecatedVersion}/upload

Request samples

application/json

{"UploadRequest": {"Request": {"TransactionReference": {"CustomerContext": ""
}
},
"UserCreatedForm": {"UserCreatedFormFileName": "TestFile.txt",
"UserCreatedFormFileFormat": "txt",
"UserCreatedFormDocumentType": "013",
"UserCreatedFormFile": "Tm90aWNlDQpJbiBhbGwgY29tbXVuaWNhdGlvbnMgd2l0aCBVUFMgY29uY2VybmluZyB0aGlzIGRvY3VtZW50LCBwbGVhc2UgcmVmZXIgdG8gdGhlIGRvY3VtZW50IGRhdGUgbG9jYXRlZCBvbiB0aGUgY292ZXIuDQpDb3B5cmlnaHQNClRoZSB1c2UsIGRpc2Nsb3N1cmUsIHJlcHJvZHVjdGlvbiwgbW9kaWZpY2F0aW9uLCB0cmFuc2Zlciwgb3IgdHJhbnNtaXR0YWwgb2YgdGhpcyB3b3JrIGZvciBhbnkgcHVycG9zZSBpbiBhbnkgZm9ybSBvciBieSBhbnkgbWVhbnMgd2l0aG91dCB0aGUgd3JpdHRlbiBwZXJtaXNzaW9uIG9mIFVuaXRlZCBQYXJjZWwgU2VydmljZSBpcyBzdHJpY3RseSBwcm9oaWJpdGVkLg0KwqkgQ29weXJpZ2h0IDIwMTYgVW5pdGVkIFBhcmNlbCBTZXJ2aWNlIG9mIEFtZXJpY2EsIEluYy4gQWxsIFJpZ2h0cyBSZXNlcnZlZC4NClRyYWRlbWFya3MNClVQUyBPbkxpbmXCriBpcyBhIHJlZ2lzdGVyZWQgdHJhZGVtYXJrIG9mIFVuaXRlZCBQYXJjZWwgU2VydmljZSBvZiBBbWVyaWNhLCBJbmMuIEFsbCBvdGhlciB0cmFkZW1hcmtzIGFyZSB0aGUgcHJvcGVydHkgb2YgdGhlaXIgcmVzcGVjdGl2ZSBvd25lcnMuDQpTb21lIG9mIHRoZSBVUFMgY29ycG9yYXRlIGFwcGxpY2F0aW9ucyB1c2UgVS5TLiBjaXR5LCBzdGF0ZSwgYW5kIHBvc3RhbCBjb2RlIGluZm9ybWF0aW9uIG9idGFpbmVkIGJ5IFVuaXRlZCBQYXJjZWwgU2VydmljZSBvZiBBbWVyaWNhLCBJbmMuIHVuZGVyIGEgbm9uLWV4Y2x1c2l2ZSBsaWNlbnNlIGZyb20gdGhlIFVuaXRlZCBTdGF0ZXMgUG9zdGFsIFNlcnZpY2UuIA0K"
}
}
}

Response samples

200
400
401
403
429

application/json

{"UploadResponse": {"Response": {"ResponseStatus": {"Code": "s",
"Description": "string"
},
"Alert": [{"Code": "string",
"Description": "string"
}
],
"TransactionReference": {"CustomerContext": "string"
}
},
"FormsHistoryDocumentID": {"DocumentID": ["string"
]
}
}
}

Paperless Document Push ImageDeprecated

The Paperless Document API web service allows the users to upload their own customized trade documents for customs clearance to Forms History.

SecurityOAuth2

Request

path Parameters

deprecatedVersion

required

string

Default: "v1"

Version of API

Valid values:

v1

header Parameters

transId	string An identifier unique to the request. Length 32
transactionSrc	string Default: testing An identifier of the client/source application that is making the request.Length 512
ShipperNumber required	string Shipper Number

Request Body schema: application/json

Generate sample code for popular API requests by selecting an example below. To view a full sample request and response, first click "Authorize" and enter your application credentials, then populate the required parameters above and click "Try it out".

<= 1

required

object (PushToImageRepositoryRequest) <= 1

Paperless Document API request container for push to Image Repository.

required

object (PushToImageRepositoryRequest_Request) <= 1

Contains Paperless Document API PushToImageRepository request criteria components.

RequestOption	string = 1 characters Enables the user to specify optional processing. Currently, there is no optional process in Paperless Document API.
SubVersion	string <= 1 Not Used.
	object (components-schemas-Request_TransactionReference) <= 1 TransactionReference identifies transactions between client and server.

ShipperNumber

required

string = 6 characters <= 1

The Shipper's UPS Account Number. Your UPS Account Number must have 'Upload Forms Created Offline' enabled to use this webservice.

required

object (PushToImageRepositoryRequest_FormsHistoryDocumentID) <= 13

The container for DocumentID(s).

DocumentID

required

Array of strings = 26 characters <= 13

DocumentID represents a document uploaded to Forms History.

FormsGroupID

string = 26 characters <= 1

FormsGroupID would be required in Push Request if user needs to update uploaded DocumentID(s) in Forms History.

ShipmentIdentifier

required

string [ 1 .. 19 ] characters <= 1

Shipment Identifier is required for this request.

ShipmentDateAndTime

string <= 1

The date and time of the processed shipment. Required only for small package shipments. The valid format is yyyy-MM-dd-HH.mm.ss

ShipmentType

required

string = 1 characters <= 1

Valid values are: 1 = small package, 2 = freight.

PRQConfirmationNumber

string [ 9 .. 30 ] characters <= 1

PRQ Confirmation being specified by client. Required for freight shipments.

TrackingNumber

Array of strings [ 7 .. 20 ] characters

UPS Tracking Number associated with this shipment. Required only for small package shipment.

Responses

200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

post/paperlessdocuments/{deprecatedVersion}/image

Request samples

application/json

{"PushToImageRepositoryRequest": {"Request": {"TransactionReference": {"CustomerContext": "Your Customer Context"
}
},
"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"
}
}

Response samples

200
400
401
403
429

application/json

{"PushToImageRepositoryResponse": {"Response": {"ResponseStatus": {"Code": "s",
"Description": "string"
},
"Alert": [{"Code": "string",
"Description": "string"
}
],
"TransactionReference": {"CustomerContext": "string"
}
},
"FormsGroupID": "stringstringstringstringst"
}
}

Delete Paperless DocumentDeprecated

The Paperless Document API web service allows the users to upload their own customized trade documents for customs clearance to Forms History.

SecurityOAuth2

Request

path Parameters

deprecatedVersion

required

string

Default: "v1"

Version of API

Valid values:

v1

header Parameters

transId	string An identifier unique to the request. Length 32
transactionSrc	string Default: testing An identifier of the client/source application that is making the request.Length 512
ShipperNumber required	string Your Shipper Number
DocumentId required	string DocumentId representing uploaded document to Forms History. Only one DocumentID will be accepted for delete request.

Responses

200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

delete/paperlessdocuments/{deprecatedVersion}/DocumentId/ShipperNumber

Request samples

Response samples

200
400
401
403
429

application/json

{"DeleteResponse": {"Response": {"ResponseStatus": {"Code": "s",
"Description": "string"
},
"Alert": [{"Code": "string",
"Description": "string"
}
],
"TransactionReference": {"CustomerContext": "string"
}
}
}
}