Skip to content
ACI Logistix
/
/
Request a label

ACI Parcel Label API (2.1.0)

Getting Started with Label API

The ACI Label API offers clients a convenient way to request per package labels that are compliant with ACI�s service offerings. The labels include all necessary elements to complete last mile delivery to the end customer.

The Label API workflow consists of three basic operations:

  • requestLabel: Client submits package information and receives a label object in return.

  • reprintLabel: Client may retrieve a previously-generated label object for reprinting.

  • printLabel: Clients who require an alternative label format, specifically PDF or PNG label formats.

Label Types

The ACI Label may return several different label types depending on the package�s physical attributes, contents, and delivery geography. These returned labels will be compliant with the ACI delivery service model requirements. The following list defines the most common templates:

  1. ACI Direct Label: a label compliant with the ACI Direct service model. This template is similar in many ways to a USPS label template but uses a custom ACI Tracking Number value. The template includes all necessary elements (barcodes and markings) and ACI sort code values.

  2. USPS Label: a label compliant with ACI�s USPS delivery service model. This template is compliant with the USPS parcel label guidelines and IMPB barcode spec. The template includes all necessary elements (barcodes and endorsements) and ACI sort code values.

  3. USPS Hazmat Label: all packages that contain hazardous materials are required to be flagged as �Hazmat� in the request object. In all cases these packages will receive a compliant USPS label with all necessary markings and attributes.

NOTE: Although the ACI Label API may return an array of label types the request JSON object definition is the same for all label types.

Label Formats

The ACI Label API response object contains, by default, a ZPL label object. Clients may request a PNG or PDF version of the label using the printLabel Operation described in this document.

Change Log

  • 20240903 v2.1: Added the serviceType attribute in the requestLabel JSON response object. This has two enumerated values: "USPS" to indicate a USPS label was generated and "ACIDirect" when an ACI Direct label is generated. Updated the schema and example sections.
Download OpenAPI description
swagger.json
swagger.yaml
Languages
Servers
Mock server

https://developer.fastgroup.co/_mock/labelapi/swagger/

https://api.acilogistix.com/aciparcellabel/v1/

Manifest a label

Request

Security
apiKey
Bodyapplication/json

Manifest request object

readableBarCodestring
encodedBarCodestring
labelIdstring
containerobject(container)
dimensionsobject(requestDimensions)
curl -i -X POST \
  https://developer.fastgroup.co/_mock/labelapi/swagger/manifestlabel \
  -H 'Content-Type: application/json' \
  -H 'aci-apikey: YOUR_API_KEY_HERE' \
  -d '{
    "readableBarCode": "string",
    "encodedBarCode": "string",
    "labelId": "string",
    "container": {
      "accountCode": "string",
      "encodedBarcode": "string",
      "containerEncodedBarcode": "string"
    },
    "dimensions": {
      "weightUOM": "string",
      "dimensionUOM": "string",
      "weight": 0.1,
      "length": 0.1,
      "width": 0.1,
      "height": 0.1
    }
  }'

Responses

Manifest response object

Bodyapplication/json
statusstring
statusCodeinteger(int32)
messagestring
createdOnstring
Response
application/json
{
  "status": "string",
  "statusCode": 0,
  "message": "string",
  "createdOn": "string"
}

Reprint a label

Request

Security
apiKey
Bodyapplication/json

The reprint label request

readableBarCodestring
encodedBarCodestring
labelIdstring
curl -i -X POST \
  https://developer.fastgroup.co/_mock/labelapi/swagger/reprintlabel \
  -H 'Content-Type: application/json' \
  -H 'aci-apikey: YOUR_API_KEY_HERE' \
  -d '{
    "readableBarCode": "string",
    "encodedBarCode": "string",
    "labelId": "string"
  }'

Responses

The reprint label response

Bodyapplication/json
statusstring
statusCodeinteger(int32)
messagestring
createdOnstring
clientReferenceNumberstring
skustring or null
labelIDstring
labelElementsobject(labelElements)
labelZPLstring
internalStatusobject(internal)
Response
application/json
{
  "status": "string",
  "statusCode": 0,
  "message": "string",
  "createdOn": "string",
  "clientReferenceNumber": "string",
  "sku": "string",
  "labelID": "string",
  "labelElements": {
    "mailClass": "string",
    "permitNo": "string",
    "endorsements": "string",
    "preSortGroup": "string",
    "sortCode": "string",
    "encodedBarCode": "string",
    "readableBarCode": "string",
    "hazmat": "string",
    "returnAddress": { … },
    "shipToAddress": { … },
    "customLabelInfo": { … }
  },
  "labelZPL": "string",
  "internalStatus": {
    "inValid": true,
    "statusCode": 200,
    "message": "string",
    "requestId": "string"
  }
}

Request a label

Request

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.

