API docs by Redocly

National API - Declarant API (1.0.21)

Download OpenAPI specification:

License: Apache 2.0 Terms of Service

The European Maritime Single Window (EMSW) environment is a framework aimed at simplifying and harmonizing the administrative procedures required for ships arriving at and/or departing from ports within the European Union. It's designed to facilitate the electronic transmission of information related to maritime transport to the relevant authorities. This initiative is part of a broader effort to reduce the administrative burden on maritime transport and improve the efficiency of maritime traffic and port operations.

In the context of a "National Declarant API" that is intended for organizations not using the Reporting Interface Module (RIM), these formalities would be submitted through an alternative digital interface. The National API would provide a means for these organizations to fulfill their reporting obligations electronically, without directly using the RIM.

To use National Declarant API, organization has to be created as declarant organization and registered as national api user in local EMSW environment. This can be done by using local EMSW (NEMO) by organization admin.

The National Declarant API now uses MIG 1.0.0.0 and 2.0.0.0 versions.

You can find the information needed to make a valid request at the address https://fintraffic-vts.github.io/mnsw/ :
- National rules and EMSA rules, conditions and guidelines
- List of data elements suggested by Finnish authorities to use, whn submitting formalities
- MIG JSON schema definitions
- Nemo codelists
- Guides

Each request must have a valid JWT token in the Authorization header.
How to get JWT token for declarant organization

curl -X POST 'https://<IDP>/realms/nemo/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=<client_id>' \
  -d 'client_secret=<secret>' \
  -d 'grant_type=client_credentials'

IDP - DEV: mnsw-dev.mnsw.fi/keycloak
IDP - TST: mnsw-tst.mnsw.fi/keycloak
IDP - STG: mnsw-stg.mnsw.fi/keycloak
IDP - PRD: mnsw.mnsw.fi/keycloak

Example request with CURL:

curl --request GET 'https://mnsw-dev.mnsw.fi/declarant-api/v1/portcalls?shipNames=KALLIO' \
--header 'Authorization: Bearer <access_token>'

Portcalls

In the context of the European Maritime Single Window and the maritime industry in general, a "port call" refers to the event of a ship arriving at, staying in, and departing from a specific port. This is a critical part of maritime operations, involving various activities and procedures.For programmers implementing a national API in their system, understanding the concept of a port call is essential as it forms the basis of many maritime data transactions and reporting requirements.

Creating a port call using API will internally create VID formality, return the visit id and create a port call in the system.

Retrieve information about port calls.

Retrieve information about callers created port calls. Port calls are returned in the order they were created by callers organization. Query parameters can be used to filter port calls. If the search parameter or its value is invalid, all port calls are returned.

query Parameters
timeWindowStart
string <date>
Example: timeWindowStart=2025-08-16

Time window start date (eta) in YYYY-MM-DD format.

timeWindowEnd
string <date>
Example: timeWindowEnd=2025-10-31

Time window end date (eta) in YYYY-MM-DD format.

shipNames
Array of strings
Example: shipNames=Customs test cargo ship 3

List of ship names

mmsiNumbers
Array of strings

List of the Maritime Mobile Service Identity number of the ships.

shipIMONumbers
Array of strings

List of the International Maritime Organization number of the ships.

callSigns
Array of strings

List of the call sign of the ships.

portIds
Array of strings

List of the UN/LOCODE (United Nations Code for Trade and Transport Locations) of the ports.

portCallStatuses
Array of strings

List of port call statuses to filter by. Possible values are 'Unconfirmed', 'Arriving', 'Moored', 'Departed', 'Cancelled'.

arrivingIn
string
Enum: "DOMESTIC" "FOREIGN"

Arriving in, domestic or foreign DOMESTIC or FOREIGN traffic

departingIn
string
Enum: "DOMESTIC" "FOREIGN"

Departing in, DOMESTIC or FOREIGN traffic

hasFormality
Array of strings
Example: hasFormality=VID

List of formalities

