Mizzen API (V1)

Download OpenAPI specification:Download

The Mizzen API offers programmatic access to the marketplace features of mizzenit.com. These APIs are intended for use with digital rate management platforms, transport management systems or platforms that have a requirement for spot pricing direct from shipping lines.

This API is REST-oriented, supporting JSON or XML. Before first use, please contact Mizzen to obtain an API access key. More details can be found in the Authentication section below.

How to use this API

The API is centered around the notion of a getting a customers pre-filed or new spot rates from shipping lines. Rates that are managed and accessed by Mizzen can be filed buy rate, a marked-up sell rate or requesting a new spot rate direct from any shipping line.

The Buy / Sell Rates API allows access to pre-procured rates that are customer specific i.e. a negotiated FAK or named account rate. These rates can be either a shipping lines buy rate and/or it can be a customers' marked up sell rate. A sell rate is what would be shown to the customers' customer, i.e. a shipper. It can also be used by an ERP to calculate the margin between the buy and sell rates. When you submit a New Rate you will only have your own rates that you have filed into Mizzen returned.

The Rate Request API is centered around the notion of requesting a New Spot Rate. After you submit a request, shipping lines will submit responses, either immediately for live prices, or after a period of time for inside sales teams responses.

Before using any of these APIs the customer must be registered. This is a one-time process for each new customer. Upon initial registration, the customer will be verified externally via Mizzen, and once approved, the customer will be able to submit rate requests and access their pre-filed rates.

Authentication

Authentication is via basic authentication using an API key provided via Mizzen. For access, please Contact Mizzen.

Please provide your API key as your username, and leave the password blank.

An example authenticated API call via curl using the API key apikey123 is below:

$ curl -u "apikey123:" http://api-demo.mizzenit.com/api/requestapi/customer/123

Changelog

Date Details
2019-04-08 Initial draft release
2019-04-17 Update rate response to offer voyage-specific products
2019-08-19 Rename existing spot rate methods, add buy / sell rates
2019-09-17 Added Voyage Rates
2020-05-12 Added CommonName property to ShippingLineResponse

Customer

On the Mizzen platform, rates can be pre-filed or spot requests are submitted on behalf of a customer. Customers are purchasers of FCL freight, typically freight forwarders.

Customers must be registered with Mizzen, after which they will be assigned a customer ID. This customer ID will be supplied as a parameter for all subsequent API calls on behalf of this customer, so you will need to save it for later use.

Please note that registering a customer and receiving a customer ID does not immediately allow submitting API requests. All customers registered with Mizzen must be manually verified. The status of a customer can be checked via Get Customer Details, and once they have been approved, they may submit API requests.

This registration may be submitted any time before the customer's initial spot of filed request - you may wish to register customers ahead of time so there is no delay before they submit their first rate request.

Register a customer

Required so that rate requests can be submitted on behalf of this customer. Once submitted, this registration will be manually reviewed by the Mizzen team. The status of the review can be obtained via the Customer URI

Authorizations:
Request Body schema: application/json

Customer to register

FirstName
string

Customer's first name

LastName
string

Customer's last name

CompanyName
string

Name of the freight buying company

Email
string

Customer's email address

Phone
string

Customer's phone number

Responses

200
Response Schema: application/json
CustomerId
integer <int32>

Customer ID generated during customer registration

CustomerPath
string

Path to customer's URL

post /api/v1/registercustomer
https://mizzenit.com/api/v1/registercustomer

Request samples

application/json
Copy
Expand all Collapse all
{
  • "FirstName": "John",
  • "LastName": "Smith",
  • "CompanyName": "Smith Freight Inc",
  • "Email": "jsmith@smithfreight.com",
  • "Phone": "+61 123 234 345"
}

Response samples

application/json
Copy
Expand all Collapse all
{}

Get customer details

Customers cannot submit rate requests until their status is Approved

Authorizations:
path Parameters
id
required
string

CustomerId supplied via customer registration

Responses

200
Response Schema: application/json
CustomerId
integer <int32>

Customer ID generated during customer registration

FirstName
string

Customer's first name

LastName
string

Customer's last name

CompanyName
string

Name of the freight buying company

Email
string

Customer's email address

Phone
string

Customer's phone number

Status
string

Pending, Approved, or Rejected. If Approved, this customer is permitted to submit rate requests

get /api/v1/customer/{id}
https://mizzenit.com/api/v1/customer/{id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "CustomerId": 1,
  • "FirstName": "John",
  • "LastName": "Smith",
  • "CompanyName": "Smith Freight Inc",
  • "Email": "jsmith@smithfreight.com",
  • "Phone": "+61 123 234 345",
  • "Status": "Pending"
}

