All APIs require authentication, which is delegated to Auth0. Before any of the following external APIs can be accessed, the requestor needs to authenticate using a client id and client secret. The returned bearer token is then added to the request headers.
Screen APIs
The Screen APIs allow access to Trade Check, Pre-Arrival Check and Vessel Health Check submissions, as well as request their status.
Usage
To use the Screen APIs, an account is required to obtain an Access Token by authenticating. All requests must be formatted as JSON and contain the following headers:
Header Name | Header Value | Optional | Comments |
Authorization | Bearer <access-token> | false |
|
Content-Type |
| false |
|
Each response will have the following structure, where data field will contain the actual data payload.
Property Name | Property Type | Can be Empty |
Success | bool | false |
ErrorMessage | String? | true |
Data | Payload Data Type | tru |
Example response including data:
{
"success": true,
"errorMessage": null,
"data": {
"uniqueIdentifier": "c91cd0bd-cf61-46fb-91bc-b6ba1a9af3a0"
}
}
Response Codes
Http Response Code | Description |
200 | Successful |
400 | Bad Request – Missing/invalid input parameters |
401 | Unauthenticated – the authentication access token is missing or expired |
403 | Unauthorized – the user is logged in successfully, however does not have permission to access the requested resource. |
500 | Unexpected error – please contact support along with any returned error messages |
Submit Pre-Arrival Check
Create a new pre-arrival check. Pre-arrival check will be created for the user associated to the client access token.
Request Uri: [HttpPost] /api/prearrival/v1
Request:
Property Name | Property Type | Optional | Comments |
VesselIMO | string | false | Vessel International Maritime Organization Number |
RequestedOnBehalfOfCompanyName | string? | true | Create Pre-Arrival Check on behalf of another company |
RequestedOnBehalfOfName | string? | true | Create Pre-Arrival Check on behalf of another company |
RequestedOnBehalfOfEmail | string? | true | Create Pre-Arrival Check on behalf of another company |
ArrivalPortExternalCode? | string | true | Arrival port |
EstimatedDateOfArrival | date? | true | Estimated date of arrival |
CargoTypeExternalCode? | string | true | Cargo type |
IsConfirmed | bool | false | Is Pre-Arrival Check confirmed |
Response:
Property Name | Property Type | Can Be Empty | Comments |
UniqueIdentifier | String? | True | If the pre-arrival check creation request was successful, this will contain an unique identifier for the new submission |
Notes:
- Any codes required are provided by their respective APIs, for instance CargoTypeExternalCode can be retrieved from the CargoType API documented below.
- Any fields in the request body which are marked with a ‘?’ are optional.
- When the pre-arrival check request is submitted, the creation part of the submission is queued. The uniqueIdentifier in the response can be used to query the pre-arrival check creation status by calling the Get PreArrivalCheck Status API.
Get Pre-Arrival Check Status
Get the creation status of a previously created Pre-Arrival Check.
Request Uri: [HttpGet] /api/prearrival/v1/{UniqueCode}
Request: empty
Response:
Property Name | Property Type | Can Be Empty |
UniqueIdentifier | string | false |
RequestTimestamp | datetime | false |
SafetyScore | decimal? | true |
GhgRating | string? | true |
GhgRatingVerification | string? | true |
InspectionStatus | string? | true |
OverallRiskLevel | string? | true |
RiskAnalysisCategories | RiskAnalysisCategory[] | true |
RequestedOnBehalfOfCompanyName | string? | true |
RequestedOnBehalfOfName | string? | true |
RequestedOnBehalfOfEmail | string? | true |
RiskAnalysisCategory:
Property Name | Property Type | Can Be Empty | Comments |
RiskLevel | string | true |
|
Category | string | false |
|
RuleCount | int | false |
|
CategoryRules | Rule[] | false |
|
Rules:
Property Name | Property Type | Can Be Empty | Comments |
Timestamp | datetime | false |
|
Outcome | string? | true |
|
IsSuccessful | string | false |
|
IsInformationRule | bool | false |
|
Name | string? | true |
|
RiskLevel | string | false |
|