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. |
<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 |