Add additional entities to a tracked vessel

Production

https://api.polestar-production.com

PUT

/purpletrac/v1/transaction/{id}/additional_entity

Add one or more additional entities to a vessel which has already been selected for tracking, so that they are screened alongside the vessel for the remainder of the tracking period.

This method requires the Additional Entity Ship Tracking feature to be enabled on the account, and the transaction must be in a tracking status - either ready to track ("R") or approved ("A").

Adding entities triggers an Additional Entity Added notification and re-runs the company watchlist check for the transaction, so any watchlist hits on the new entities will appear in the company watchlist check response and in the screening report.

A transaction may hold at most 10 active additional entities added during tracking. The cap is evaluated against the current count plus the number being added in this request, so it is not a per-request limit.

Refer to Managing Additional Entities to see how to use this endpoint in a vessel tracking workflow.

Request

Authorization

API Key

Add parameter in query

api_key

Example:

api_key: ********************

Path Params

Query Params

Body Params application/jsonRequired

Examples

Responses

🟢200OK

application/json

The entities were added, and are echoed back from your payload. None carries an id yet; read them back with the GET method.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found

🔴500Server Error

Request Example

Shell

JavaScript

Java

Swift

cURL

DefaultFree text entityMultiple entities

curl --location --request PUT 'https://api.polestar-production.com/purpletrac/v1/transaction//additional_entity?username=undefined&api_key=%3Capi-key%3E' \
--header 'Content-Type: application/json' \
--data '{
    "additional_entities": [
        {
            "name": "Hello Bank!",
            "relationship": "Financier",
            "type": "organisation",
            "obj_id": 1039902
        }
    ]
}'

Response Example

200 - Default

{
    "transaction_id": 123,
    "additional_entities": [
        {
            "name": "Hello Bank!",
            "relationship": "Financier",
            "type": "organisation",
            "obj_id": 1039902
        }
    ]
}

Modified at 2026-09-18 08:35:54

Remove additional entities from a tracked vessel

List the additional entities on a transaction