Testing the PurpleTRAC API

Two ways to exercise these endpoints from this documentation: against a mock server, or against production with your own credentials.

There is no separate customer test environment. Calls with real credentials go to production, so build against the mock until you are confident in what you are sending.

Mock server

Every endpoint has a mock available from its reference page, and it needs no credentials. Responses are generated from the spec, so they carry the right fields, types and structure without touching production.

Use it to:

Check a response shape before you write a parser

Build and demo a client while onboarding is still in progress

Reproduce an integration bug without creating real transactions

Develop against addons your account does not have enabled

Mock data is shaped like real data, not drawn from it

A mock returns a plausible vessel with plausible screening results. The schema generates it. Use it to validate structure and integration logic, never to judge a specific vessel or the quality of a check.

Try it, with your own credentials

Endpoint pages have a Try it button that sends a real request from your browser.

Have both values ready

PurpleTRAC needs a username and an api_key, issued by your Pole Star representative. See Authentication.

Enter them on the endpoint page

Both are query parameters, so they appear as fields on the request. Enter them on each endpoint you try.

Send the request

The call goes to production under your own credentials, with your own account configuration.

Reads first

Try it sends genuine requests. A GET is harmless. POST /registration creates a real transaction and PUT /transaction/{id}/track starts real tracking, both of which consume screening volume. Use the mock for anything that writes until you mean it.

Choosing between them

	Mock	Try it
Needs credentials	No	Yes
Data	Generated from the spec	Real
Hits production	No	Yes
Creates transactions	No	Yes
Good for	Shape, structure, integration logic	Confirming real behaviour and what your account reaches
Not good for	Judging a check result	Exploratory calls that write

Work through the mock first, then confirm against production with a read.

Using a REST client

If you would rather work outside this documentation, export the endpoints to your own client. Each endpoint page offers generated code in several languages, and the reference can be exported as a collection you import into Postman, Insomnia or similar.

Once imported, store your credentials as collection variables rather than repeating them on every request. username and api_key are needed on every call, so two variables cover the whole collection.

Import the collection

Use your client's import option and point it at the exported file.

Set the variables

Open the collection settings and fill in username and api_key. Every request in the collection then carries them.

Point at the right server

Production is https://api.polestar-production.com/purpletrac/v1. Only production exists at this host. Confirm the collection points to https://api.polestar-production.com/purpletrac/v1 before you read anything into a response.

Before you go live

Confirm which addons you have

Carbon Rating, BL Verification and Container Screening are enabled per account. Call one endpoint from each and check you do not get a 403.

Handle the error shapes you have not seen

PurpleTRAC returns several, and some are not JSON. Branch on the status code first. See Errors & Status Codes.

Store every transaction id

Almost every follow-up call needs one, and rescreening keeps the original. Losing an id means starting a vessel again.

Decide your tracking lifecycle

Tracking runs until you stop it or until the configured conditions end it. Work out which vessels should stop, and when, before you enable it in volume.

Getting help

Talk to our team. Include the endpoint, the transaction id and the full response body, since PurpleTRAC error bodies vary and the body is often the only detail available.

Testing PurpleTRAC

Mock server#

Try it, with your own credentials#

Choosing between them#

Using a REST client#

Before you go live#