openapi: 3.1.0
info:
title: Portbase Port Community System API
description: >-
Portbase is the Dutch Port Community System providing APIs for customs declarations,
cargo manifests, vessel call notifications, berth planning, and port logistics
coordination at the Port of Rotterdam and Amsterdam, connecting shipping lines,
freight forwarders, customs authorities, and terminal operators.
version: 1.0.0
contact:
name: Portbase Support
url: https://www.portbase.com/en/contact/
license:
name: Portbase Terms of Service
url: https://www.portbase.com/en/about-portbase/terms-and-conditions/
servers:
- url: https://api.portbase.com/v1
description: Portbase Production API
security:
- oauth2: []
tags:
- name: CargoManifests
description: Cargo manifest declarations
- name: Containers
description: Container tracking and inspection
- name: CustomsDeclarations
description: Import and export customs filings
- name: HazardousCargo
description: Dangerous goods declarations
- name: VesselCalls
description: Vessel arrival and departure notifications
paths:
/vessel-calls:
get:
operationId: listVesselCalls
summary: List vessel calls
description: Returns vessel call notifications for upcoming arrivals and departures at Dutch ports.
tags:
- VesselCalls
parameters:
- name: portCode
in: query
description: UN/LOCODE of the port (e.g., NLRTM for Rotterdam)
schema:
type: string
example: NLRTM
- name: status
in: query
description: Filter by vessel call status
schema:
type: string
enum: [EXPECTED, ARRIVED, BERTHED, DEPARTED, CANCELLED]
- name: fromDate
in: query
description: Earliest expected arrival date
schema:
type: string
format: date-time
- name: toDate
in: query
schema:
type: string
format: date-time
- name: offset
in: query
schema:
type: integer
default: 0
- name: limit
in: query
schema:
type: integer
default: 100
maximum: 500
responses:
'200':
description: Vessel call list
content:
application/json:
schema:
type: object
properties:
vesselCalls:
type: array
items:
$ref: '#/components/schemas/VesselCall'
totalCount:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createVesselCall
summary: Submit vessel call notification
description: Submits a pre-arrival vessel call notification (PARN) to the port authority.
tags:
- VesselCalls
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VesselCallCreate'
responses:
'201':
description: Vessel call submitted
content:
application/json:
schema:
$ref: '#/components/schemas/VesselCall'
'400':
$ref: '#/components/responses/BadRequest'
/vessel-calls/{vesselCallId}:
get:
operationId: getVesselCall
summary: Get vessel call
description: Returns details for a specific vessel call including berth allocation and status.
tags:
- VesselCalls
parameters:
- $ref: '#/components/parameters/VesselCallId'
responses:
'200':
description: Vessel call details
content:
application/json:
schema:
$ref: '#/components/schemas/VesselCallDetail'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateVesselCall
summary: Update vessel call
description: Updates a vessel call notification with revised arrival times or cargo information.
tags:
- VesselCalls
parameters:
- $ref: '#/components/parameters/VesselCallId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VesselCallUpdate'
responses:
'200':
description: Vessel call updated
content:
application/json:
schema:
$ref: '#/components/schemas/VesselCall'
/cargo-manifests:
post:
operationId: submitCargoManifest
summary: Submit cargo manifest
description: Submits a cargo manifest declaration for a vessel call, listing all cargo on board.
tags:
- CargoManifests
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CargoManifestCreate'
responses:
'201':
description: Manifest submitted
content:
application/json:
schema:
$ref: '#/components/schemas/CargoManifest'
'400':
$ref: '#/components/responses/BadRequest'
/cargo-manifests/{manifestId}:
get:
operationId: getCargoManifest
summary: Get cargo manifest
description: Returns a cargo manifest with all cargo lines and customs status.
tags:
- CargoManifests
parameters:
- name: manifestId
in: path
required: true
schema:
type: string
responses:
'200':
description: Cargo manifest details
content:
application/json:
schema:
$ref: '#/components/schemas/CargoManifest'
'404':
$ref: '#/components/responses/NotFound'
/customs/import-declarations:
post:
operationId: submitImportDeclaration
summary: Submit import customs declaration
description: Submits an electronic import declaration (EID) to Dutch customs via Portbase.
tags:
- CustomsDeclarations
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ImportDeclarationCreate'
responses:
'201':
description: Declaration submitted to customs
content:
application/json:
schema:
$ref: '#/components/schemas/CustomsDeclaration'
'400':
$ref: '#/components/responses/BadRequest'
/containers/{containerId}:
get:
operationId: getContainer
summary: Get container status
description: Returns tracking information and inspection status for a shipping container.
tags:
- Containers
parameters:
- name: containerId
in: path
required: true
description: Container number (ISO 6346 format, e.g. MSCU1234567)
schema:
type: string
pattern: '^[A-Z]{4}[0-9]{7}$'
responses:
'200':
description: Container details
content:
application/json:
schema:
$ref: '#/components/schemas/Container'
'404':
$ref: '#/components/responses/NotFound'
/hazardous-cargo:
post:
operationId: submitHazardousCargoDeclaration
summary: Submit hazardous goods notification
description: Submits an IMDG dangerous goods declaration for hazardous cargo on a vessel call.
tags:
- HazardousCargo
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HazardousCargoDeclaration'
responses:
'201':
description: Hazardous cargo declaration submitted
'400':
$ref: '#/components/responses/BadRequest'
components:
securitySchemes:
oauth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://auth.portbase.com/oauth2/token
scopes:
vessel-calls.read: Read vessel call data
vessel-calls.write: Submit and update vessel calls
manifests.write: Submit cargo manifests
customs.write: Submit customs declarations
parameters:
VesselCallId:
name: vesselCallId
in: path
required: true
description: Portbase vessel call identifier
schema:
type: string
responses:
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
VesselCall:
type: object
description: A vessel arrival/departure call at a Dutch port
properties:
vesselCallId:
type: string
imoNumber:
type: string
description: IMO vessel identification number (7 digits)
pattern: '^\d{7}$'
mmsi:
type: string
description: Maritime Mobile Service Identity
vesselName:
type: string
callSign:
type: string
flag:
type: string
maxLength: 3
description: ISO 3166-1 alpha-3 flag state
portCode:
type: string
description: UN/LOCODE
terminalCode:
type: string
status:
type: string
enum: [EXPECTED, ARRIVED, BERTHED, DEPARTED, CANCELLED]
eta:
type: string
format: date-time
description: Estimated time of arrival
etd:
type: string
format: date-time
description: Estimated time of departure
ata:
type: string
format: date-time
nullable: true
description: Actual time of arrival
atd:
type: string
format: date-time
nullable: true
description: Actual time of departure
shippingAgent:
type: string
pilotageRequired:
type: boolean
tugAssistance:
type: boolean
VesselCallCreate:
type: object
required:
- imoNumber
- vesselName
- portCode
- eta
- etd
properties:
imoNumber:
type: string
pattern: '^\d{7}$'
vesselName:
type: string
callSign:
type: string
portCode:
type: string
terminalCode:
type: string
eta:
type: string
format: date-time
etd:
type: string
format: date-time
shippingAgent:
type: string
pilotageRequired:
type: boolean
default: true
VesselCallUpdate:
type: object
properties:
eta:
type: string
format: date-time
etd:
type: string
format: date-time
terminalCode:
type: string
status:
type: string
enum: [EXPECTED, ARRIVED, DEPARTED, CANCELLED]
VesselCallDetail:
allOf:
- $ref: '#/components/schemas/VesselCall'
- type: object
properties:
berthPlan:
$ref: '#/components/schemas/BerthPlan'
cargoManifestIds:
type: array
items:
type: string
BerthPlan:
type: object
properties:
berthId:
type: string
berthName:
type: string
plannedArrival:
type: string
format: date-time
plannedDeparture:
type: string
format: date-time
bollardFrom:
type: integer
bollardTo:
type: integer
CargoManifest:
type: object
properties:
manifestId:
type: string
vesselCallId:
type: string
declarantId:
type: string
description: EORI number of the declarant
submissionDatetime:
type: string
format: date-time
status:
type: string
enum: [DRAFT, SUBMITTED, ACCEPTED, REJECTED, RELEASED]
lines:
type: array
items:
$ref: '#/components/schemas/CargoManifestLine'
CargoManifestCreate:
type: object
required:
- vesselCallId
- declarantId
- lines
properties:
vesselCallId:
type: string
declarantId:
type: string
lines:
type: array
items:
$ref: '#/components/schemas/CargoManifestLine'
CargoManifestLine:
type: object
properties:
lineNumber:
type: integer
containerNumber:
type: string
billOfLadingNumber:
type: string
cargoDescription:
type: string
hsCode:
type: string
description: HS tariff code (6 digits)
grossWeight:
type: number
format: double
grossWeightUnit:
type: string
enum: [KG, MT]
packageCount:
type: integer
packageType:
type: string
portOfLoading:
type: string
description: UN/LOCODE of port of loading
portOfDischarge:
type: string
description: UN/LOCODE of port of discharge
shipper:
type: string
consignee:
type: string
CustomsDeclaration:
type: object
properties:
declarationId:
type: string
declarationType:
type: string
enum: [IMPORT, EXPORT, TRANSIT]
mrn:
type: string
description: Movement Reference Number from customs
status:
type: string
enum: [PENDING, ACCEPTED, CONTROLLED, RELEASED, REJECTED]
submissionDatetime:
type: string
format: date-time
releaseStatus:
type: string
nullable: true
ImportDeclarationCreate:
type: object
required:
- manifestId
- declarantId
- consigneeId
- lines
properties:
manifestId:
type: string
declarantId:
type: string
description: EORI number
consigneeId:
type: string
description: EORI number of consignee
lines:
type: array
items:
type: object
Container:
type: object
properties:
containerNumber:
type: string
isoType:
type: string
description: ISO 6346 container type code
status:
type: string
enum: [ON_VESSEL, AT_TERMINAL, IN_CUSTOMS, RELEASED, PICKED_UP]
terminalCode:
type: string
vesselCallId:
type: string
customsStatus:
type: string
enum: [NOT_YET_DECLARED, DECLARED, RELEASED, CONTROLLED, BLOCKED]
inspectionStatus:
type: string
enum: [NOT_SELECTED, SELECTED, INSPECTED, CLEARED]
lastUpdateDatetime:
type: string
format: date-time
HazardousCargoDeclaration:
type: object
required:
- vesselCallId
- imdgClass
- unNumber
- quantity
properties:
vesselCallId:
type: string
containerNumber:
type: string
imdgClass:
type: string
description: IMDG hazard class (e.g., 1.1, 3, 8)
unNumber:
type: string
pattern: '^UN\d{4}$'
description: UN substance number
properShippingName:
type: string
quantity:
type: number
format: double
quantityUnit:
type: string
enum: [KG, L, MT]
packingGroup:
type: string
enum: [I, II, III]
flashPoint:
type: number
format: double
nullable: true
emergencyContact:
type: string
Error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: array
items:
type: string