# Create Bulk Shipments ERR

ERR (Electronic Return Receipt) is an official United States Postal Service® (USPS) document designed to be equivalent to the hardcopy 'green card' Return Receipt. 
It provides the following information:
- Name of the Recipient
- Time when article is delivered
- Signature (image) of the Recipient
- Address where the item is delivered, and
- Date when the article gets delivered.

ERR is combined with certain classes and categories of mails, which are as follow:
- First-Class Mail®
- Priority Mail®

ERR Batch supports two types of Shipment Document format:
- Shipping Label
- Coversheet

This API "Create Bulk Shipments with ERR" operation requires the following information:
- Recipient (Single or Multiple)
- Carrier - USPS
- Service
- Parcel Type, and
- Special Service.

The ERR API works at two levels: Shipment level and Root level. Root level is marked as Default, where multiple shipments are processed and entities are common for all shipments. While at Shipment level, entities might differ. 
User can either define values for *CarrierAccountID*, *ParcelType*, *ServiceID*, and *SpecialService* respectively at the Root level for all shipments, or mention the values at Shipment level, i.e., for individual shipment(s).
If user does not provide values for the above-mentioned fields combinedly at Shipment level, then the default values for these fields provided at Root level will be considered. While, if user provides these values combinedly at Shipment Level for individual shipment(s), it will override the values defined at Root level. 

*Condition: The fields *CarrierAccountID*, *ParcelType*, *ServiceID* are treated as a combination, and values against each field must be provided if user selects Shipment level. In case any of these field(s) out of the mentioned combination is/are missing, it will return validation error.*

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

## Security:

  - `bearerAuth` (unknown)
    http bearer

## Header parameters:

  - `X-PB-Developer-Partner-ID` (string)
    The Developer-Partner-ID is assigned by PB to uniquely identify a developer's strategic business partners. If the developer is the sole business partner, this field is not required.

## Request body:

  - `application/json` (unknown)
    This is the request body to create Bulk Shipment for ERR.