object (PortCallsFilterParamsDTO)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Create a new port call

Create a new port call. The port call is created for the organization of the caller.

Request Body schema: application/json
required

port call data

shipName
required
string
iceClassCode
required
string
registeredOwnerName
required
string
portLocationCode
required
string
eta
required
string <date-time>
portAreaCode
string
shipImoNumber
string
mmsiNumber
string
shipCallSign
string
cfrNumber
string
eniNumber
string
otherShipIdentificationNumber
string
etd
string <date-time>

Responses

Request samples

Content type
application/json
Example

success_request

{
  • "shipName": "Customs test cargo ship 3",
  • "iceClassCode": "FS1A",
  • "registeredOwnerName": "Nemo customs test",
  • "portLocationCode": "FITOR",
  • "portAreaCode": "FITOR-0001",
  • "eta": "2025-09-28T19:50:00.000Z",
  • "shipImoNumber": "0000103",
  • "mmsiNumber": "0000103",
  • "shipCallSign": "A8PQ7",
  • "etd": "2025-09-28T20:55:00.000Z"
}

Response samples

Content type
application/json

success_response

{
  • "env:Envelope": {
    }
}

Formalities

Formalities to portcalls require a "MAI" header in each request. The MAI header is a JSON object that contains information of portcall such as visit id etc.

