# FirstMile Label Server REST API

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


Version: 1.0

## Servers

Test server
```
https://labelserver-test.firstmile.com
```

Production server
```
https://labelserver.firstmile.com
```

## Security

### OAuth2

Type: oauth2

## Download OpenAPI description

[FirstMile Label Server REST API](https://developer.fastgroup.co/_spec/xmethod/label/rest/swagger.yaml)

## Label

### Cancel a shipment by tracking number

 - [DELETE /api/v1/label/{trackingNumber}/{techPartnerId}](https://developer.fastgroup.co/xmethod/label/rest/swagger/label/cancellabelbytrackingnumber.md): Attempts to cancel the shipment with the supplied tracking number.

 CancelDomesticLabel / CancelInternationalLabel

 The trackingNumber and techPartnerId parameters replace the SOAP request object's fields.


### Generate a label image for a shipment

 - [POST /api/v1/label](https://developer.fastgroup.co/xmethod/label/rest/swagger/label/generatelabel.md): Attempts to get a label image for a shipment.

 GetLabel (DhlLabelRequest), GetInternationalLabel (InternationalLabelRequest)

 The request body maps to FirstMileRequest, which combines fields from DhlLabelRequest and InternationalLabelRequest.


### Close shipping day (manifest)

 - [POST /api/v1/label/closeday](https://developer.fastgroup.co/xmethod/label/rest/swagger/label/closeshippingday.md): Attempts to perform the close shipping day process for both domestic and international shipments.

 CloseDomesticShippingDay, CloseInternationalShippingDay

 The request body maps to CloseShippingDayRequest.


## Meter

### Get details of the meter with the specified id

 - [GET /api/v1/meter/{id}/{techPartnerId}](https://developer.fastgroup.co/xmethod/label/rest/swagger/meter/getmeterbyid.md): Attempts to get details of the meter with the specified id.

 GetMeterBalance

 The id and techPartnerId parameters replace the SOAP request object's fields.


### Get all available meters

 - [GET /api/v1/meter/{techPartnerId}](https://developer.fastgroup.co/xmethod/label/rest/swagger/meter/getallmeters.md): Gets all available meters for the authenticated account.

 GetMeters

 The techPartnerId parameter is required.


### Add funds to a meter

 - [POST /api/v1/meter/addfunds](https://developer.fastgroup.co/xmethod/label/rest/swagger/meter/addfundstometer.md): Attempts to add funds to a meter.

 AddFundsToMeter

 The request body maps to AddFundsRequest.


## Rate

### Get a rate for a shipment

 - [POST /api/v1/rate](https://developer.fastgroup.co/xmethod/label/rest/swagger/rate/getrate.md): Attempts to get a rate for a specific shipping service.

 GetRate (DomesticRateRequest), GetInternationalRate (InternationalRateRequest)

 The request body maps to FirstMileRequest.


### Rate shop available ship methods

 - [POST /api/v1/rate/shop](https://developer.fastgroup.co/xmethod/label/rest/swagger/rate/rateshop.md): Attempts to rate shop available ship methods across all carriers.

 GetRates (DomesticRatesRequest), GetInternationalRates (InternationalRatesRequest)

 The request body maps to FirstMileRequest.