Skip to content
FirstMile
/
/
/
Get a rate for a shipment

FirstMile Label Server REST API (1.0)

The FirstMile Label Server REST API provides endpoints for label creation, rate shopping, meter management, and manifesting shipments. This API replaces the legacy SOAP interface. All endpoints, request/response models, and business logic are documented here, with migration notes for users transitioning from SOAP.

Authentication

The API uses OAuth 2.0 Bearer token authentication with policy-based authorization:

  • Label operations require 'fm.external.rest.labelserver.label' scope
  • Rate operations require 'fm.external.rest.labelserver.rate' scope
  • Meter operations require 'fm.external.rest.labelserver.meter' scope

The API validates claims including 'fm.api.companyId' (IFS ID) and 'fm.api.techPartnerId'.

Migration Notes

  • All SOAP methods are now available as REST endpoints
  • Request and response models are mapped to OpenAPI schemas
  • See the migration guide for detailed mapping and examples
Download OpenAPI description
swagger.json
swagger.yaml
Languages
Servers
Mock server

https://developer.fastgroup.co/_mock/xmethod/label/rest/swagger/

Test server

https://labelserver-test.firstmile.com/

Production server

https://labelserver.firstmile.com/

Label

Operations

Meter

Operations

Rate

Operations

Get a rate for a shipment

Request

Attempts to get a rate for a specific shipping service.

SOAP Equivalent: GetRate (DomesticRateRequest), GetInternationalRate (InternationalRateRequest)

Migration Note: The request body maps to FirstMileRequest.

Security
OAuth2
Bodyapplication/jsonrequired

Rate request

techPartnerIdstringrequired

Tech partner identifier (required)

fromAddressobject(Address)

Address information for sender or recipient. (SOAP: Address)

toAddressobject(Address)

Address information for sender or recipient. (SOAP: Address)

shippingServiceEnumstring(ShippingService)

Available shipping services

Enum"Unknown""AMZN_Ground_Parcel_Delivery""Asendia_International_Fully_Tracked""Asendia_International_Country_Tracked""Asendia_International_PMI""Asendia_International_PMEI""Asendia_International_EPAQ_Select""Asendia_International_EPAQ_Elite""Asendia_International_EPAQ_Standard""Asendia_International_EPAQ_Elite_DPD"
shippingServicestring or null

Deprecated: Use shippingServiceEnum instead

packagesArray of objects(Package)

Package(s) information. Multi-package shipments are only supported for FedEx, UPS, and DHL Express shipments. (SOAP: PackageDetail)

requestIdstring or null

Id for the request. This will be echoed in the response. (SOAP: RequestId)

customsDataobject(CustomsData)

Customs information for international shipments. (SOAP: CustomsData)

internationalDutyTermsEnumstring(InternationalDutiesTerms)

International customs duties terms

Enum"Unknown""DDU""DDP"
internationalDutyTermsstring or null

Deprecated: Use internationalDutyTermsEnum instead

ancillaryEndorsementEnumstring(Endorsement)

USPS ancillary service endorsement

Enum"None""Address_Service_Requested""Change_Service_Requested""Forwarding_Service_Requested""Return_Service_Requested"
ancillaryEndorsementstring or null

Deprecated: Use ancillaryEndorsementEnum instead

secondaryEndorsementEnumstring(Endorsement)

USPS ancillary service endorsement

Enum"None""Address_Service_Requested""Change_Service_Requested""Forwarding_Service_Requested""Return_Service_Requested"
secondaryEndorsementstring or null

Deprecated: Use secondaryEndorsementEnum instead

docTabValuesArray of strings or null

These values are added to the label image when possible. (SOAP: DocTabValues)

futureShipmentDatestring or null(date-time)

Scheduled shipment date (if not immediate). (SOAP: FutureShipmentDate)

labelImageFormatEnumstring(ImageFormat)

Label image format

Enum"Unknown""Png""Jpeg""Gif""Pdf""ZPL""EPL"
labelImageFormatstring or null

Deprecated: Use labelImageFormatEnum instead

labelImageSizeEnumstring(LabelStockSize)

Thermal label stock size

Enum"Label4X6""Label4X8"
shipmentWeightOznumber(decimal)

Total weight of the shipment in ounces. (SOAP: WeightOz)

reference1string or null

Optional billing reference 1. (SOAP: Reference1)

reference2string or null

Optional billing reference 2. (SOAP: Reference2)

orderNumberstring or null

Optional user defined barcode on the label. (SOAP: OrderNumber)