The term "formalities" in this context refers to various reporting obligations that ships need to fulfill. These can include a range of information such as:

  • Cargo Information: Details about the cargo carried by the ship, including hazardous materials, if any.
  • Crew and Passenger Lists: Information about the people on board the ship, including crew members and passengers.
  • Ship Details: Information about the ship itself, such as its name, flag state, and tonnage.
  • Waste Notifications: Declarations regarding the waste on board, including any hazardous waste.
  • Security Information: Details related to the security of the ship, in compliance with international and EU regulations.
  • Health Declarations: Particularly relevant in situations like the COVID-19 pandemic, where health declarations may be necessary.

    • Specifications:

    MIG-P13 – Number of possible formalities of the same type per port call

    There can be only one formality per port call (i.e. per Visit ID) for the following formality types: ATA, ATD, BKA, BKD, BWA, COA, CWA, CWD, EFF, EXP, HZA, HZD, MDD, MDH, MTS, NAC, NAV, NOA, NOD, PBK, POA, POD, PXA, PXD, SEC, SHP, SID, SSA, STA, STD, VID, WAS.

    The following formality types can be reported in several formalities per port call (i.e. per Visit ID) and by different declarants: ACT, ABS, BLU, CAR, CGA, CGD, CGM, CRT, DUE, EXT, EXS, HOS, HZS, NOS, PPA, PNO, REN, SDA, SDD, STW, SRV, TRA, TRD, TSD, VIS, WAR.

    MIG-P24 – Allowed updates of formalities

    Formalities of the following types can be updated: ABS, ACT, ATA, ATD, BLU, BKA, BKD, BWA, CGA, CGD, CGM, CRT, CWA, CWD, DUE, EFF, EXP, EXS, HOS, HZA, HZD, HZS, MDD, MDH, MTS, NAV, NOA, NOD, NOS, PBK, POA, POD, PPA, PXA, PXD, REN, SEC, SID, SHP, SRV, SSA, STA, STD, STW, TRA, TRD, TSD, VIS, WAS, WAR.

    Formalities of other types cannot be updated: CAR, COA, EXT, PNO, NAC, SDA, SDD, VID. This rule will be controlled by the MNSW-Core in the semantic checks (refer to MIG-P14). If formalities cannot be updated, then the update needs to be arranged through relevant procedures defined by the corresponding authority(ies) if needed and allowed.

    MIG-P29 – Withdrawing previously provided formalities

    Formalities of the following types can be withdrawn: ABS, ACT, BLU, BKA, BKD, BWA, CGA, CGD, CRT, CWA, CWD, DUE, EFF, EXP, EXS, HOS, HZA, HZD, HZS, MDD, MDH, MTS, NAV, NOS, PBK, POA, POD, PNO, PXA, PXD, REN, SEC, SHP, SSA, STA, STD, STW, SRV, TRA, TRD, TSD, VIS, WAS, WAR.

    Formalities of the following types cannot be withdrawn: ATA, ATD, CAR, CGM, COA, EXT, NAC, NOA, NOD, PPA, SDA, SDD, SID, VID.

    The formality message sent to withdraw a formality must contain the MAI header only. The MAI header must contain the information indicated in principle MIG-P23.

    Once a withdrawal request is received and accepted (by a formality response message), the corresponding formality is ignored by the authorities and will not generate any further processing. After a successful withdrawal, the same or a different declarant may submit a new formality of the same type.

    If formalities cannot be withdrawn, then the withdrawal needs to be arranged through relevant procedures defined by the corresponding authority(ies) if needed and allowed.

    MIG-P14 – Use of response message for formality responses and process responses

    The MNSW uses the response message for communicating authorities’ responses to the declarants.
    Formality response: a formality response is returned directly after having checked the semantics of a formality message (e.g. acknowledgment of receipt of a formality). Depending on the architecture of the MNSW, semantic checks are done either by the MNSW-Core or by relevant authorities behind the MNSW Core. Each submitted formality that passes the syntax, rules and conditions checks (see MIG-P19) will receive a formality response.

    If the formality does not pass the semantics checks, it will not cause any further processing by the authorities. The formality response will indicate the reasons for the rejection in form of a list of errors. Each formality which is rejected due to semantic checks will need to be corrected and resent (with a distinct Message Identifier).

    The formality response must include the message status (accepted, rejected), the Visit ID, the type of formality, the formality reference number (when relevant, see MIG-P24), the reference number of the formality message (message identifier) and possibly a process reference number issued by an authority (e.g. MRN – Master Reference Number as defined in R04).

    In the case of a rejection, the formality response includes a list of errors identified by a code and with an optional textual description. The formality response may as well include a list of warnings identified by a code with an optional textual description. Warnings do not imply a rejection of the formality and may be provided in both cases where the formality passes the semantics checks or is rejected. Along an error or a warning, the reference to one or several classes or attributes in the formality may be provided. The attribute or class reference takes the form of a position in the formality message in xpath format, and eventually of an item number if the position corresponds to an attribute in a list (if the list contains a “sequence number” attribute, the value of the sequence number of the received occurrence is used. If there is no attribute “Sequence number” in the list, the position of the occurrence in the list is used).

    MIG-P23 – Each formality message must contain sequence information

    Updating or withdrawing [2] a formality is done by sending a formality message. Updates and withdrawals are therefore done per individual formality. " +For an update or withdrawal, the formality message must contain the Visit ID, the type of formality, and when necessary, the formality reference number (i.e. LRN), as in the initial message. For customs formalities, the MRN assigned to the initial formality must be reported.

    To control the sequence of formality messages per message chain, each message needs to contain the following data elements:

    1. Message function code: original or withdrawal,
    2. Authentication date time, representing the date and time when the information contained in the formality has been certified by the declarant.

    When a formality message is received by the MNSW in the wrong sequence i.e. the message’s authentication date time is earlier than the authentication date time of the latest message already received and accepted by the MNSW for the same formality then the message is rejected by the MNSW (formality response with message status “rejected”).

    When a formality message with function code “withdrawal” is received by the MNSW while no previous formality message for the same formality had been received by the MNSW, then the message is accepted by the MNSW and any formality message for that formality with an earlier authentication date time than the accepted withdrawal message’s authentication date time will be rejected because out of sequence.

    Update or withdraw existing formality.

    Allowed updates of formalities in Finland

    Formalities of the following types can be updated: ATA, ATD, CGA, CGD, CRT, CWA, CWD, DUE, EFF, HZA, HZD, MDD, MDH, MTS, NOA, NOD, NOS, PXA, PXD, SEC, SID, SHP, SRV, SSA, STA, STD, WAS, WAR.

    Formalities of other types cannot be updated: COA and VID.

    If formality is already withdrawn, it cannot be updated.

    NOTE! At the moment, it is not possible to send files via the National Declarant API. If you need to update files for a formality, you must do so through the NEMO UI.

    Withdrawing previously provided formalities in Finland

    Formalities of the following types can be withdrawn: CGA, CGD, CRT, CWA, CWD, DUE, EFF, HZA, HZD, MDD, MDH, MTS, PXA, PXD, SEC, SHP, SSA, STA, STD, SRV, WAS, WAR.

    Formalities of the following types cannot be withdrawn: ATA, ATD, COA, NOA, NOD, SID, VID.

    The formality message sent to withdraw a formality must contain the MAI header only. If formality is already withdrawn, it cannot be withdrawn again.NOTE! The value of ram:PurposeCode must be 1.

    path Parameters
    visitId
    required
    string [ 0 .. 35 ] characters
    Example: c5f034b28f6445f69497b83e69159665

    The ID of the port call to retrieve formalities for. Max length is 35 characters.

    formalityType
    required
    string
    Examples:
    • NOA - update_success_request
    • VID - update_error_400_request
    • MDH - withdraw_success_request
    • NOA - withdraw_error_400_request

    The type of the formality to update.

    formalityId
    required
    string <uuid>
    Examples:
    • 2c2d5312-afc2-4356-b74b-29e5e4a68663 - update_success_request
    • 437d9500-f3b9-47c6-b87e-e36f0f7f84cb - update_error_400_request
    • 7a7b5acf-0812-4114-a105-66cb5eab407c - withdraw_success_request
    • 2c2d5312-afc2-4356-b74b-29e5e4a68663 - withdraw_error_400_request

    The ID of the formality to update.

    Request Body schema: application/json
    required

    formality data

    any (JsonNode)

    Responses

    Request samples

    Content type
    application/json
    Example

    update_success_request

    {
    • "env:Envelope": {
      }
    }

    Response samples

    Content type
    application/json
    Example

    update_success_response

    {
    • "env:Envelope": {
      }
    }

    Create a new formality

    Create a new formality. The formality type is determined by the type field in the request body.

    Only the following way can be used to send formalities in Finland:

    There can be only one formality per port call (i.e. per Visit ID) for the following formality types: ATA, ATD, COA, CWA, CWD, EFF, HZA, HZD, MDD, MDH, MTS, NOA, NOD, PXA, PXD, SEC, SHP, SID, SSA, STA, STD, VID, WAS.

    The following formality types can be reported in several formalities per port call (i.e. per Visit ID) and by different declarants: CGA, CGD, CRT, DUE, SRV, WAR.

    The formality messages for formality types CGA, CGD, CRT, DUE, SRV, and WAR must include a formality reference number. This mandatory reference number is a unique LRN which is issued by the sender of the formality message.

    NOTE! At the moment, it is not possible to send files via the National Declarant API. We recommend submitting the CRT formality through the NEMO UI, even though it is possible to submit the CRT formality without a file using the National Declarant API.

    path Parameters
    visitId
    required
    string [ 0 .. 35 ] characters
    Example: c5f034b28f6445f69497b83e69159665

    The ID of the port call to retrieve formalities for.

    formalityType
    required
    string
    Example: NOA

    The type of the formality to create.

    Request Body schema: application/json
    required

    formalityData

    any (JsonNode)

    Responses

    Request samples

    Content type
    application/json
    Example

    success_request

    {
    • "env:Envelope": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "env:Envelope": {
      }
    }

    Retrieve a list of formalities. Formalities are returned in the order they were created by callers organization.

    path Parameters
    visitId
    required
    string [ 0 .. 35 ] characters
    Examples:
    • c5f034b28f6445f69497b83e69159665 - success_request
    • a4cc7783756541e09a4bdf7260 - error_400_request

    The ID of the port call to retrieve formalities for.

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      },
    • {
      }
    ]