POST /labels/{version}/recovery

The Label Shipping API allows us to retrieve forward and return labels.

Servers

https://wwwcie.ups.com/api
https://onlinetools.ups.com/api

Path parameters

Name Type Required Description

Name	Type	Required	Description
`version`	String	Yes	When UPS introduces new elements in the response that are not associated with new request elements, Subversion is used. This ensures backward compatibility. v1 original features of the application. No support for CODTurn-inPage, HighValueReport or InternationalForms features returned in the response v1701 includes support for CODTurn-inPage features returned in the response. V1903 Length 5 Default value: "v1"

version

String

Yes

When UPS introduces new elements in the response that are not associated with new request elements, Subversion is used. This ensures backward compatibility. v1 original features of the application. No support for CODTurn-inPage, HighValueReport or InternationalForms features returned in the response v1701 includes support for CODTurn-inPage features returned in the response. V1903 Length 5

Default value: "v1"

Request headers

Name Type Required Description

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"
`transactionSrc`	String	No	An identifier of the client/source application that is making the request.Length 512 Default value: "testing"
`transId`	String	No	An identifier unique to the request. Length 32

Content-Type

String

Yes

The media type of the request body.

Default value: "application/json"

transactionSrc

String

An identifier of the client/source application that is making the request.Length 512

Default value: "testing"

transId

String

An identifier unique to the request. Length 32

Request body fields

