Skip to content
FirstMile
/
Label API
/
/
SOAP to REST Migration Gu...
Last updated

FirstMile Label API Migration Guide: SOAP to REST

This guide helps users transition from the legacy FirstMile SOAP API to the new REST API.

Overview

  • All SOAP methods are now available as REST endpoints
  • Request and response models are mapped to OpenAPI schemas
  • Key Change: Both domestic and international operations now use unified request models
  • Field names follow camelCase convention for JSON
  • OAuth 2.0 Bearer token authentication replaces SOAP credentials

Endpoint Mapping

SOAP MethodREST EndpointHTTP MethodRequest ModelResponse Model
GetLabel(DhlLabelRequest)/api/v1/labelPOSTFirstMileRequestLabelResponse
GetInternationalLabel(InternationalLabelRequest)/api/v1/labelPOSTFirstMileRequestLabelResponse
CancelDomesticLabel/api/v1/label/{trackingNumber}/{techPartnerId}DELETEPath params200 OK or 404 with errors
CancelInternationalLabel/api/v1/label/{trackingNumber}/{techPartnerId}DELETEPath params200 OK or 404 with errors
CloseDomesticShippingDay/api/v1/label/CloseDayPOSTCloseShippingDayRequestCloseShippingDayResponse
CloseInternationalShippingDay/api/v1/label/CloseDayPOSTCloseShippingDayRequestCloseShippingDayResponse
GetRate(DomesticRateRequest)/api/v1/ratePOSTFirstMileRequestRateResponse
GetInternationalRate(InternationalRateRequest)/api/v1/ratePOSTFirstMileRequestRateResponse
GetRates(DomesticRatesRequest)/api/v1/rate/ShopPOSTFirstMileRequestRatesResponse
GetInternationalRates(InternationalRatesRequest)/api/v1/rate/ShopPOSTFirstMileRequestRatesResponse
GetMeters/api/v1/meter/{techPartnerId}GETPath paramMetersResponse
GetMeterBalance/api/v1/meter/{id}/{techPartnerId}GETPath paramsMetersResponse
AddFundsToMeter/api/v1/meter/AddFundsPOSTAddFundsRequestAddFundsResponse

Field Mapping

Core Request Fields

SOAP FieldREST FieldNotes
FromAddressfromAddressAddress object
ShipToAddresstoAddressAddress object
LabelTypeshippingServiceEnumPreferred: Use enum version
LabelTypeshippingServiceLegacy: String version (deprecated)
PackageDetailpackagesArray of Package objects
WeightOzshipmentWeightOzTotal shipment weight in ounces
CustomsDatacustomsDataFor international shipments
LabelImageFormatlabelImageFormatEnumPreferred: Enum version
LabelSizelabelImageSizeEnumThermal label stock size
AncillaryEndorsementancillaryEndorsementEnumUSPS endorsement
SecondaryAncillaryEndorsementsecondaryEndorsementEnumSecondary USPS endorsement
IncotermsinternationalDutyTermsEnumCustoms duties terms
FutureShipmentDatefutureShipmentDateISO 8601 datetime
RequestIdrequestIdEchoed in response

Enum Value Changes

ShippingService (LabelType)

Most enum values are preserved but follow consistent naming:

  • SOAP: DhlSmParcelsGround
  • REST: DhlSm_Parcels_Ground
  • SOAP: USPSPriorityMailPackage
  • REST: USPS_Priority_Mail_Package

Example Migration

REST Label Request

POST /api/v1/label
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

{
  "techPartnerId": "PARTNER123",
  "fromAddress": {
    "name": "John Doe",
    "address1": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "postalCode": "12345"
  },
  "toAddress": {
    "name": "Jane Smith", 
    "address1": "456 Oak Ave",
    "city": "Other City",
    "state": "NY",
    "postalCode": "67890"
  },
  "shippingServiceEnum": "FirstMile_Ground",
  "shipmentWeightOz": 16,
  "labelImageFormatEnum": "Png",
  "packages": [
    {
      "weight": {
        "weightOz": 16,
        "weightType": "Actual"
      }
    }
  ]
}

Support Resources

  • OpenAPI/Swagger documentation: /swagger/index.html
  • Test environment: https://labelserver-test.firstmile.com
  • Production environment: https://labelserver.firstmile.com
Previous page
Next page