## Request fields (application/json):

  - `name` (string, required)
    Name of the of ERR Batch which consists of multiple shipments (shipments in bulk) for Label printing, e.g. ERR-Bulk05.
    Example: ERR-Bulk05

  - `groupName` (string)
    Indicates the name of the group of batches, which consists of multiple Batch groups.

  - `size` (string, required)
    This indicates the label size of the Bulk Shipment when it gets printed,i.e., DocSize. This has two options 8' X 11' or 4' X 6'.
    Enum: "DOC_8X11", "DOC_4X6"

  - `type` (string, required)
    Indicates the type of the Batch Shipment, e.g., Shipping Label.
    Enum: "SHIPPING_LABEL"

  - `format` (string)
    Defines the type of the shipment which is printed, e.g., Shipping label gets printed in PDF form.
    Enum: "PDF"

  - `carrierAccountId` (string, required)
    A unique identifier associated with the Carrier account used by client users during shipment process. Default CarrierAccountID for this batch will be user's registered USPS account. User can override this value by defining it at Shipment level.
    Example: qnpB1VkRMmw

  - `serviceId` (string, required)
    A unique identifier given to the carrier-specific service. User can override this value by defining it at Shipment level.
    Example: PM

  - `parcelType` (string, required)
    Parcel Type is required for creating a shipment while rating a parcel. And it varies as per USPS selected services, e.g. FRPKG, LGENV, TUBE, and PKG. User can override this value by defining it at Shipment level.
    Example: PKG

  - `parcelID` (string)
    A unique identifier given to the parcel or package corresponding to the selected service. This is optional field, but is used in few cases. Examples include BLM10, B1095, MT1098, etc. User can override this value by defining it at Shipment level.
    Example: PMB4

  - `specialServices` (array)
    Example: [{"specialServiceID":"ERR"},{"specialServiceID":"Cert"},{"specialServiceID":"CertRD"}]

  - `specialServices.specialserviceId` (string)
    A unique identifier associated with the Special Service, will be mentioned in this column. If user selects additional service will be entered here.
    Enum: "ERR", "Cert", "CertRD"

  - `shipments` (array, required)

  - `shipments.externalId` (string)
    This is a user-defined value provided by users just for their reference. This is for mapping purpose against each shipment.

  - `shipments.fromAddress` (object, required)
    The complete address of the Sender.

  - `shipments.fromAddress.name` (string, required)
    The name of the Sender to which this address points. `Max length = 40`
    Example: Anupama

  - `shipments.fromAddress.addressLine1` (string, required)
    The addressLine1 contains the Flat number, Building or Apartment Name/number (if any) or company name (if not residential) of the Sender.  `Max length = 40`
    Example: 27 Watervw Dr

  - `shipments.fromAddress.addressLine2` (string)
    The addressLine2 contains the Area or Street Name. This is an optional field.  `Max length = 40`
    Example: Street-257

  - `shipments.fromAddress.addressLine3` (string)
    The addressLine3 contains other details for easy reach, e.g. Landmark. This is an optional field.  `Max length = 40`
    Example: Near XZ Tower

  - `shipments.fromAddress.cityTown` (string, required)
    The name of the city or town the Sender's address belongs to.
    Example: Stamford

  - `shipments.fromAddress.stateProvince` (string, required)
    The name of the State or Province the Sender belongs to. It is the `2-letter` State or Province Code for US or Canadian address(es).  Below is the hyperlink for CA country that will navigate to its Province/State Codes page. Similarly, respective country users can check for their country- State/Province codes.  Please switch to the `Search` tab, select `Country codes` radio button, enter the required country name or country code, and then click `SEARCH` button.
    Example: CT

  - `shipments.fromAddress.postalCode` (string, required)
    The Postal Code or ZIP Code of the address.  For US addresses, use either the `5-digit` or `9-digit` ZIP Code in one of the following formats: '12345' or '12345-6789'.  While for CA addresses, use a `six-character` alphanumeric string Postal Code in this format: 'A1A 1A1'.   *NOTE: USPS supports only US location.*
    Example: 6905

  - `shipments.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. Supported for Create Bulk Shipment API.
    Example: 06905

  - `shipments.fromAddress.countryCode` (string, required)
    The country in which the sender's address is located. The value will be the two-character ISO Code of the country from the ISO country list.  Use ISO 3166-1 Alpha-2 standard values. For best results this should be included, especially if the country name does not appear in any of the unparsedAddressLines.  Below is the hyperlink, please select `Country codes` and then click `SEARCH` button.  *NOTE: USPS supports only US location.*
    Example: US

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

  - `shipments.fromAddress.phone` (string)
    This is sender's phone number. Enter the digits with or without spaces or hyphens.  `Max length = 15`.
    Example: 203-555-1213

  - `shipments.fromAddress.email` (string)
    This must be sender's valid email.  `Max length = 50`
    Example: anupama.k@gmail.com

  - `shipments.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

  - `shipments.toAddress` (object, required)
    The complete address of the Recipient or Department (in case if the address is not pointed to any individual recipient).

  - `shipments.toAddress.name` (string, required)
    The name of the Recipient.  `Max length = 40`
    Example: John Smith

  - `shipments.toAddress.addressLine1` (string, required)
    The addressLine1 contains the Flat number, Building or Apartment Name/number (if any) or company name (if not residential) of the Recipient.  `Max length = 40`
    Example: 98 Watervw Dr

  - `shipments.toAddress.addressLine2` (string)
    The addressLine2 contains the Area or Street Name. This is an optional field.  `Max length = 40`
    Example: Street-975

  - `shipments.toAddress.addressLine3` (string)
    The addressLine3 contains other details for easy reach, e.g. Landmark. This is an optional field.  `Max length = 40`
    Example: Near ABC Tower

  - `shipments.toAddress.cityTown` (string, required)
    The name of the city or town the Recipient belongs to.
    Example: Shelton

  - `shipments.toAddress.stateProvince` (string, required)
    The name of the State or Province the Sender belongs to. It is the `2-letter` State or Province Code for US or Canadian address(es).  Below is the hyperlink for CA country that will navigate to its Province/State Codes page. Similarly, respective country users can check for their country- State/Province codes.  Please switch to the `Search` tab, select `Country codes` radio button, enter the required country name or country code, and then click `SEARCH` button .  `Max length = 2`
    Example: CT

  - `shipments.toAddress.postalCode` (string, required)
    The Postal Code or ZIP Code of the address. For US addresses, use either the `5-digit` or `9-digit` ZIP Code in one of the following formats: '12345' or '12345-6789'.  While for CA addresses, use a `six-character` alphanumeric string Postal Code in this format: 'A1A 1A1'. ERR supports only US addresses. *NOTE: USPS supports only US location.*
    Example: 6905

  - `shipments.toAddress.countryCode` (string, required)
    The country in which the recipient's address is located. The value will be the two-character ISO Code of the country from the ISO country list.  Use ISO 3166-1 Alpha-2 standard values. For best results this should be included, especially if the country name does not appear in any of the unparsedAddressLines.  Below is the hyperlink, please select `Country codes` and then click `SEARCH` button.   *NOTE: USPS supports only US location.*
    Example: US

  - `shipments.toAddress.company` (string)
    The name of the company, in case if the Recipient address is not residential.
    Example: PB

  - `shipments.toAddress.phone` (string)
    This is recipient's phone number. Enter the digits with or without spaces or hyphens.  `Max length = 15`.
    Example: 203-555-1213

  - `shipments.toAddress.email` (string)
    This must be recipients's valid email.  `Max length = 50`
    Example: anupama.kr@gmail.com

  - `shipments.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

  - `shipments.parcel` (object, required)
    The details of the Parcel.

  - `shipments.parcel.length` (number)
    Length is always the greatest of the three dimensions. The other two dimensions are used in the calculation of the girth.
    Example: 2

  - `shipments.parcel.width` (number)
    There is no strict rule as to which element is the width or the height, but the width is the second greatest dimension of a parcel by convention.
    Example: 1

  - `shipments.parcel.height` (number)
    By convention the height is the smallest dimension of the parcel.
    Example: 1

  - `shipments.parcel.dimUnit` (string)
    DimUnit is a standard for measuring the physical quantities of specified dimension parameters. The valid values are: Inch and Centimeter.
    Enum: "IN", "CM"

  - `shipments.parcel.weightUnit` (string, required)
    WeightUnit is a standard for measuring the physical quantities of specified weight. The valid values are: Ounces and Grams. For USPS shipments, set this to OZ.
    Enum: "OZ", "GM"

  - `shipments.parcel.weight` (number)
    Weight measures the heaviness of an object (how heavy an object is) .
    Example: 2

  - `shipments.carrierAccountId` (string)
    A unique identifier associated with the Carrier account used by client users during shipment process.
    Example: asas2223

  - `shipments.parcelType` (string)
    > -Packaging type varies as per selected carrier and its services, e.g., PKG, LGENV.
    Example: PKG

  - `shipments.serviceId` (string)
    > -The unique identifier given to the carrier-specific service. ERR supports two services: First Class Mail (FCM) and Priority Mail (PM).
    Example: PM

  - `shipments.dateOfShipment` (string)
    Indicates the date when shipment is created.
    Example: 2023-04-03

  - `shipments.shipmentOptions` (object)

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

  - `shipments.shipmentOptions.printCustomMessage` (string)
    This prints a custom message on the Shipping Label.
    Example: Print Message 1

  - `shipments.shipmentOptions.receiptOption` (string)
    It provides options to print receipt with Shipping Label. This is only applicable for USPS, and takes values: `RECEIPT_ONLY`, `RECEIPT_WITH_INSTRUCTIONS`, or `NO_OPTIONS`.
    Enum: "RECEIPT_ONLY", "RECEIPT_WITH_INSTRUCTIONS", "NO_OPTIONS"

  - `shipments.metadata` (array)
    Additional metadata that needs to be stored for this shipment can be added here. For now, `costAccountName` is supported.

  - `shipments.metadata.name` (string)
    The key of metadata is CostAccount. User needs to enter the name of the CostAccount, e.g. PBPUNE_COSTACC.
    Example: costAccountName

  - `shipments.metadata.value` (string)
    User needs to enter the CostAccount Code, e.g. CAC-00PBPUN.
    Example: CostAccount-00PBPUN

  - `name` (string, required)
    Name of the of ERR Batch which consists of multiple shipments (shipments in bulk) for Coversheet printing., e.g. ERR-Coversheet07.
    Example: ERR-Coversheet07

  - `size` (string, required)
    This indicates the envelope size of the ERR Bulk Shipment, i.e., DocSize. We have indicated the example values in enum.
    Enum: "10", "6 X 9", "6 X 9.5", "9.5 X 12"

  - `type` (string, required)
    This indicates the type of the ERR Batch Shipment, e.g., Coversheet.
    Enum: "COVERSHEET"

  - `format` (string)
    This defines the format type of the shipment which is printed. For example Coversheet prints in PDF form.
    Enum: "PDF"

  - `carrierAccountId` (string, required)
    The unique identifier associated with the user's registered USPS Account which will be required for this batch. User can override this value by defining it at Shipment level.
    Example: qnpB1VkRMmw

  - `parcelType` (string, required)
    Parcel Type is required for creating a shipment while rating a parcel. And it varies as per USPS selected services, e.g. LTR, LGENV. User can override this value by defining it at shipment level.
    Example: LTR

  - `serviceId` (string, required)
    A unique identifier given  to the carrier-specific service which is used for this BulkShipment. User can override this value by defining it at shipment level.
    Example: FCM

## Response 200:

  - `200` (unknown)
    The Bulk Shipment for ERR has been successfully created.

## Response 200 fields (application/json):

  - `batchId` (string)
    This is a system-generated unique identifier assigned to the Batch while it is processed.

  - `name` (string)
    Name of the of ERR Batch which consists of multiple shipments (shipments in bulk).

  - `groupName` (string)
    Indicates the name of the group of batches, which consists of multiple Batch groups.

  - `status` (string)
    This shows all the status related to the Batch Job.
    Enum: "SUBMITTED", "ADDRESS_VALIDATION_PROCESSING", "ADDRESS_VALIDATED", "ADDRESS_VALIDATION_FAILED", "RATE_VALIDATION_PROCESSING", "RATE_VALIDATED", "RATE_VALIDATION_FAILED", "LABEL_GENERATION_PROCESSING", "LABEL_GENERATION_FAILED", "LABEL_GENERATED", "COMPLETED"

  - `addressValidation` (object)
    This indicates the status count of addresses which are at validation stage.

  - `addressValidation.success` (number)
    The number of addresses which have been successfully validated.
    Example: 20

  - `addressValidation.failed` (number)
    The number of addresses failed at validation due to incorrect entry in the address.
    Example: 10

  - `addressValidation.pending` (number)
    The number of addresses which are pending and in-queue to be processed.
    Example: 10

  - `rating` (object)
    This indicates the status count of shipments which are at Rating stage. Rating is a process of assessing the shipping/freight charge associated with the ERR Bulk shipment. Rates are calculated based on selected special/extra services corresponding to the selected Services and ParcelType for USPS.

  - `rating.success` (number)
    The number of shipments that have been successfully processed for Ratings.
    Example: 20

  - `rating.failed` (number)
    The number of shipments which failed processing at Ratings due to some scenarios like unsupported extra services or incompatible extra services combined for a shipment.
    Example: 10

  - `rating.pending` (number)
    The number of shipments which are pending and in-queue to be processed.
    Example: 10

  - `labelGeneration` (object)
    Indicates the status of shipping labels/coversheets which are at final steps before printing.

  - `labelGeneration.success` (number)
    The number of shipment labels which have been successfully generated.
    Example: 20

  - `labelGeneration.failed` (number)
    The number of shipment labels which failed processing and could not be generated due to some errors with shipment.
    Example: 10

  - `labelGeneration.pending` (number)
    The number of shipment labels which are pending and in-queue to be processed.
    Example: 10

  - `labelDetails` (object)

  - `labelDetails.layout` (object)
    This indicates the layout of the label.

  - `labelDetails.layout.size` (string)
    Defines the label size of the Shipment, that is, the Shipping Label is available in different Doc Size.
    Enum: "DOC_8X11", "DOC_4X6"

  - `labelDetails.layout.type` (string)
    This indicates the type of the label.
    Example: SHIPPING_LABEL

## Response 400:

  - `400` (unknown)
    Invalid request.

## 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/Invalid 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: Error while getting rates for carrier with carrierAccount eRMnRx4mzPP.

  - `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:

  - `401` (unknown)
    The request could not be authorized.

## 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:

  - `500` (unknown)
    The request could not be completed due to an internal server error.

## 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.