Skip to main content
All CollectionsAPI
PSC Submission API
PSC Submission API

Submit Port State Control inspections and close-outs to RightShip

Updated over a week ago

The Port State Control (PSC) Submission API provides the ability to send inspections and close-outs for your vessels.

What we offer

With the PSC Submission API you can:

  • Provide RightShip with

    • details of PSC inspections that we do not have in our platform

    • corrections to PSC inspections that are in our platform

    • close-out information, including attaching evidence

  • Retrieve

    • the processing status of any new submissions

    • a list of changed inspection records based on a date range

    • details of submitted inspections, including the close-out status

Optionally you can also provide your own API endpoint (webhook) to accept Requests for Information (RFIs) sent by RightShip.

Authentication

Our APIs are protected using the Auth0 authorization platform. This means that only certain user groups and entities are allowed access to certain endpoints.

To use the PSC Submission API, you will need an account and obtain an access token from Auth0, using the Client ID and Client Secret that has been shared with you.

NOTE: Do not share these with anyone.

All requests must be formatted as JSON and contain the following:

Submit PSC inspections

You can submit up to 100 PSC Inspections in a single submission. Each inspection must follow the format described below. An identifier, <DATA_SUBMISSION_ID>, will be returned which can be used to track the status of the entire submission in bulk.

To submit inspections, make a POST request to /api/v1/psc/submission, passing the token retrieved from Auth0 to the Authorization Header, following the request body structure below.

NOTE: In order to keep track of your submissions, cross-reference records, and allow updates, you must supply a unique identifier for each inspection, deficiency, and attachment submitted. These values should be provided in the thirdPartyPscInspectionId, thirdPartyDefectId, and thirdPartyAttachmentId fields respectively.

Example

Response

Response codes

Response Code

Response Description

0

Successful

1

Empty Submission

2

Invalid Request

3

Exceeded maximum entries (100 records)

5

Unexpected Value in Property

10

Duplicate Third Party PSC Inspection Ids in submission

99

Unhandled Error

Track the status of a PSC submission

Once a submission has been received, an immediate response containing a dataSubmissionId will be provided and processing will occur asynchronously. In order to keep track of the submission status, or determine if an error has occurred during processing, it is recommended to regularly query the status endpoint until the status becomes Completed.

To track the status of a submission, make a POST request to /api/v1/psc/status providing either a dataSubmissionId or an array of thirdPartyPscInspectionIds in the body.

NOTE: if an individual inspection has errors during processing, it will be provided in the error field.

Example

Response

Response codes

Response Code

Response Description

0

Successful

1

Empty Submission

2

Invalid Request

3

Exceeded maximum entries (100) per submission

5

Unexpected property in value

99

Unhandled Error

Submission statuses

Status Text

Description

New

The submission of the PSC inspection has been registered.

Processing

The PSC inspection is being processed, parsed, and mastered.

Completed

The data has been used to insert a new record or update an existing one.

Closed

The PSC Inspection is closed and is not allowed to be further updated

Retrieving PSC inspection changes by date

Users are able to retrieve a list of IDs for all inspections that were previously submitted via API and have been updated during the period specified.

To query inspections that have been modified during a specified date range, make a POST request to /api/v1/psc/changes-by-date providing a lastModifiedDateFrom and optionally a lastModifiedDateTo in the body.

NOTE: The date range specified cannot be more than 30 days.

Example

Response

Response codes

Response Code

Response Description

0

Successful

1

Empty submission

2

Invalid Request

5

Unexpected property in value

10

Missing LastModifiedDateFrom

11

Date range is greater than 30 days

99

Unhandled Error

Retrieving PSC inspections

To retrieve the full details of inspections that were previously submitted via API, make a POST request to /api/v1/psc/retrieve with an array of rightshipPscInspectionIds in the body.

Example

Response

Response codes

Response Code

Response Description

0

Successful

1

Empty submission

2

Invalid Request

3

Exceeded maximum inspections (100)

5

Unexpected property in value

10

RightShip PSC Inspection Id(s) not found

99

Unhandled error

Inspection statuses

Status

Closed

Opened

Misreported

Accepting RFIs (Not available for testing environment)

In order to receive RFIs, you must provide a publicly accessible HTTP endpoint that supports a POST request formatted as JSON in the body. The endpoint must also be secured (e.g. using an API key) and suitable credentials, along with the endpoint URL, supplied to RightShip as part of the initial setup.

When a new RFI is requested in the RightShip platform, related to a submitted inspection. RightShip will make a POST request to the <ENVIRONMENT_URL>/<ACCEPT_RFI_ENDPOINT>.

Authentication will be done by using a secret shared between parties and passed in the header Ocp-Apim-Subscription-Key. Such key is to be shared by the Customer.

Example

Response

Response codes supported

Response Code

Response Description

0

Successful

1

Empty submission

2

Invalid Request

5

Unexpected property in value

10

Unknown RightshipPscInspectionId

99

Unhandled Error

Definitions

<ENVIRONMENT_URL>

Dependent on the environment you are using, a different base URL is available.

<CLIENT_ID>

A unique identifier associated with a specific entity / user.

Needed to authenticate with Auth0.

<CLIENT_SECRET>

A string needed to authenticate the client ID above with Auth0, like a password. DO NOT SHARE.

<AUDIENCE>

Specifies the API group that you are attempting to generate an access token for.

<ACCESS_TOKEN>

The token that is returned after successful authentication via Auth0. To be passed in subsequent requests to the API, via Bearer Token scheme.

<AUTH0_TOKEN_URL>

The URL endpoint to retrieve the Authorization access token.

<DATA_SUBMISSION_ID>

A GUID which uniquely identifies a data submission.

<RIGHTSHIP_PSC_INSPECTION_ID>

A GUID which uniquely identifies a PSC Inspection on the RightShip platform.

<THIRDPARTY_PSC_INSPECTION_ID>

The unique ID that an inspection is associated with on your system / another third-party system.

<THIRDPARTY_PSC_DEFECT_ID>

The unique ID that an inspection’s defect is associated with on your system / another third-party system.

<THIRDPARTY_PSC_ATTACHMENT_ID>

The unique ID that an inspection’s attachment is associated with on your system / another third-party system.

<STATUS_DATE>

The date that a PSC Inspection status update change was performed.

<STATUS>

The status update itself.
There will be a specified ENUM of possible status updates.

<MESSAGE>

The message associated with an RFI.

<RFI_ID>

The identifier of an RFI generated by RightShip.

Standard Response Codes

All endpoints may return the following standard response codes, in the range 0-9, and 99. Status codes 10-98 are reserved for errors related to specific endpoints.

Response Code

Response Description

Comment

0

Successful

1

Empty submission

No body in request

2

Invalid Request

Either the request body is not JSON, or the request body is malformed

3

Limit exceeded

A limit was exceeded in the request, e.g., number of IDs supplied

5

Unexpected property in value

A value for one of the properties in the request body was not of the expected type/format, e.g., a string was provided instead of a number

99

Unhandled Error

For scenarios that are not currently catered for by known status codes. These should be reviewed for standard inclusion

Did this answer your question?