# Request a label Clients submit a single request object for each package. The request object must include common package attributes. The API will validate each label request. Passing requests receive a label response object. Endpoint: POST /requestlabel Version: 2.1.0 Security: apiKey ## Request fields (application/json): - `isUSPSRequired` (integer) Defines the shipment carrier; Possible values are: 0=ACI Direct, 1=Postal. If no value is provided, then default is 0=ACI Direct. - `objectTypeId` (integer, required) Defines the shipment type; 1=package/parcel. For packages, always set to 1. - `client` (object, required) - `client.accountCode` (string,null, required) Must match account code provided by ACI - `client.serviceProviderKey` (string,null, required) Must match service provider key provided by ACI - `client.clientReferenceNumber` (string,null, required) Defined by client; value will be returned in the response - `client.sku` (string,null) Client SKU value - `client.companyName` (string,null) Return address company name - `client.attnLine` (string,null) Return address attention line - `client.endorsements` (string,null) endorsement: Any one of the following value allowed: “CHANGE SERVICE REQUESTED” “ADDRESS SERVICE REQUESTED” “RETURN SERVICE REQUESTED” “FORWARDING SERVICE REQUESTED” - `client.hazmat` (string,null) Hazardous Materials indicator Possible values: '0' or null or no field - ACI Direct Parcel '1'=Hazardous Parcel '2'=Hazardous Limited Parcel - `client.returnAddress` (object,null) - `client.returnAddress.addressLine1` (string, required) Up to 150 characters, alphanumeric; Hyphen, spaces, apostrophes and periods are allowed - `client.returnAddress.addressLine2` (string) Up to 150 characters, alphanumeric; Hyphen, spaces, apostrophes and periods are allowed - `client.returnAddress.city` (string, required) Up to 28 characters, alphanumeric; Hyphen, spaces, apostrophes and periods are allowed - `client.returnAddress.state` (string, required) 2 characters; USPS state abbreviations only - `client.returnAddress.zip5` (string, required) 5 characters exactly; Numeric only - `client.returnAddress.zip4` (string) 4 characters exactly; Numeric only - `client.address` (object,null) - `consignee` (object, required) - `consignee.companyName` (string) Company Name - `consignee.fullName` (string, required) - `consignee.email` (string) - `consignee.phoneNumber` (string) - `dimensions` (object, required) - `dimensions.weightUOM` (string) - `dimensions.dimensionUOM` (string) - `dimensions.weight` (number, required) package weight 7-digit, numeric; Periods allowed; Leading and traling zeros preferred. Weight cannot be zero. Format examples: - 1.0020 - 08.1234 - 10.0000 - 1.5 (stored as 1.5000) - 1.53 (stored as 1.5300) - `dimensions.length` (number, required) package length 7-digit, numeric; Periods allowed; Leading and traling zeros preferred. Length cannot be zero. Format examples: - 1.0020 - 08.1234 - 10.0000 - 1.5 (stored as 1.5000) - 1.53 (stored as 1.5300) - `dimensions.width` (number, required) package width 7-digit, numeric; Periods allowed; Leading and traling zeros preferred. Width cannot be zero. Format examples: - 1.0020 - 08.1234 - 10.0000 - 1.5 (stored as 1.5000) - 1.53 (stored as 1.5300) - `dimensions.height` (number, required) package height 7-digit, numeric; Periods allowed; Leading and traling zeros preferred. Height cannot be zero. Format examples: - 1.0020 - 08.1234 - 10.0000 - 1.5 (stored as 1.5000) - 1.53 (stored as 1.5300) - `document` (object) To receive a URL link to a PDF label, set this value to 'PDF' To receive a URL link to a PNG label, set this value to 'PNG' Leaving this field blank will return no URL as the system assumes you intend to use ZPL or your own label format - `document.format` (string) - `customLabelInfo` (object) - `customLabelInfo.reference3` (string) - `customLabelInfo.reference4` (string) ## Response 200 fields (application/json): - `message` (string) status message - `status` (string) Request status: SUCCESS/FAILURE - `statusCode` (integer) request statusCode - `serviceType` (string) Selected serviceType 'USPS' indicates a USPS label was generated 'ACI Direct' indicates an ACI Direct label was generated - `createdOn` (string) request created date value (in UTC) ISO 8601 compliant datetime format: yyyy-MM-ddTHH:mm:ssZ format - `clientReferenceNumber` (string) passed through from the request object - `sku` (string) SKU client value - `labelID` (string) labelID value - `labelElements` (object) - `labelElements.mailClass` (string,null) - `labelElements.permitNo` (string,null) - `labelElements.endorsements` (string,null) - `labelElements.preSortGroup` (string,null) - `labelElements.sortCode` (string,null) - `labelElements.encodedBarCode` (string,null) - `labelElements.readableBarCode` (string,null) - `labelElements.hazmat` (string,null) - `labelElements.returnAddress` (object,null) - `labelElements.returnAddress.attnLine` (string) - `labelElements.returnAddress.companyName` (string) - `labelElements.returnAddress.addressLine1` (string, required) Up to 150 characters, alphanumeric; Hyphen, spaces, apostrophes and periods are allowed - `labelElements.returnAddress.addressLine2` (string) Up to 150 characters, alphanumeric; Hyphen, spaces, apostrophes and periods are allowed - `labelElements.returnAddress.city` (string, required) Up to 28 characters, alphanumeric; Hyphen, spaces, apostrophes and periods are allowed - `labelElements.returnAddress.state` (string, required) 2 characters; USPS state abbreviations only - `labelElements.returnAddress.zip5` (string, required) 5 characters exactly; Numeric only - `labelElements.returnAddress.zip4` (string) 4 characters exactly; Numeric only - `labelElements.shipToAddress` (object,null) - `labelElements.shipToAddress.fullName` (string) - `labelElements.shipToAddress.email` (string,null) - `labelElements.shipToAddress.phoneNumber` (string,null) - `labelElements.customLabelInfo` (object) - `labelElements.customLabelInfo.reference3` (string) - `labelElements.customLabelInfo.reference4` (string) - `document` (object) document object - `document.url` (string) - `labelZPL` (string) ZPL label template populated with values - `internalStatus` (object) - `internalStatus.inValid` (boolean) - `internalStatus.statusCode` (integer) Enum: 200, 201, 400, 500, 550, 551, 552, 553, 554, 555, 556, 557, 558, 601, 602, 603, 604, 605, 606, 607, 608, 609, 610, 611, 612, 613, 614, 615, 616, 617, 618, 619, 620, 621, 622, 623, 624, 625, 626, 627, 628, 701, 702, 703, 704, 705, 706, 707, 708, 709, 710, 711, 712, 713, 714, 715, 716, 717, 718, 719, 720, 721, 722, 723, 725, 726, 727, 728, 729, 730, 807, 808, 809, 810, 811, 812, 813, 815, 816, 817, 822, 823, 824, 825, 826, 827, 828, 829, 830, 831, 832, 833, 834, 835, 836, 837, 838, 839, 840, 841, 842, 843, 844 - `internalStatus.message` (string) - `internalStatus.requestId` (string)