Additional entities on a tracked vessel

Additional entities are the companies and people screened alongside a vessel: a financier, a charterer, a broker. You normally supply them when the vessel is first submitted for screening, as Screening Vessels describes.

Counterparties change mid-voyage. Someone new joins the deal, or a party who mattered at fixture no longer does. You can list, add to and remove the additional entities on a tracked vessel while the track continues, so the transaction and its screening history stay intact.

This is an addon feature

The calls on this page need Additional Entity Ship Tracking enabled on your account. Without it every method returns 403. Your Pole Star representative can switch it on.

All three methods share one endpoint, a sub-resource of an existing transaction.

Method	Purpose
`GET /transaction/{id}/additional_entity`	List the additional entities currently tracked on a transaction
`PUT /transaction/{id}/additional_entity`	Add one or more additional entities to a tracked vessel
`DELETE /transaction/{id}/additional_entity`	Remove one or more additional entities from a tracked vessel

The {id} path parameter is the transaction id of the vessel, the same id used throughout the tracking workflow, and the transaction has to belong to the authenticated user.

This endpoint breaks the list convention

The GET method returns the entities directly in an additional_entities array. There is no meta and objects envelope here, and no filtering or ordering parameters.

Before you start

Two conditions apply to PUT and DELETE.

Tracking status. The transaction has to be tracking, meaning Ready to Track ("status": "R") or Approved ("status": "A"). Tracking a Vessel shows how to check. Any other status gets you a 400 with "Transaction must be in tracking or ready-to-track status."

Entity cap. A transaction holds at most 10 active additional entities added during tracking. The cap counts the total, so adding 3 entities to a transaction that already holds 9 fails.

The GET method has neither restriction and works at any transaction status.

List the current entities

Start here. The response carries the entity ids you need to remove anything later.

{
  "additional_entities": [
    {
      "id": 4521,
      "name": "Hello Bank!",
      "relationship": "Financier",
      "type": "organisation",
      "obj_id": 1039902,
      "not": []
    }
  ]
}

Three of those fields need explaining.

id is the additional entity record id, and the value you supply in the DELETE body. It is a different thing from obj_id.

obj_id is the internal id of the company or person record the entity resolved to, if any. GET /additional_entity_search returns it.

not carries registration-time disambiguation entries. For entities added during tracking it is always empty.

Removed entities are left out of this response. Removal is a soft delete, so they stay visible in screening reports generated while they were active.

Add entities

Search for the entity by name first, with GET /additional_entity_search, and pass the resulting obj_id in your request. That screens the entity you meant and gives PurpleTRAC an identity to check duplicates against. Screening Vessels covers the search in detail.

You can add an entity with no obj_id, in which case the name has to match exactly for watchlist hits to come back.

Only name is mandatory, up to 255 characters. relationship is freeform text up to 20 characters, shown next to the entity name in the screening report and in the GET /companysanction response. type restricts the entity to an organisation or a person, and omitting it considers both.

Validation rules

We reject the whole request, adding nothing, if any of these apply.

The additional_entities array is missing or empty.

The transaction is not tracking.

The request would take the transaction past 10 active entities added during tracking.

Two entities in the request share an obj_id and type combination. Entities with no obj_id are never treated as duplicates, since a freeform entry has no identity to compare.

An entity in the request matches the obj_id and type of one already active on the transaction.

The response

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

The response echoes your request

These entities come straight back from the payload you sent, so none of them carries an id. Call the GET method afterwards for the record ids of what you just added.

What happens next

Adding entities has two effects on the tracked vessel.

An Additional Entity Added (ADDITIONAL_ENTITY_ADDED) notification is raised. Tracking Notifications has the full set.

We also re-run the company watchlist check for the transaction. Hits on the new entities appear in the GET /companysanction response with "ship_relationship": "ADDITIONAL_ENTITY", and in screening reports generated from then on. Poll GET /notification for an Associated Company on Global Sanction List (COMPANY_SANCTION_ADDED) notification, raised when a new entity turns up on a watchlist.

Remove entities

Removing an entity excludes it from further screening. Send the record ids returned by the GET method.

Validation rules

At least one id is required.

The transaction has to be tracking.

Every id has to resolve to an entity currently active on this transaction. One unresolvable id rejects the whole request, so nothing is removed and there is no partial state to reconcile.

The response

{
  "transaction_id": 123,
  "removed": [
    {
      "id": 4521,
      "name": "Hello Bank!"
    }
  ]
}

What happens next

Removal is a soft delete. We keep the entity record against the transaction and it stays visible in screening reports generated while it was active, but it is excluded from all future screening and drops out of the GET response.

An Additional Entity Removed (ADDITIONAL_ENTITY_REMOVED) notification is raised, and any outstanding Associated Company on Global Sanction List (COMPANY_SANCTION_ADDED) notifications standing against the removed entities are cleared. The slot is freed against the cap of 10, so a removed entity does not consume capacity for the rest of the track.

Error responses

Status	Cause
`400`	Validation failure on `PUT` or `DELETE`, or the transaction id could not be found for the authenticated user
`401`	Missing or wrong `username` and `api_key` pair. The body is empty
`403`	Additional Entity Ship Tracking is not enabled for your account
`404`	`GET` only. The transaction does not exist, or does not belong to the authenticated user
`500`	System failure

One condition, two status codes

A transaction that cannot be found returns 404 with a NOT_FOUND error code on GET, and 400 with a NOT_VALID code and a {"transaction": "can not find transaction"} entry in error_info.errors on PUT and DELETE. Handle both.

Errors and Status Codes has every message this endpoint returns, with its body shape.

Tracking a Vessel

Enable a track and get the transaction into a status these calls accept.

Watchlist Checks

Where hits on your added entities show up.

Errors and Status Codes

Every rejection message for this endpoint, in full.

Managing Additional Entities

Before you start#

List the current entities#

Add entities#

Validation rules#

The response#

What happens next#

Remove entities#

Validation rules#

The response#

What happens next#

Error responses#

Related#

Before you start

List the current entities

Add entities

Validation rules

The response

What happens next

Remove entities

Validation rules

The response

What happens next

Error responses

Related