# Create ERR Single Coversheet

This API generates Electronic Return Receipt (ERR) artifacts for a parcel, including a coversheet, ERR barcode, and ERR stamp. The response output can be configured using the `type` parameter to return a coversheet, barcode and stamp images, or all outputs.

Endpoint: POST /api/v1/err/coverSheet
Version: 1.0.0
Security: bearerAuth

## Header parameters:

  - `X-PB-LocationId` (string)
    The X-PB-LocationId header identifies the enterprise, division, or partner location under which a shipment is processed and billed.
If this header is not provided, the system automatically uses the enterprise-level location that was created during developer account onboarding. This default location is then used for shipment processing, carrier selection, and billing.

**Location Scope**

- Carrier accounts and services available in a request must belong to the specified location or the default enterprise location.
- Attempting to use carriers or services that are not configured for the resolved location will result in a validation error.

**Requirement Rules**

- The `X-PB-LocationId` header is optional when the shipment origin country code matches the enterprise's default address country code.
- The `X-PB-LocationId` header is required when the shipment origin country code differs from the enterprise's default address country code.
- If the header is required but not provided, the API returns a validation error indicating that the location must be specified for the given shipment origin.

## Request fields (application/json):

  - `format` (string)
    The file format of the coversheet. For coversheet, supported format is `PDF`. For barcode and stamp, supported format is `GIF`
    Enum: "PDF", "GIF"

  - `size` (string)
    The size of the coversheet. Default size is `10`. This is applicable only for coversheet.
    Enum: "10", "6X9.5", "6X9", "9.5x12"

  - `type` (string, required)
    The type of the output.
