Skip to main content
Skip table of contents

APIs

This is an additional solution and requires a separate license.

APIs

The APIs module provides a standard set of web services, implemented as a set of RESTful interfaces, that allow external systems to retrieve information and submit Voyage Reporting form XML. The available endpoints and the actions available are documented at https://api.veslink.com/Help.

The methods available via the API are mainly GET and POST (with a PATCH method available to act on IMOS Dataforms).

The API supports form XML for all standard Voyage Reporting forms.

  • For in-port forms (for example, the Statement of Facts form), the nomination of a particular external system for a port call can occur within the Veson IMOS Platform. These nominations are replicated from the Veson IMOS Platform to Voyage Reporting and are accessible via the web service.

Enabling User-level Access to the API

Access to the API is administered per user. In order to use the API, the user must belong to a Company defined in the Veson IMOS Platform and have the API ReadAPI Write, and/or API IMOS Message General Permissions enabled.

Additionally, the user's API access will mimic the user's existing Object and Module Permissions; for example, if the user only has Object Vessel Permissions for Vessels "A" and "B," when requesting a list of vessels using the API, only Vessels "A" and "B" will be returned and no others.

If a user has API access, there is no additional security assigned to endpoints. The exception to this policy is for reports. The Administrator can assign or revoke access to reports on a per-user basis. On top of the report access privileges, the creator of a report can make the report private or public, which adds another layer of access security on reports.

Managing Access to the API

The API is protected from unauthorized access by two factors of authentication:

  • An API Token, which is generated for a IMOS user account

  • An IP Allowlist entry, specifying allowed networks or machines for API access

    • By default the Allowlist is unenabled, allowing accessing from any IP address. Please submit a support request to restrict access to certain IP addresses.

Once a user's API Token is generated, it will not expire; however, each user has access to their own API Token in the same way and can refresh or clear the token as often as desired. The Administrator can revoke API access for a user by modifying the user's Voyage Reporting Permissions.

Managing API Tokens

You must request a unique API token to authenticate with all API calls. The API Token is passed in all of the query strings for each call and is valid until you clear it.

  1. Do one of the following:

    • To request or clear your own API Token, open the My Profile panel.

    • As an administrator, to request or clear a user's API Token, open the User Profile tab from the Security list.

  2. In the API Token or Veslink API section, click Request New API Token.

  3. An API Token appears.

    • To request a new API Token, click Request New API Token.

    • To deactivate the current API Token, click Clear API Token.

API Monitoring and Security

Veson Nautical has added monitoring and security enhancements to the API, namely:

  • Programmatic access to the API logs for a given account, for the purposes of monitoring compliance, uncovering misuse, and gathering data for analytics.

  • The option to embed the API Token in the authorization header of an API call. The default API syntax includes the API Token in the query parameters, while a new option embeds the token as a bearer token in an API header. This option removes the API Token from browser address bars, router logs, and other sources where the token may be exposed.

Related Configuration Flags

Name/Flag

Description

API Reports Raw Column Names
CFGAPIReportsRawColumnNames

If enabled, getting reports via the API will assign column names based on table.column format.

Enable JSON Path Query
CFGEnableJsonPathQuery

When enabled, Report Designer reports will have the Optimize query for document export option available. This makes exporting to XML via datashed and the API faster for certain reports. Requires SQL Server 2016 or newer.

Email Web Hook
CFGEmailWebHook

Provides the ability to send the eml URL generated when triggering an email from the Veson IMOS Platform to a specific endpoint. Place the {emlUrl} placeholder where you want it to appear in the endpoint you are configuring.

The outgoing email includes:

  • To, CC, and BCC email addresses

  • Subject heading

  • The email message, either:

    • Embedded in the HTML body

    • Attached as a PDF

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.