Spot Rate

The rate request is the central concept in the Mizzen marketplace. In order to obtain a price via Mizzen, a customer submits a rate request matching their particular buying scenario, ie POL / POD, departure date, etc. From there, shipping lines will submit responses with prices and validity specific to this request. Alternatively, they may choose to decline to quote.

Rate response information is associated against the request entity. Responses may be instantly returned in the case of live prices, or returned at a later point in time in the case of manual quotes. Some responses may utilise products that are not easily expressed in simple price / validity terms. For these responses there will be a SeeMizzen status, which means the customer will need to access mizzenit.com to see these prices.

New Spot Rate

Request Body schema: application/json

Spot Rate to send

CustomerId
integer <int32>
PoLCode
string
PoDCode
string
DepartBy
string <date-time>
TargetSCACs
Array of string
CommodityAndWeight
Array of object (Mizzen.API.V1.CommodityAndWeight)

Responses

200

Response data

Response Schema: application/json
RatePath
string

Path from which to access the rate request details

Rates
Array of object (Mizzen.API.V1.ShippingLineResponse)

Responses to spot rate. One collection of responses per shipping line. Shipping lines may respond over time but once a response has been submitted by a shipping line, it does not change

post /api/v1/newspotrate
https://mizzenit.com/api/v1/newspotrate

Request samples

application/json
Copy
Expand all Collapse all
{
  • "CustomerId": 1,
  • "PoLCode": "AUSYD",
  • "PoDCode": "CNSHA",
  • "DepartBy": "2020-06-06",
  • "CommodityAndWeight":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "RatePath": "/api/v1/SpotRate/dU1iTk4yQlVRTW04QWhlOGxoOS90SGFPMFZqOGVsRWk1Q3dGVlhKaVhnVmpVZkRvWnFvNVF1VDVuRWsxSzNrU1ZiaDlrSDRGRHJ1bUJLQU4zOTNSOVE9PQ2",
  • "Rates":
    [
    ]
}

Get Spot Rate

The rate request includes rate responses. Reload this periodically to see if new responses have arrived.

For a given rate request, each shipping line will either decline or respond with an offer. A shipping line will decline/respond once per request. Mizzen offers shipping lines the ability to offer a range of different products. Within this product suite, various properties of these products are common to all (in particular the pricing structure), with the specific product on offer defined by the presence of a Standard, SEG, or LimitedOffer property. The specifics of these products are detailed below.

Standard

This is an industry-standard fixed price bound by effective and validity date. A standard product can be itentified by the presence of the Standard property in the repsonse payload

Space & equipment guarantee (SEG)

This is a premium product for which the avaiability of space and equipment is guaranteed. It is valid for a limited time and only for specific voyages. A SEG product can be identified by the presence of the SEG property in the response payload

Limited Offer

This product is restricted to a specific set of voyages and may also be limited by a period of time, eg: next 7 days only. A limited offer product can be identified by the presence of the LimitedOffer property in the response payload

path Parameters
id
required
string

ID of rate request. Returned during submit

Responses

200

The Spot Rate

Response Schema: application/json
RatePath
string

Path from which to access the rate request details

Rates
Array of object (Mizzen.API.V1.ShippingLineResponse)

Responses to spot rate. One collection of responses per shipping line. Shipping lines may respond over time but once a response has been submitted by a shipping line, it does not change

get /api/v1/spotrate/{id}
https://mizzenit.com/api/v1/spotrate/{id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "RatePath": "/api/v1/SpotRate/dU1iTk4yQlVRTW04QWhlOGxoOS90SGFPMFZqOGVsRWk1Q3dGVlhKaVhnVmpVZkRvWnFvNVF1VDVuRWsxSzNrU1ZiaDlrSDRGRHJ1bUJLQU4zOTNSOVE9PQ2",
  • "Rates":
    [
    ]
}

Buy / Sell Rates

A customer can use Mizzen to manage their shipping line FAK and named account rates, and then make these rates accessible to other systems via the new rate API. Further, the customer's buy rates can be transformed into their own customer sell rates through the application of pricing rules, and accessible by the new rate API.

The uploading and management of rules and rates is performed via the Mizzen website. The rates are then available via the APIs detailed below.

Request Buy / Sell Rates

Request Body schema: application/json

Rate request to send

CustomerId
integer <int32>
PoLCode