Q88 - Web Services API Reference

1. Overview

The Q88 Web Services API lets your systems exchange vessel data with Q88 directly, instead of exporting and re-keying it by hand. It is a SOAP/ASMX service, so every operation is also reachable over a plain HTTP GET, which makes it straightforward to consume from any language.

The API is read-first. Most operations pull data out of Q88 questionnaires, HVPQ answers, vessel specifications, certificates, inspections and officer matrices so that Q88 remains the single source of truth and your systems stay in step with it. Two data types can also be pushed into Q88: officer matrices and certificates.

2. Before you start

2.1 Prerequisites

Three things must be in place before any call will succeed. All three are set up by Veson, there is no self-service portal.

Requirement	What it means	How to obtain it
Web Services subscription	Web Services is an additional add on to your subscription with the Q88 platform.	Your Account Manager
Per-operation enablement	Operations are switched on individually basis what you have subscribed to.	Support, on request
IP whitelisting	Calls are only accepted from public IP addresses registered against your account. Private or internal addresses (for example `10.x`, `172.16–31.x`, `192.168.x`) cannot be white listed.	Support, on request

If your traffic leaves through a gateway, proxy, NAT or cloud API management layer, send us the outbound public IP of that layer, not the internal address your application sees. Checking http://whatismyipaddress.com from the calling host is the quickest way to confirm it.

2.2 Authentication

Every operation takes an AuthorizationString parameter. This is a single fixed token for your company there is no OAuth flow, no login call and no token refresh. The same string is used across all operations you have access to.

3. Testing your access

You do not need to write any code to test an operation. Most operations take only two parameters your authorization string and a vessel identifier and a few take just one. That makes every operation testable from a browser address bar in under a minute.

Test before you build. It separates an access problem from an integration problem, which is much harder to diagnose once there is code in between.

Every operation is checked against your allowlisted IP addresses, so run your tests from the same network your integration will eventually call from. Testing from a home connection, a mobile hotspot or a VPN with a different exit node will return Permission Denied even when everything on your account is correctly configured.

3.1 Test in the browser, no code required

Every operation has a built-in test form. Add ?op= and the operation name to the service URL:

https://www.q88.com/ws/api.asmx?op=GetQ88XML

Open the URL in a browser, on an allowlisted network.
Fill in AuthorizationString, and whichever vessel parameter the form shows.
Leave optional parameters blank.
Click Invoke. The response opens in a new tab.

The form is regenerated from the service itself, so it is always an accurate view of the parameters an operation accepts. It is also the quickest way to confirm which operations are enabled on your account if one is not enabled, invoking it returns Permission Denied.

This is the smallest set of parameters that will return data. Anything not listed here is optional for a first test and can be left blank.

AuthorizationString is required by all of them and is omitted from the table for readability. Where a vessel identifier is needed, IMO is the safer choice vessel names are not unique and may not match Q88's spelling.

Auth only

Operation	Params	Also supply	Notes for testing
`GetHVPQQuestions_XmlString`	1	—	Best first test. Not vessel-specific, so a valid response proves your token and IP are working.
`CertificateXML_GetCertificateListFormat`	1	—	Also vessel-independent. Good second test if you are building a certificate integration.

Auth plus one vessel identifier

Operation	Params	Also supply	Notes for testing
`GetQ88XML`	2	`IMO`	Use a vessel on your own account.
`GetQ88`	2	`VesselName`	Accepts an IMO number in the `VesselName` field. Returns HTML, so expect a wall of markup.
`GetBalt99XML`	2	`IMO`	Q88 Dry only test against `dry.q88.com`.
`GetBalt99`	2	`VesselName`	Q88 Dry only.
`GetQuestionnaires`	2	`IMO`	Returns the list of questionnaires held for the vessel.
`GetCertificates_DataSet`	2	`IMO` or `VesselName`	Send one and leave the other blank. Returns the standard certificate list only.
`GetInspectionObservations_DataSet`	2	`IMO`	An empty result is normal if the vessel has no recorded observations.
`GetVettings_XmlString`	2	`IMO` or `VesselName`	An empty result is normal if the vessel has no SIRE or CDI record.
`GetNonHVPQAnswers_XmlString`	2	`IMO`	Returns only the answers that do not come from the HVPQ.
`CertificateXML_GetVesselCertificateValue`	2	`IMO` or `VesselName`	Leave `CertificateID` blank to return everything.
`CertificateXML_GetVesselCertificateAttachment`	2	`AttachmentID`	Take an `AttachmentID` from a `CertificateXML_GetVesselCertificateValue` response first. Returns Base64, not a file.

Auth plus both name and IMO

Operation	Params	Also supply	Notes for testing
`GetVesselSpecs_XmlString`	3	`VesselName` + `IMO`	Both are required. `ShipType` is optional leave it blank.
`GetOfficerMatrix_XMLString`	3	`VesselName` + `vesselIMO`	Note the parameter is `vesselIMO`, not `IMO`. Case-sensitive.
`GetHVPQAnswers_XmlString`	5	`VesselName` + `IMO` + `Chapter` + `SinceLastUpdated`	Test with `Chapter=1` and `SinceLastUpdated=01-01-1970` to return everything.

Write operations — test with care

Operation	Params	Also supply	Notes for testing
`ImportOfficerMatrix`	2	`xml` payload	Overwrites existing crew data for the vessel. See the warning below before testing.
`OfficerMatrixProcess`	2	`xml` payload	Same caution applies.
`CertificateXML_ImportVesselCertificate`	2	certificate XML payload	Can update and delete certificates. Same caution applies.

Imports overwrite rather than merge, so a test submission will replace the crew or certificate records already held for that vessel. Contact Support before your first import and we will arrange a safe way to test.

3.2 Reading the result

What you see	Meaning	Next step
An XML document with vessel data	Working	Token, IP and operation access are all correct. Start building.
`<string>Permission Denied</string>`, or Web Service Permission Denied	Blocked	One of three causes. Work through section 8.1 in order IP first, it is the usual one.
An XML document with no records inside it	Working, no data	Access is fine. Either the vessel holds no data of that type, or it is not on your account. Retry with a vessel you know has data.
The page will not load at all	Network	Traffic is not reaching Q88. Check outbound firewall rules and proxy configuration before raising a ticket.
A SOAP fault	Bad request	Usually a misspelled parameter name. Check casing against section 4.3 `vesselIMO` and `_XMLString` are the common ones.

4. Getting help

What you need	Who to contact
Add or change an Whitelisted IP address	Veson Nautical Help Center — Q88 and Shipfix
Enable a specific operation on your account	Help Center. Name the operation in your request.
Reissue your authorization string	Help Center
Request an XSD or an integration guide	Help Center
Add Web Services to your subscription, or discuss pricing	Your Account Manager
Report a data discrepancy	Help Center. Include the operation name, vessel IMO, and the timestamp of the call.

Include the operation name, the vessel IMO, the public IP you are calling from, the timestamp, and the full response text. Do not include your authorization string, Support can look it up against your account.