openapi: 3.0.1
info:
  title: ACI Parcel Label API
  description: "# Getting Started with Label API\r\n\r\nThe 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. \r\n\r\nThe Label API workflow consists of three basic operations:  \r\n\r\n- `requestLabel`: Client submits package information and receives a label object in return.  \r\n\r\n- `reprintLabel`: Client may retrieve a previously-generated label object for reprinting. \r\n\r\n- `printLabel`: Clients who require an alternative label format, specifically PDF or PNG label formats. \r\n\r\n## Label Types\r\nThe 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: \r\n\r\n1. **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.  \r\n\r\n2. **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. \r\n\r\n3. **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. \r\n\r\n> **_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.\r\n\r\n## Label Formats\r\nThe 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. \r\n\r\n## Change Log\r\n- 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. "
  version: 2.1.0
servers:
  - url: https://api.acilogistix.com/aciparcellabel/v1
paths:
  /manifestlabel:
    post:
      summary: Manifest a label
      operationId: ManifestLabel
      requestBody:
        description: Manifest request object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/manifestRequest'
      responses:
        '200':
          description: Manifest response object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/manifestResponse'
      security:
        - apiKey: []
  /reprintlabel:
    post:
      summary: Reprint a label
      operationId: ReprintLabel
      requestBody:
        description: The reprint label request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/reprintLabelRequest'
      responses:
        '200':
          description: The reprint label response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/reprintLabelResponse'
      security:
        - apiKey: []
  /requestlabel:
    post:
      summary: Request a label
      description: >-
        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.
      operationId: RequestLabel
      requestBody:
        description: The request body for label generation.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/request'
            examples:
              first:
                value:
                  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
        required: true
      responses:
        '200':
          description: Payload of ResponseStr
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responseStr'
              examples:
                Sample Response:
                  value:
                    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:
                        attnLine: SHIPPING MANAGER
                        companyName: TEST COMPANY NAME
                        addressLine1: Client Address Line 1
                        addressLine2: Client Address Line 2
                        city: Grand Prairie
                        state: TX
                        zip5: '91376'
                        zip4: ''
                      shipToAddress:
                        fullName: Consignee Full Name
                        companyName: Test Customer Company
                        addressLine1: Consignee Address Line
                        addressLine2: Consignee Address Line
                        city: Calabass
                        state: CA
                        zip5: '89144'
                        zip4: null
                    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
      security:
        - apiKey: []