curl -i -X POST \
  https://developer.fastgroup.co/_mock/xmethod/label/rest/swagger/api/v1/rate \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "techPartnerId": "string",
    "fromAddress": {
      "companyName": "string",
      "name": "string",
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "email": "string",
      "phoneNumber": "string",
      "residential": false
    },
    "toAddress": {
      "companyName": "string",
      "name": "string",
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "email": "string",
      "phoneNumber": "string",
      "residential": false
    },
    "shippingServiceEnum": "Unknown",
    "shippingService": "string",
    "packages": [
      {
        "weight": {
          "weightOz": 0,
          "weightType": "Actual"
        },
        "packageDimensions": {
          "lengthInch": 0,
          "widthInch": 0,
          "heightInch": 0
        },
        "specialServices": {
          "dangerousGoodsOptions": {
            "dangerousGoodsType": "None",
            "emergencyContactNumber": "string"
          },
          "signatureType": "None"
        },
        "packageDescription": "string",
        "packageValue": 0
      }
    ],
    "requestId": "string",
    "customsData": {
      "shipmentValue": 0,
      "shipmentDescription": "string",
      "customsItems": [
        {
          "countryOfOrigin": "string",
          "description": "string",
          "itemValue": 0,
          "itemQuantity": 0,
          "itemSKU": "string",
          "hsCode": "string",
          "itemWeight": {
            "weightOz": 0,
            "weightType": "Actual"
          },
          "itemDescriptionInExportCountryLanguage": "string"
        }
      ]
    },
    "internationalDutyTermsEnum": "Unknown",
    "internationalDutyTerms": "string",
    "ancillaryEndorsementEnum": "None",
    "ancillaryEndorsement": "string",
    "secondaryEndorsementEnum": "None",
    "secondaryEndorsement": "string",
    "docTabValues": [
      "string"
    ],
    "futureShipmentDate": "2019-08-24T14:15:22Z",
    "labelImageFormatEnum": "Unknown",
    "labelImageFormat": "string",
    "labelImageSizeEnum": "Label4X6",
    "shipmentWeightOz": 0,
    "reference1": "string",
    "reference2": "string",
    "orderNumber": "string"
  }'

Responses

OK - Rate calculated successfully

Bodyapplication/json
requestIdstring or null

The Id passed in the request, echoed back

errorsArray of strings or null

A list of errors, if any

warningsArray of strings or null

Warning information. These are for information purposes only, they are not errors.

estimatedZonestring or null

The estimated zone of the shipment.

weightobject(Weight)

Weight information for a package. (SOAP: BilledWeight)

packageRatesArray of objects or null(PackageRate)

Package-specific rate information

shippingServicestring(ShippingService)

Available shipping services

Enum"Unknown""AMZN_Ground_Parcel_Delivery""Asendia_International_Fully_Tracked""Asendia_International_Country_Tracked""Asendia_International_PMI""Asendia_International_PMEI""Asendia_International_EPAQ_Select""Asendia_International_EPAQ_Elite""Asendia_International_EPAQ_Standard""Asendia_International_EPAQ_Elite_DPD"
daysInTransitinteger or null

Estimated days in transit

Response
application/json
{
  "requestId": "string",
  "errors": [
    "string"
  ],
  "warnings": [
    "string"
  ],
  "estimatedZone": "string",
  "weight": {
    "weightOz": 0,
    "weightType": "Actual"
  },
  "packageRates": [
    { … }
  ],
  "shippingService": "Unknown",
  "daysInTransit": 0
}

Rate shop available ship methods

Request

Attempts to rate shop available ship methods across all carriers.

SOAP Equivalent: GetRates (DomesticRatesRequest), GetInternationalRates (InternationalRatesRequest)

Migration Note: The request body maps to FirstMileRequest.

Security
OAuth2
Bodyapplication/jsonrequired

Rate shop request

techPartnerIdstringrequired

Tech partner identifier (required)

fromAddressobject(Address)

Address information for sender or recipient. (SOAP: Address)

toAddressobject(Address)

Address information for sender or recipient. (SOAP: Address)

shippingServiceEnumstring(ShippingService)

Available shipping services

Enum"Unknown""AMZN_Ground_Parcel_Delivery""Asendia_International_Fully_Tracked""Asendia_International_Country_Tracked""Asendia_International_PMI""Asendia_International_PMEI""Asendia_International_EPAQ_Select""Asendia_International_EPAQ_Elite""Asendia_International_EPAQ_Standard""Asendia_International_EPAQ_Elite_DPD"
shippingServicestring or null

Deprecated: Use shippingServiceEnum instead

packagesArray of objects(Package)

Package(s) information. Multi-package shipments are only supported for FedEx, UPS, and DHL Express shipments. (SOAP: PackageDetail)

requestIdstring or null