- COVERSHEET: Returns coversheet output (backward compatible).
- BARCODE.STAMP: Returns separate outputs for the ERR barcode and ERR stamp.
- ALL: Returns three outputs:
  - coversheet (Content Type: URL, Format: PDF)
  - ERR barcode (Content Type: BASE64, Format: GIF)
  - ERR stamp (Content Type: URL, Format: GIF)
    Enum: "COVERSHEET", "ALL", "BARCODE.STAMP"

  - `carrierAccountId` (string, required)
    A unique identifier assigned to the specific carrier account. Its value can be referred from the response of `Get Carrier Accounts` API.
    Example: JPZlE8DldKwx

  - `parcelType` (string, required)
    Type of the parcel, such as Letter or Envelope.
    Enum: "LGENV", "PKG", "LTR"

  - `serviceId` (string, required)
    The unique identifier given to the carrier specific service, such as First Class Mail (FCM). It can be referred from response of `Get Services` API.
    Example: FCM

  - `specialServices` (array, required)
    List of special services applied.
    Example: [{"specialServiceId":"Cert"},{"specialServiceId":"ERR"}]

  - `specialServices.specialServiceId` (string)
    The ID of the special service. Cert is mandatory special service.
    Enum: "Cert", "ERR"

  - `fromAddress` (object, required)

  - `fromAddress.name` (string)
    Name of the person or entity.
    Example: Ankush Monga

  - `fromAddress.addressLine1` (string)
    First line of the address.
    Example: 27 Waterview Dr

  - `fromAddress.addressLine2` (string)
    The addressLine2 contains Street address or Landmark (if any).
    Example: near abc street

  - `fromAddress.addressLine3` (string)
    The addressLine3 contains P.O. Box (if any) near the address.
    Example: near xyz street

  - `fromAddress.cityTown` (string)
    City or town of the address.
    Example: Shelton

  - `fromAddress.stateProvince` (string)
    State or province of the address. It is the `2-letter` State or Province Code for US address(es).
    Example: CT

  - `fromAddress.postalCode` (string)
    The Postal Code or ZIP Code of the address.  For US addresses, use only `9-digit` ZIP Code.
    Example: 06484-4361

  - `fromAddress.countryCode` (string)
    Country code of the address.
    Example: US

  - `fromAddress.phone` (string)
    Phone number associated with the address.
    Example: 203-555-1213

  - `fromAddress.company` (string)
    The name of the company, in case if the sender address is not residential.  `Max length = 30`.
    Example: PB

  - `fromAddress.email` (string)
    This must be sender's valid email. Email is required if the customer is using GoFor Carrier.  `Max length = 30`
    Example: testuser@gmail.com

  - `fromAddress.inductionPostalCode` (string)
    The postal code where the shipment is tendered to the carrier. If an induction postal code is specified in the "fromAddress", it will be used for rate calculations and determining manifest eligibility instead of the standard postal code. If not specified, the postal code from the "fromAddress" will be used.
    Example: 06905

  - `fromAddress.residential` (boolean)
    The specified address can be Residential or Official. In case if the address is Residential, the boolean value will be 'true', else it will take 'false'.
    Example: true

  - `parcel` (object, required)

  - `parcel.weight` (number)
    The weight of the parcel.
    Example: 0.1

  - `parcel.weightUnit` (string)
    The unit of the parcel weight.
    Example: OZ

  - `parcel.length` (number)
    The length of the parcel.
    Example: 1

  - `parcel.height` (number)
    The height of the parcel.
    Example: 1

  - `parcel.width` (number)
    The width of the parcel.
    Example: 0.1

  - `parcel.dimUnit` (string)
    The dimensional unit of the parcel.
    Example: IN

  - `toAddress` (object, required)

  - `toAddress.name` (string)
    Name of the person or entity.
    Example: test_user

  - `toAddress.addressLine1` (string)
    First line of the address.
    Example: 27 Waterview Dr

  - `toAddress.addressLine2` (string)
    The addressLine2 contains Street address or Landmark (if any).
    Example: near abc street

  - `toAddress.addressLine3` (string)
    The addressLine3 contains P.O. Box (if any) near the address.
    Example: near xyz street

  - `toAddress.cityTown` (string)
    City or town of the address.
    Example: Shelton

  - `toAddress.stateProvince` (string)
    State or province of the address. It is the `2-letter` State or Province Code for US address(es).
    Example: CT

  - `toAddress.postalCode` (string)
    The Postal Code or ZIP Code of the address.  For US addresses, use only `9-digit` ZIP Code.
    Example: 06484-4361

  - `toAddress.countryCode` (string)
    Country code of the address.
    Example: US

  - `toAddress.phone` (string)
    Phone number associated with the address.
    Example: 203-555-1213

  - `toAddress.company` (string)
    The name of the company, in case if the receiver address is not residential.  `Max length = 30`.
    Example: PB

  - `toAddress.email` (string)
    This must be recipient’s valid email. Email is required if the customer is using GoFor Carrier.  `Max length = 30`
    Example: testuser@gmail.com

  - `toAddress.residential` (boolean)
    The specified address can be Residential or Official. In case if the address is Residential, the boolean value will be 'true', else it will take 'false'.
    Example: true

  - `shipmentOptions` (object)

  - `shipmentOptions.printCustomMessage` (string)
    A custom message printed on the coversheet. You can pass either print custom message or reference1 under shippingReference. If both are supplied, they will be concatenated.
    Example: thankyou

  - `shipmentOptions.addToManifest` (boolean)
    The option asks if the shipment is to be added for Manifest, so that the shipment will reflect in the Manifest Form while compilation. The value can be 'true' or 'false'. Applicable for USPS and CPC carriers.
    Example: true

  - `metadata` (array)
    Additional metadata that needs to be stored for this shipment can be added here. Supported values are [Cost Account Name, Cost Account Id, Cost Account Code](/openapi/costaccount/cost-account-management/addcostaccount), [Account Code](/openapi/billingcodes/account-code/createaccountcode) and [Company Code](/openapi/billingcodes/company-code/createcompanycode).If Cost Account metadata is provided, all three Cost Account fields are required.
    Example: [{"name":"costAccountName","value":"costAccountName"},{"name":"costAccountId","value":"costAccountId"},{"name":"costAccountCode","value":"Code"}]

  - `metadata.name` (string)
    The name of the metadata field.
    Example: costAccountName

  - `metadata.value` (string)
    The value of the metadata field.
    Example: cost account 123

  - `shippingReferences` (object)
    Contains additional reference fields that can be passed with an ERR request (single piece or batch). While USPS only accepts a single reference, these fields are used for internal tracking, exports, and reporting.

  - `shippingReferences.reference1` (string)
    Primary reference field, printed on the coversheet under the label `Shipper Ref`. If `reference1` and `printCustomMessage` are both supplied, they will be concatenated and printed on the coversheet under the label `Shipper Ref`.
    Example: reference1

  - `shippingReferences.reference2` (string)
    Secondary reference field.
    Example: reference2

  - `shippingReferences.reference3` (string)
    Tertiary reference field.
    Example: reference3

  - `shippingReferences.reference4` (string)
    Additional reference field.
    Example: reference4

  - `shippingReferences.shipperReference` (string)
    Reference provided by the shipper.
    Example: Shipper123

  - `shippingReferences.transportationReference` (string)
    Reference related to transportation.
    Example: TransRef2025

  - `shippingReferences.shipperNotes` (string)
    Optional notes from the shipper.
    Example: Handle with care