components:
  schemas:
    address:
      required:
        - addressLine1
        - city
        - state
        - zip5
      type: object
      properties:
        addressLine1:
          maxLength: 50
          minLength: 0
          type: string
          description: >-
            Up to 150 characters, alphanumeric; Hyphen, spaces, apostrophes and
            periods are allowed
        addressLine2:
          maxLength: 50
          minLength: 0
          type: string
          description: >-
            Up to 150 characters, alphanumeric; Hyphen, spaces, apostrophes and
            periods are allowed
        city:
          maxLength: 50
          minLength: 0
          type: string
          description: >-
            Up to 28 characters, alphanumeric; Hyphen, spaces, apostrophes and
            periods are allowed
        state:
          maxLength: 2
          minLength: 0
          type: string
          description: 2 characters; USPS state abbreviations only
        zip5:
          minLength: 1
          pattern: ^\d{5}$
          type: string
          description: 5 characters exactly; Numeric only
        zip4:
          pattern: ^\d{4}$
          type: string
          description: 4 characters exactly; Numeric only
      nullable: true
    client:
      required:
        - accountCode
        - serviceProviderKey
        - clientReferenceNumber
      type: object
      properties:
        accountCode:
          minLength: 1
          type: string
          description: Must match account code provided by ACI
          nullable: true
        serviceProviderKey:
          minLength: 1
          type: string
          description: Must match service provider key provided by ACI
          nullable: true
        clientReferenceNumber:
          maxLength: 50
          minLength: 0
          type: string
          description: Defined by client; value will be returned in the response
          nullable: true
        sku:
          maxLength: 50
          minLength: 0
          type: string
          description: Client SKU value
          nullable: true
        companyName:
          maxLength: 50
          minLength: 0
          type: string
          description: Return address company name
          nullable: true
        attnLine:
          maxLength: 50
          minLength: 0
          type: string
          description: Return address attention line
          nullable: true
        endorsements:
          type: string
          description: |-
            endorsement: Any one of the following value allowed: 

            “CHANGE SERVICE REQUESTED” 

            “ADDRESS SERVICE REQUESTED” 

            “RETURN SERVICE REQUESTED” 

            “FORWARDING SERVICE REQUESTED” 
          nullable: true
        hazmat:
          maximum: 2
          minimum: 0
          type: string
          description: |-
            Hazardous Materials indicator 

             Possible values:

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

            '1'=Hazardous Parcel

            '2'=Hazardous Limited Parcel
          nullable: true
        returnAddress:
          $ref: '#/components/schemas/address'
        address:
          $ref: '#/components/schemas/address'
    consignee:
      required:
        - fullName
        - address
      type: object
      properties:
        companyName:
          maxLength: 50
          minLength: 0
          type: string
          description: Company Name
        fullName:
          maxLength: 50
          minLength: 0
          type: string
        address:
          $ref: '#/components/schemas/address'
        email:
          maxLength: 44
          minLength: 0
          type: string
        phoneNumber:
          maxLength: 50
          minLength: 0
          type: string
    container:
      type: object
      properties:
        accountCode:
          type: string
        encodedBarcode:
          type: string
        containerEncodedBarcode:
          type: string
    customLabelInfo:
      type: object
      properties:
        reference3:
          type: string
        reference4:
          type: string
    document:
      type: object
      properties:
        format:
          type: string
      description: >-
        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
    internal:
      type: object
      properties:
        inValid:
          type: boolean
        statusCode:
          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
          type: integer
          format: int32
          default: 200
        message:
          type: string
        requestId:
          type: string
    labelElements:
      type: object
      properties:
        mailClass:
          type: string
          nullable: true
        permitNo:
          type: string
          nullable: true
        endorsements:
          type: string
          nullable: true
        preSortGroup:
          type: string
          nullable: true
        sortCode:
          type: string
          nullable: true
        encodedBarCode:
          type: string
          nullable: true
        readableBarCode:
          type: string
          nullable: true
        hazmat:
          type: string
          nullable: true
        returnAddress:
          $ref: '#/components/schemas/returnAddress'
        shipToAddress:
          $ref: '#/components/schemas/shipToAddress'
        customLabelInfo:
          $ref: '#/components/schemas/customLabelInfo'
    manifestRequest:
      type: object
      properties:
        readableBarCode:
          type: string
        encodedBarCode:
          type: string
        labelId:
          type: string
        container:
          $ref: '#/components/schemas/container'
        dimensions:
          $ref: '#/components/schemas/requestDimensions'
    manifestResponse:
      type: object
      properties:
        status:
          type: string
        statusCode:
          type: integer
          format: int32
        message:
          type: string
        createdOn:
          type: string
    reprintLabelRequest:
      type: object
      properties:
        readableBarCode:
          type: string
        encodedBarCode:
          type: string
        labelId:
          type: string
    reprintLabelResponse:
      type: object
      properties:
        status:
          type: string
        statusCode:
          type: integer
          format: int32
        message:
          type: string
        createdOn:
          type: string
        clientReferenceNumber:
          type: string
        sku:
          type: string
          nullable: true
        labelID:
          type: string
        labelElements:
          $ref: '#/components/schemas/labelElements'
        labelZPL:
          type: string
        internalStatus:
          $ref: '#/components/schemas/internal'
    request:
      required:
        - objectTypeId
        - client
        - consignee
        - dimensions
      type: object
      properties:
        isUSPSRequired:
          maximum: 1
          minimum: 0
          type: integer
          description: |-
            Defines the shipment carrier; Possible values are:

             0=ACI Direct,

             1=Postal. 

            If no value is provided, then default is 0=ACI Direct.
          format: int32
        objectTypeId:
          maximum: 1
          minimum: 1
          type: integer
          description: >-
            Defines the shipment type; 1=package/parcel.  For packages, always
            set to 1.
          format: int32
        client:
          $ref: '#/components/schemas/client'
        consignee:
          $ref: '#/components/schemas/consignee'
        dimensions:
          $ref: '#/components/schemas/requestDimensions'
        document:
          $ref: '#/components/schemas/document'
        customLabelInfo:
          $ref: '#/components/schemas/customLabelInfo'
    requestDimensions:
      required:
        - weight
        - length
        - width
        - height
      type: object
      properties:
        weightUOM:
          type: string
        dimensionUOM:
          type: string
        weight:
          type: number
          description: |-
            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)
          format: double
        length:
          type: number
          description: |-
            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)
          format: double
        width:
          type: number
          description: |-
            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)
          format: double
        height:
          type: number
          description: |-
            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)
          format: double
    responseDocument:
      type: object
      properties:
        url:
          type: string
      description: document object
    responseStr:
      type: object
      properties:
        message:
          type: string
          description: status message
        status:
          type: string
          description: 'Request status: SUCCESS/FAILURE'
        statusCode:
          type: integer
          description: request statusCode
          format: int32
        serviceType:
          type: string
          description: |-
            Selected serviceType

            'USPS' indicates a USPS label was generated

            'ACI Direct' indicates an ACI Direct label was generated
        createdOn:
          type: string
          description: |-
            request created date value (in UTC)

            ISO 8601 compliant datetime format:

            yyyy-MM-ddTHH:mm:ssZ format
        clientReferenceNumber:
          type: string
          description: passed through from the request object
        sku:
          type: string
          description: SKU client value
        labelID:
          type: string
          description: labelID value
        labelElements:
          $ref: '#/components/schemas/labelElements'
        document:
          $ref: '#/components/schemas/responseDocument'
        labelZPL:
          type: string
          description: ZPL label template populated with values
        internalStatus:
          $ref: '#/components/schemas/internal'
    returnAddress:
      required:
        - addressLine1
        - city
        - state
        - zip5
      type: object
      properties:
        attnLine:
          type: string
        companyName:
          type: string
        addressLine1:
          maxLength: 50
          minLength: 0
          type: string
          description: >-
            Up to 150 characters, alphanumeric; Hyphen, spaces, apostrophes and
            periods are allowed
        addressLine2:
          maxLength: 50
          minLength: 0
          type: string
          description: >-
            Up to 150 characters, alphanumeric; Hyphen, spaces, apostrophes and
            periods are allowed
        city:
          maxLength: 50
          minLength: 0
          type: string
          description: >-
            Up to 28 characters, alphanumeric; Hyphen, spaces, apostrophes and
            periods are allowed
        state:
          maxLength: 2
          minLength: 0
          type: string
          description: 2 characters; USPS state abbreviations only
        zip5:
          minLength: 1
          pattern: ^\d{5}$
          type: string
          description: 5 characters exactly; Numeric only
        zip4:
          pattern: ^\d{4}$
          type: string
          description: 4 characters exactly; Numeric only
      nullable: true
    shipToAddress:
      required:
        - addressLine1
        - city
        - state
        - zip5
      type: object
      properties:
        fullName:
          type: string
        companyName:
          type: string
        email:
          type: string
          nullable: true
        phoneNumber:
          type: string
          nullable: true
        addressLine1:
          maxLength: 50
          minLength: 0
          type: string
          description: >-
            Up to 150 characters, alphanumeric; Hyphen, spaces, apostrophes and
            periods are allowed
        addressLine2:
          maxLength: 50
          minLength: 0
          type: string
          description: >-
            Up to 150 characters, alphanumeric; Hyphen, spaces, apostrophes and
            periods are allowed
        city:
          maxLength: 50
          minLength: 0
          type: string
          description: >-
            Up to 28 characters, alphanumeric; Hyphen, spaces, apostrophes and
            periods are allowed
        state:
          maxLength: 2
          minLength: 0
          type: string
          description: 2 characters; USPS state abbreviations only
        zip5:
          minLength: 1
          pattern: ^\d{5}$
          type: string
          description: 5 characters exactly; Numeric only
        zip4:
          pattern: ^\d{4}$
          type: string
          description: 4 characters exactly; Numeric only
      nullable: true
  securitySchemes:
    apiKey:
      type: apiKey
      name: aci-apikey
      in: header