Security
apiKey
Bodyapplication/jsonrequired

The request body for label generation.

isUSPSRequiredinteger(int32)[ 0 .. 1 ]

Defines the shipment carrier; Possible values are:

0=ACI Direct,

1=Postal.

If no value is provided, then default is 0=ACI Direct.

objectTypeIdinteger(int32)[ 1 .. 1 ]required

Defines the shipment type; 1=package/parcel. For packages, always set to 1.

clientobject(client)required
client.​accountCodestring or nullnon-emptyrequired

Must match account code provided by ACI

client.​serviceProviderKeystring or nullnon-emptyrequired

Must match service provider key provided by ACI

client.​clientReferenceNumberstring or null[ 0 .. 50 ] charactersrequired

Defined by client; value will be returned in the response

client.​skustring or null[ 0 .. 50 ] characters

Client SKU value

client.​companyNamestring or null[ 0 .. 50 ] characters

Return address company name

client.​attnLinestring or null[ 0 .. 50 ] characters

Return address attention line

client.​endorsementsstring or null

endorsement: Any one of the following value allowed:

“CHANGE SERVICE REQUESTED”

“ADDRESS SERVICE REQUESTED”

“RETURN SERVICE REQUESTED”

“FORWARDING SERVICE REQUESTED”

client.​hazmatstring or null[ 0 .. 2 ]

Hazardous Materials indicator

Possible values:

'0' or null or no field - ACI Direct Parcel

'1'=Hazardous Parcel

'2'=Hazardous Limited Parcel

client.​returnAddressobject or null(address)
client.​addressobject or null(address)
consigneeobject(consignee)required
consignee.​companyNamestring[ 0 .. 50 ] characters

Company Name

consignee.​fullNamestring[ 0 .. 50 ] charactersrequired
consignee.​addressobject or null(address)required
consignee.​address.​addressLine1string[ 0 .. 50 ] charactersrequired

Up to 150 characters, alphanumeric; Hyphen, spaces, apostrophes and periods are allowed

consignee.​address.​addressLine2string[ 0 .. 50 ] characters

Up to 150 characters, alphanumeric; Hyphen, spaces, apostrophes and periods are allowed

consignee.​address.​citystring[ 0 .. 50 ] charactersrequired

Up to 28 characters, alphanumeric; Hyphen, spaces, apostrophes and periods are allowed

consignee.​address.​statestring[ 0 .. 2 ] charactersrequired

2 characters; USPS state abbreviations only

consignee.​address.​zip5stringnon-empty^\d{5}$required

5 characters exactly; Numeric only

consignee.​address.​zip4string^\d{4}$

4 characters exactly; Numeric only

consignee.​emailstring[ 0 .. 44 ] characters
consignee.​phoneNumberstring[ 0 .. 50 ] characters
dimensionsobject(requestDimensions)required
dimensions.​weightUOMstring
dimensions.​dimensionUOMstring
dimensions.​weightnumber(double)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.​lengthnumber(double)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.​widthnumber(double)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.​heightnumber(double)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)

documentobject(document)

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

customLabelInfoobject(customLabelInfo)
curl -i -X POST \
  https://developer.fastgroup.co/_mock/labelapi/swagger/requestlabel \
  -H 'Content-Type: application/json' \
  -H 'aci-apikey: YOUR_API_KEY_HERE' \
  -d '{
    "isUSPSRequired": 0,
    "ObjectTypeId": 1,
    "Client": {
      "accountCode": "DEMO0301",
      "serviceProviderKey": "KBD4pG88vEnDHf5n",
      "clientReferenceNumber": "1234asdf2345",
      "sku": "",
      "companyName": "RDT LOGISTICS",
      "attnLine": "ATTN RETURNS DEPT.",
      "endorsements": "",
      "hazmat": "",
      "returnAddress": {
        "AddressLine1": "330 GOLDEN SHORE",
        "AddressLine2": "STE 410",
        "City": "LONG BEACH",
        "State": "CA",
        "Zip5": "90802",
        "Zip4": "4271"
      },
      "address": null
    },
    "Consignee": {
      "CompanyName": "ABC ENTERPRISES",
      "FullName": "BOB SMITH",
      "Address": {
        "AddressLine1": "2300 SCENIC DR",
        "AddressLine2": "",
        "City": "GEORGETOWN",
        "State": "TX",
        "Zip5": "78626",
        "Zip4": ""
      },
      "Email": "D045F834652047F0A96CBE3EC609A4CE@ABC.com",
      "PhoneNumber": "6128042091"
    },
    "Dimensions": {
      "WeightUOM": "lbs",
      "DimensionUOM": "in",
      "Weight": 4.1245,
      "Length": 3.51,
      "Width": 1.1,
      "Height": 2.78
    },
    "Document": {
      "Format": "pdf"
    },
    "CustomLabelInfo": null
  }'

