Looking for the legacy API documentation? Click here

Ratings API Specification

Overview

The Rating API enables customers to programmatically create and fetch rated quotes within Maersk’s system.

To use this API, you must have a CoPilot account. For more details, please contact your Maersk sales representative.

API Reference

The interactive reference below is filtered to the Ratings and Locations tags so you can focus on the endpoints described on this page.

Name Method Path Description
CreateRating POST /ratings Creates a rating
GetRating GET /ratings/{quoteId} Fetches a previously created rating
GetLocationTariffServiceCodes GET /locations/{locationId}/tariffs/{tariffCode}/service-codes Retrieves a list of all valid service codes associated with a specified locationId and tariffCode

Key Request Fields

When creating a rating, the following fields are especially important and are linked to your CoPilot account. To obtain the correct values, navigate to Settings > Developer Console in your CoPilot account.

  • locationId (Required): Unique identifier associated with your CoPilot account.
  • tariffCode (Required): Can be found under your CoPilot account. If there are multiple, reach out to your Maersk sales representative for clarification on which one to use.

You must have a tariff code assigned to your CoPilot account in order to use this API.

All required request fields are indicated in the API Reference. However, some fields have special behavior, as detailed below.

  • serviceCode (Required): Should be a valid service code. This must also be a valid service under your tariff. See GetLocationTariffServiceCodes.
  • save (Optional): Indicates if a rating should be saved for later retrieval. If true (default), the quoteId response field will be populated. See GetRating.

Accessorials

Accessorials represent optional services that affect the final rating.

The Ratings API supports two distinct accessorial scopes when creating a rating. Accessorials are only applied if they are defined and enabled in the tariff (tariffCode) used for the request.

Shipment-Level Accessorials

Shipment-level accessorials apply to the entire shipment and are not associated with a specific location (origin or destination). They are added to the top-level accessorials array in the request.

Example:

{
    "accessorials": ["Packing", "Oversized"]
}

Location-Level Accessorials (Directional)

Location-level accessorials apply specifically to either the origin (pickup) or destination (delivery) location. They are defined inside the origin and/or destination objects. Each accessorial is represented as an object with an optional quantity field.

Quantity behavior

  • The quantity field is optional for most accessorials.
  • When omitted, quantity defaults to 1
  • For the following accesssorials, quantity is required and represents hours:
    • TwoMan
    • WaitTime

Example:

{
  "origin": {
    "countryCode": "US",
    "regionCode": "PA",
    "postalCode": "19342",
    "accessorials": [
      {
        "accessorial": "Liftgate"
      },
      {
        "accessorial": "WaitTime",
        "quantity": 2.5
      }
    ]
  },
  "destination": {
    "countryCode": "US",
    "regionCode": "CA",
    "postalCode": "90210",
    "accessorials": [
      {
        "accessorial": "PrivateResidence"
      },
      {
        "accessorial": "Inside"
      }
    ]
  },
  "accessorials": ["Oversized"],
  ...
}

Environments & Authentication

Environments

The API is available in the below environments. Ensure you are using the appropriate environment for testing and live operations.

Environment Base URL
Production https://api.maersk.com/mgf/public-gateway
Testing https://api-stage.maersk.com/mgf/public-gateway

Authentication

This API utilizes OAuth 2.0 authentication with the client_credentials grant type. To obtain access credentials, please contact your Maersk sales representative.

Authentication Steps

  1. Get an access token: Send a POST request to the token endpoint (see Token Endpoints) with your client credentials. If successful, you’ll receive an access_token in the response.
  2. Use the access token: Include the access_token value in the Authorization header:
Authorization: Bearer YOUR_ACCESS_TOKEN

Important: You must also include your client_id in the Consumer-Key header for both the token request and all subsequent requests that use the access_token:

Consumer-Key: YOUR_CLIENT_ID

Example access token request:

POST /customer-identity/oauth/v2/access_token HTTP/1.1
Host: api.maersk.com
Content-Type: application/x-www-form-urlencoded
Consumer-Key: YOUR_CLIENT_ID

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials

Example access token response:

{
  "access_token": "eyJ0...",
  "scope": "openid",
  "id_token": "eyJ0...",
  "token_type": "Bearer",
  "expires_in": 7199
}

Token Endpoints

Use the corresponding token endpoint for the environment that matches your request.

Environment Token Endpoint
Production https://api.maersk.com/customer-identity/oauth/v2/access_token
Testing https://api-stage.maersk.com/customer-identity/oauth/v2/access_token

Versioning

API versioning is implemented using the Api-Version header to ensure backward compatibility while allowing for improvements and new features to be introduced without disrupting existing integrations. If the Api-Version header is omitted, the request will default to the latest stable version.

Example:

Api-Version: 1

Error Handling

The API returns a standardized response object for structured errors across all endpoints. Errors are provided in a JSON format with detailed information to aid in debugging.

Example Error Response 

{
  "httpMethod": "POST",
  "requestUri": "https://api.maersk.com/mgf/public-gateway/ratings",
  "statusCode": 400,
  "statusText": "Bad Request",
  "errorMessage": "Validation Error(s)",
  "correlationIdentifier": "00-004a8d8690078d85bc8f92b156072a25-9782db54b2045007-01",
  "errorTimestamp": "2025-03-05T02:51:56.7724601Z",
  "detailedErrors": [
    {
      "path": "$.shipDate",
      "field": "shipDate",
      "value": "3/2/2025",
      "message": "'shipDate' cannot be in the past."
    }
  ]
}

Common Error Codes

Status Code Meaning Possible Causes
400 Bad Request Invalid input data, missing required fields
401 Unauthorized Missing or invalid authentication token
403 Forbidden Insufficient permissions
404 Not Found Resource does not exist
500 Internal Server Error Unexpected API error