Name	Type	Required	Description
`LabelRecoveryRequest`	Object	Yes	Request for obtaining the Label for the return shipment.
`LabelRecoveryRequest.Translate`	Object	No	Translate container allows the user to specify the language he/she would like a specific portion of response to return. The language is specified by the combination of language code and dialect code. Valid combinations are: LanguageCode + DialectCode. Either Translate container or Locale element can be present in a given request. Both can't be requested together in same request. Combinations: eng GB = Queen's English Spa 97 = Castilian Spanish ita 97 = Italian fra 97 = France French fra CA = Canadian French deu 97 = German por 97 = Portugal Portuguese nld 97 = Dutch dan 97 = Danish fin 97 = Finnish swe 97 = Swedish eng CA = Canadian English Eng US = US English Default language is Queen's English If the Ship from country or territory is Canada, the Language defaults to Canadian English. If the ship from country or territory is US, the language defaults to US English. If shipping from some other country or territory, the language defaults to Queens English.
`LabelRecoveryRequest.Translate.Code`	String	Yes	Used to specify what will be translated. Valid code: 01 = label direction instructions and receipt
`LabelRecoveryRequest.Translate.DialectCode`	String	Yes	Valid dialect codes are: CA - Canada GB - Great Britain US - United States 97 – Not Applicable
`LabelRecoveryRequest.Translate.LanguageCode`	String	Yes	The Language code. The language codes are three letter language codes. Supported languages are: eng - English spa - Spanish ita - Italian fra - French deu - German por -Portuguese nld – Dutch dan - Danish fin - Finnish swe – Swedish nor – Norwegian
`LabelRecoveryRequest.TrackingNumber`	String	No	Small Package Tracking Number. Required if Mail Innovations Tracking Number or ReferenceNumber/Value and ShipperNumber is not provided. If only TrackingNumber is provided, the request will be treated as Small Package Shipment. Label Recovery will return label for Small Package Tracking Number. If both, TrackingNumber and MailInnovationsTrackingNumber are provided, the request will be treated as Dual Mail Innovations Return Shipment. Label Recovery will return two labels one each for - Small Package Tracking Number and Mail Innovations Return Tracking Number.
`LabelRecoveryRequest.MailInnovationsTrackingNumber`	String	No	Mail Innovations Tracking Number. Required if Tracking Number or ReferenceNumber/Value is not populated. If only MailInnovationsTrackingNumber is provided, the request will be treated as Single Mail Innovations Return Shipment. Label Recovery will return label for Mail Innovations Return Tracking Number. If both, TrackingNumber and MailInnovationsTrackingNumber are provided, the request will be treated as Dual Mail Innovations Return Shipment. Label Recovery will return two labels one each for - Small Package Tracking Number and Mail Innovations Return Tracking Number.
`LabelRecoveryRequest.ReferenceValues`	Object	No	Container that holds reference number and shipper number If tracking number is not present use reference Number
`LabelRecoveryRequest.ReferenceValues.ReferenceNumber`	Object	Yes	Container for reference number
`LabelRecoveryRequest.ReferenceValues.ReferenceNumber.Value`	String	Yes	Required if TrackingNumber or Mail Innovations Tracking Number is not populated. Customer supplied reference number. Supports up to 2 customer supplied combinations of Reference code- value combinations.
`LabelRecoveryRequest.ReferenceValues.ShipperNumber`	String	Yes	Required if ReferenceNumber/Value is populated. Shipper's six digit account number. Must be six alphanumeric characters. Must be associated with the Internet account used to login.
`LabelRecoveryRequest.Request`	Object	Yes	Request Container.
`LabelRecoveryRequest.Request.RequestOption`	String	No	Request option is no longer used.
`LabelRecoveryRequest.Request.SubVersion`	String	No	When UPS introduces new elements in the response that are not associated with new request elements, Subversion is used. This ensures backward compatibility. To get such elements you need to have the right Subversion. The value of the subversion is explained in the Response element Description. Format: YYMM = Year and month of the release. Example: 1701 = 2017 January Supported values: 1701, 1707, 1903
`LabelRecoveryRequest.Request.TransactionReference`	Object	No	Container that identifies transactions between client and server.
`LabelRecoveryRequest.Request.TransactionReference.CustomerContext`	String	No	The CustomerContext Information which will be echoed during response
`LabelRecoveryRequest.LabelDelivery`	Object	No	Container for the Label Delivery accessorial. One Label Delivery per shipment.
`LabelRecoveryRequest.LabelDelivery.LabelLinkIndicator`	String	No	Indicates the Label Recovery and Receipt Recovery URL links are to be returned in the XML Response. Valid for following shipment - Print/Electronic Return Label Print/Electronic Import Control Label Forward shipment except for Mail Innovations Forward
`LabelRecoveryRequest.LabelDelivery.ResendEMailIndicator`	String	No	Not Used. If this tag is present, resend the Label Delivery notification email.
`LabelRecoveryRequest.Locale`	String	No	Represents 5 character ISO Locale that allows the user to request Reference Number Code on Label, Label instructions, Receipt instructions (if available for given tracking number) and High Value Report (if available for given tracking number) in desired language. Locale is specified by the combination of language code and country or territory code - 2 character language code and 2 character country code seperated by an underscore ('_') character. Example - de_DE. Please refer to Appendix for supported values for Locale. Either Translate container or Locale element can be present in a given request. Both can't be requested together in same request.
`LabelRecoveryRequest.UPSPremiumCareForm`	Object	No	UPS Premium Care Form container. Default is PDF when container is not provided. Valid only for Canada to Canada movements. UPS Premium Care Form will be returned in both US English and Canadian French language.
`LabelRecoveryRequest.UPSPremiumCareForm.PageSize`	String	Yes	Size of UPS Premium Care Form. Valid values: 01 = A4 Size 02 = Letter Size
`LabelRecoveryRequest.UPSPremiumCareForm.PrintType`	String	Yes	Format of UPS Premium Care Form. Valid values: 01 = PNG 02 = PDF
`LabelRecoveryRequest.LabelSpecification`	Object	No	Container that is used to define the properties required by the user to print and/ or display the UPS shipping label. Required for the shipment without return service, or shipment with PRL return service.
`LabelRecoveryRequest.LabelSpecification.HTTPUserAgent`	String	No	Browser HTTPUserAgent String. This is the preferred way of identifying GIF image type to be generated. Required if / LabelSpecification/LabelImageFormat/Code = Gif. Default to Mozilla/4.5 if this field is missing or has invalid value.
`LabelRecoveryRequest.LabelSpecification.LabelStockSize`	Object	No	Container to hold Label Height and Width information. Applicable if Label Image Code is ZPL, EPL and SPL. Ignored for other Label Image Code types.
`LabelRecoveryRequest.LabelSpecification.LabelStockSize.Width`	String	Yes	Width of the Label. Valid value is 4. Note: Label Image will only scale up to 4 X 6, even when requesting 4 X 8.
`LabelRecoveryRequest.LabelSpecification.LabelStockSize.Height`	String	Yes	Height of the Label. Only valid values are 6 or 8. Note: Label Image will only scale up to 4 X 6, even when requesting 4 X 8.
`LabelRecoveryRequest.LabelSpecification.LabelImageFormat`	Object	No	The file format of the label and receipt. Defaults to HTML format if this node does not exist.
`LabelRecoveryRequest.LabelSpecification.LabelImageFormat.Code`	String	Yes	File type that the label is to be generated in. Valid values are: GIF -- label is in HTML format. PDF -- label is in PDF format. ZPL -- Thermal label in ZPL format. EPL -- Thermal label in EPL2 format. SPL -- Thermal label in SPL format. Default is GIF
`LabelRecoveryRequest.LabelSpecification.LabelImageFormat.Description`	String	No	Description of the label image format code.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.