Responses

Payload of ResponseStr

Bodyapplication/json
messagestring

status message

statusstring

Request status: SUCCESS/FAILURE

statusCodeinteger(int32)

request statusCode

serviceTypestring

Selected serviceType

'USPS' indicates a USPS label was generated

'ACI Direct' indicates an ACI Direct label was generated

createdOnstring

request created date value (in UTC)

ISO 8601 compliant datetime format:

yyyy-MM-ddTHH:mm:ssZ format

clientReferenceNumberstring

passed through from the request object

skustring

SKU client value

labelIDstring

labelID value

labelElementsobject(labelElements)
documentobject(responseDocument)

document object

labelZPLstring

ZPL label template populated with values

internalStatusobject(internal)
Response
application/json
{
  "message": "Successfully Generated Label",
  "status": "SUCCESS",
  "statusCode": 200,
  "serviceType": "USPS",
  "createdOn": "2024-08-22T05:51:01+00:00",
  "clientReferenceNumber": "TEST REF NO",
  "sku": null,
  "labelID": "1e3e1bf9b77692e7d3166344",
  "labelElements": {
    "mailClass": "PARCEL SELECT",
    "permitNo": "42632",
    "endorsements": null,
    "preSortGroup": null,
    "sortCode": "LAX-L-13",
    "encodedBarCode": "4208914492612998877002100000000517",
    "readableBarCode": "92612998877002100000000517",
    "hazmat": "0",
    "returnAddress": { … },
    "shipToAddress": { … }
  },
  "document": {
    "url": "https://api-aci.azure-api.net/aciparcelprintlabel/sandbox/v1/printLabel?documentid=1e3e1bf9b77692e7d3166344&format=pdf&output=base64"
  },
  "labelZPL": "^XA^PW830^CI28^XA^LH^FO0,0^GB0,1220,4^FS^FO0,0^GB815,0,4^FS^FO0,1215^GB813,0,4^FS^FO810,0^GB0,1220,4^FS^FO0,205^GB813,0,4^FS^FO0,0^GB0,205,4^FS^FO0,0^GB205,0,4^FSFO1,4^GD200,200,5,B,L^FS^FO1,4^GD200,200,5,B,L^FSFO1,1^GD203,203,5,B,R^FS^FO205,0^GB0,205,4^FS^FO535,30^GB240,160,4^FS^FO580,45^A0N,25,23^FDPARCEL SELECT^FS^FO560,75^A0N,25,23^FDU.S. POSTAGE PAID^FS^FO570,102^A0N,25,23^FDWASHINGTON DC^FS^FO565,130^A0N,25,23^FDPERMIT NO. 42632^FS^FO635,155^A0N,25,23^FDeVS^FS^FO145,220^A0N,55,55^FDUSPS PARCEL SELECT^FS^FO0,275^GB813,0,4^FS^FO20,290^A0N,25,26^FDSHIPPING MANAGER^FS^FO20,320^A0N,25,26^FDTEST COMPANY NAME^FS^FO20,350^A0N,25,26^FDCLIENT ADDRESS LINE 1^FS^FO20,380^A0N,25,26^FDGRAND PRAIRIE, TX 91376^FS^FO20,435^A0N,25,26^FD^FS^FO0,520^A0N,55,55^FB775,1,0,R^FDLAX-L-13^FS^FO40,595^A0N,30,26^FDSHIP TO: ^FS^FT40,730^BXN,5,200,0,0,1,_,1^FH\\\\^FD_142089144_192612998877002100000000517^FS^FO160,595^A0N,32,32^FDCONSIGNEE FULL NAME^FS^FO160,630^A0N,32,32^FDTEST CUSTOMER COMPANY^FS^FO160,665^A0N,32,32^FDCONSIGNEE ADDRESS LINE^FS^FO160,705^A0N,32,32^FDCONSIGNEE ADDRESS LINE ^FS^FO160,735^A0N,32,32^FDCALABASS, CA 89144^FS^FO160,740^A0N,32,32^FD^FS^FO0,780^GB813,0,4^FS^FO215,810^CI27^A0N,35,40^FH|^FDUSPS TRACKING # eVS^FS^FO45,862^BY3^BCN,160,N,Y,N^FD>;>842089144;>892612998877002100000000517^FS^FO125,1050^A0N,35,40^FD9261 2998 8770 0210 0000 0005 17^FS^FO0,1090^GB813,0,4^FS^FO20,1105^A0N,25,26^TBN,620,620^FDREFNO:TEST REF NO^FS^FO20,1163^A0N,25,26^TBN,620,620^FD^FS^FT675,1200^BXN,5,200,0,0,1,_,1^FH\\\\^FD_142089144_192612998877002100000000517^FS^CI0^XZ",
  "internalStatus": null
}