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

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": "2019-10-01",
  • "CommodityAndWeight":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "Rates":
    [