## Response 200 fields (application/json):

  - `fromAddress` (object)

  - `fromAddress.name` (string)
    Name of the person or entity.
    Example: Ankush Monga

  - `fromAddress.addressLine1` (string)
    First line of the address.
    Example: 27 Waterview Dr

  - `fromAddress.addressLine2` (string)
    The addressLine2 contains Street address or Landmark (if any).
    Example: near abc street

  - `fromAddress.addressLine3` (string)
    The addressLine3 contains P.O. Box (if any) near the address.
    Example: near xyz street

  - `fromAddress.cityTown` (string)
    City or town of the address.
    Example: Shelton

  - `fromAddress.stateProvince` (string)
    State or province of the address. It is the `2-letter` State or Province Code for US address(es).
    Example: CT

  - `fromAddress.postalCode` (string)
    The Postal Code or ZIP Code of the address.  For US addresses, use only `9-digit` ZIP Code.
    Example: 06484-4361

  - `fromAddress.countryCode` (string)
    Country code of the address.
    Example: US

  - `fromAddress.phone` (string)
    Phone number associated with the address.
    Example: 203-555-1213

  - `fromAddress.company` (string)
    The name of the company, in case if the sender address is not residential.  `Max length = 30`.
    Example: PB

  - `fromAddress.email` (string)
    This must be sender's valid email. Email is required if the customer is using GoFor Carrier.  `Max length = 30`
    Example: testuser@gmail.com

  - `fromAddress.inductionPostalCode` (string)
    The postal code where the shipment is tendered to the carrier. If an induction postal code is specified in the "fromAddress", it will be used for rate calculations and determining manifest eligibility instead of the standard postal code. If not specified, the postal code from the "fromAddress" will be used.
    Example: 06905

  - `fromAddress.residential` (boolean)
    The specified address can be Residential or Official. In case if the address is Residential, the boolean value is 'true', else it is 'false'.

  - `toAddress` (object)

  - `toAddress.name` (string)
    Name of the person or entity.
    Example: test_user

  - `toAddress.addressLine1` (string)
    First line of the address.
    Example: 27 Waterview Dr

  - `toAddress.addressLine2` (string)
    The addressLine2 contains Street address or Landmark (if any).
    Example: near abc street

  - `toAddress.addressLine3` (string)
    The addressLine3 contains P.O. Box (if any) near the address.
    Example: near xyz street

  - `toAddress.cityTown` (string)
    City or town of the address.
    Example: Shelton

  - `toAddress.stateProvince` (string)
    State or province of the address. It is the `2-letter` State or Province Code for US address(es).
    Example: CT

  - `toAddress.postalCode` (string)
    The Postal Code or ZIP Code of the address.  For US addresses, use only `9-digit` ZIP Code.
    Example: 06484-4361

  - `toAddress.countryCode` (string)
    Country code of the address.
    Example: US

  - `toAddress.phone` (string)
    Phone number associated with the address.
    Example: 203-555-1213

  - `toAddress.company` (string)
    The name of the company, in case if the receiver address is not residential.  `Max length = 30`.
    Example: PB

  - `toAddress.email` (string)
    This must be recipient’s valid email. Email is required if the customer is using GoFor Carrier.  `Max length = 30`
    Example: testuser@gmail.com

  - `toAddress.residential` (boolean)
    The specified address can be Residential or Official. In case if the address is Residential, the boolean value is 'true', else it is 'false'.

  - `labelLayout` (array)
    Example: [{"contentType":"URL","contents":"https://225934331380-spa-bpod-files-prd.s3.us-east-1.amazonaws.com/trk-barcode/898643/9414809898643519783477.pdf?..................","fileFormat":"PDF","size":"9.5X12…

  - `labelLayout.fileFormat` (string)
    The file format of the coversheet.
    Example: PDF

  - `labelLayout.size` (string)
    The size of the coversheet.
    Example: 6X9.5

  - `labelLayout.type` (string)
    The type of the coversheet.
    Example: COVERSHEET

  - `labelLayout.contentType` (string)
    Specifies how the label content is encoded.
    Example: URL

  - `labelLayout.contents` (string)
    The content of the label is URL.
    Example: https://225934331380-spa-bpod-files-dev.s3-fips.us-east-1.amazonaws.com/trk-barcode/898643/9414809898643517920904.pdf?...................................

  - `parcel` (object)

  - `parcel.weight` (number)
    The weight of the parcel.
    Example: 0.1

  - `parcel.weightUnit` (string)
    The unit of the parcel weight.
    Example: OZ

  - `parcel.length` (number)
    The length of the parcel.
    Example: 1

  - `parcel.height` (number)
    The height of the parcel.
    Example: 1

  - `parcel.width` (number)
    The width of the parcel.
    Example: 0.1

  - `parcel.dimUnit` (string)
    The dimensional unit of the parcel.
    Example: IN

  - `shipmentOptions` (object)

  - `shipmentOptions.addToManifest` (boolean)
    The option asks if the shipment is to be added for Manifest, so that the shipment will reflect in the Manifest Form while compilation. The value can be 'true' or 'false'. Applicable for USPS and CPC carriers.
    Example: true

  - `shipmentOptions.printCustomMessage` (string)
    A custom message printed on the coversheet.
    Example: thankyou

  - `shipmentId` (string)
    A unique identifier for a Shipment.
    Example: 670d1820222f6a010ab3152c

  - `parcelTrackingNumber` (string)
    The tracking number associated with the parcel in a shipment.
    Example: 9414809898643517885166

  - `rate` (object)

  - `rate.totalCarrierCharge` (number)
    The total amount payable to the carrier.
    Example: 8.97

  - `correlationId` (string)
    Key assigned by the shipping system to the transaction.
    Example: 65cc49aa8aeb46c1a77b1fc82a5ecba4

## Response 400 fields (application/json):

  - `errorCode` (string)
    Error code(s) that appear due to HTTP  400- Invalid or Bad Request, e.g., validation-error.
    Example: validation_error

  - `errorDescription` (string)
    The HTTP 400 Bad Request response status code indicates that the server cannot process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
    Example: string

  - `additionalCode` (string)
    A unique identifier for the error, for example 1101055, 0100008, or 1021126.

  - `additionalInfo` (string)
    This is an additional information about the error. This error 'Invalid Request' might appear due to invalid dimension, weight, or serviceID, or if the information is missing.

  - `additionalParameters` (array)

## Response 401 fields (application/json):

  - `message` (string, required)
    This is HTTP 401 Unauthorized response status code, which indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource.

## Response 500 fields (application/json):

  - `message` (string, required)
    This is HTTP 500 Internal Server Error response status code, which indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.