Id for the request. This will be echoed in the response. (SOAP: RequestId)

customsDataobject(CustomsData)

Customs information for international shipments. (SOAP: CustomsData)

internationalDutyTermsEnumstring(InternationalDutiesTerms)

International customs duties terms

Enum"Unknown""DDU""DDP"
internationalDutyTermsstring or null

Deprecated: Use internationalDutyTermsEnum instead

ancillaryEndorsementEnumstring(Endorsement)

USPS ancillary service endorsement

Enum"None""Address_Service_Requested""Change_Service_Requested""Forwarding_Service_Requested""Return_Service_Requested"
ancillaryEndorsementstring or null

Deprecated: Use ancillaryEndorsementEnum instead

secondaryEndorsementEnumstring(Endorsement)

USPS ancillary service endorsement

Enum"None""Address_Service_Requested""Change_Service_Requested""Forwarding_Service_Requested""Return_Service_Requested"
secondaryEndorsementstring or null

Deprecated: Use secondaryEndorsementEnum instead

docTabValuesArray of strings or null

These values are added to the label image when possible. (SOAP: DocTabValues)

futureShipmentDatestring or null(date-time)

Scheduled shipment date (if not immediate). (SOAP: FutureShipmentDate)

labelImageFormatEnumstring(ImageFormat)

Label image format

Enum"Unknown""Png""Jpeg""Gif""Pdf""ZPL""EPL"
labelImageFormatstring or null

Deprecated: Use labelImageFormatEnum instead

labelImageSizeEnumstring(LabelStockSize)

Thermal label stock size

Enum"Label4X6""Label4X8"
shipmentWeightOznumber(decimal)

Total weight of the shipment in ounces. (SOAP: WeightOz)

reference1string or null

Optional billing reference 1. (SOAP: Reference1)

reference2string or null

Optional billing reference 2. (SOAP: Reference2)

orderNumberstring or null

Optional user defined barcode on the label. (SOAP: OrderNumber)

curl -i -X POST \
  https://developer.fastgroup.co/_mock/xmethod/label/rest/swagger/api/v1/rate/shop \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "techPartnerId": "string",
    "fromAddress": {
      "companyName": "string",
      "name": "string",
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "email": "string",
      "phoneNumber": "string",
      "residential": false
    },
    "toAddress": {
      "companyName": "string",
      "name": "string",
      "address1": "string",
      "address2": "string",
      "address3": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "email": "string",
      "phoneNumber": "string",
      "residential": false
    },
    "shippingServiceEnum": "Unknown",
    "shippingService": "string",
    "packages": [
      {
        "weight": {
          "weightOz": 0,
          "weightType": "Actual"
        },
        "packageDimensions": {
          "lengthInch": 0,
          "widthInch": 0,
          "heightInch": 0
        },
        "specialServices": {
          "dangerousGoodsOptions": {
            "dangerousGoodsType": "None",
            "emergencyContactNumber": "string"
          },
          "signatureType": "None"
        },
        "packageDescription": "string",
        "packageValue": 0
      }
    ],
    "requestId": "string",
    "customsData": {
      "shipmentValue": 0,
      "shipmentDescription": "string",
      "customsItems": [
        {
          "countryOfOrigin": "string",
          "description": "string",
          "itemValue": 0,
          "itemQuantity": 0,
          "itemSKU": "string",
          "hsCode": "string",
          "itemWeight": {
            "weightOz": 0,
            "weightType": "Actual"
          },
          "itemDescriptionInExportCountryLanguage": "string"
        }
      ]
    },
    "internationalDutyTermsEnum": "Unknown",
    "internationalDutyTerms": "string",
    "ancillaryEndorsementEnum": "None",
    "ancillaryEndorsement": "string",
    "secondaryEndorsementEnum": "None",
    "secondaryEndorsement": "string",
    "docTabValues": [
      "string"
    ],
    "futureShipmentDate": "2019-08-24T14:15:22Z",
    "labelImageFormatEnum": "Unknown",
    "labelImageFormat": "string",
    "labelImageSizeEnum": "Label4X6",
    "shipmentWeightOz": 0,
    "reference1": "string",
    "reference2": "string",
    "orderNumber": "string"
  }'

Responses

OK - Rates retrieved successfully

Bodyapplication/json
requestIdstring or null

The Id passed in the request, echoed back

errorsArray of strings or null

A list of errors, if any

warningsArray of strings or null

Warning information. These are for information purposes only, they are not errors.

ratesArray of objects(RateResponse)

Available shipping rates

Default []
Response
application/json
{
  "requestId": "string",
  "errors": [
    "string"
  ],
  "warnings": [
    "string"
  ],
  "rates": []
}