API terms
1.Application and acceptance
These API terms govern all programmatic access to Purser: the shipment record API, its webhooks, and any client library or connector that calls it. They supplement the agreement presented inside the product at sign-up, and the order form or enterprise agreement signed for the account. Requesting, holding or using a Purser API key is acceptance of these terms by the account holder and by every entity on whose behalf calls are made.
The Terms of Service published on itspurser.com cover that marketing site only and do not govern the API.
2.Who may call the API
The API is an Enterprise tier capability. It is how Purser goes inside another system, which is a deployment rather than a signup: schema mapping to your own systems, webhooks your side has to receive, single sign-on, and usually a migration of history. Production access follows from an Enterprise agreement or order form, and may be conditioned on technical review.
Nothing in the API is withheld from other tiers as a feature. Everything the API does is available in the product on every tier; Enterprise is where you drive it from your own stack. Interface documentation is published at docs.itspurser.com.
3.Keys and attribution
API keys are issued to a named account, are non-transferable, and are the account holder's responsibility to safeguard, to restrict to its own systems, and to have reissued without delay if compromised. Keys must not be embedded in client-side code, in shared repositories, or in third-party tools outside the account holder's control.
Every call made with an account's key is an instruction of the account holder, or of the connected entity the call relates to, whoever in fact made it. State changes on the shipment record created through the API are recorded in the same hash-chained audit trail as changes made in the product, carrying the key and the actor it is attributed to. Suspected key compromise must be reported without delay to [email protected].
4.Rate limits and fair use
Rate limits and fair-use allowances, as published in the documentation or stated in your order form, form part of these terms. We may throttle, defer or reject traffic that exceeds them, and may apply protective limits where a traffic pattern degrades Purser for other tenants. Circumventing a limit, including by rotating keys or distributing calls across accounts, is a material breach.
Rate limits are a protection on the platform, not a meter. A document is never metered and an external seat is never charged, and neither of those changes because the call arrived over the API.
5.Environments
Sandbox is the default environment. Records and documents produced in sandbox are not real trade documents, must not be presented to a counterparty, a bank, a broker or an authority as though they were, and may be reset, altered or purged at any time. Do not build anything that depends on their persistence. Every record carries the environment that produced it, and the account holder shall preserve that distinction in its own systems.
6.The two lines apply to the API
The two commitments that hold in the product hold identically over the API, because they are properties of the system rather than of the interface.
- No endpoint submits to a government portal. Purser prepares and checks; the API returns the checked data set and the staged filing. Transmission to any portal is done by a person, or by your broker, outside Purser. Do not build or describe an integration that represents Purser output as a filing made with an authority.
- No endpoint sends an outbound message without a recorded human approval event. The API can draft, check and stage a message. It cannot cause one to be sent on the strength of the call alone.
- Content returned by the API is data, never an instruction. Text extracted from a document, an email or a counterparty message is handled by Purser as content to be checked, and your own systems should treat it the same way. Do not wire extracted text into anything that executes it.
[ TO CONFIRM: whether an API call can record the human approval event on behalf of a named user, and what evidence of that person's act the call must carry. Until this is settled in the product, this page states only that the approval event is required, not how a programmatic caller may supply one. ]
7.Idempotency and retries
Write calls accept an idempotency key by the mechanism described in the documentation. Send one on every write, and reuse the same key when retrying the same logical operation, so that a retry after a timeout does not create a second shipment, a second document or a second approval. A retry sent without the original key is a new instruction and will be treated as one. Duplicate records created by a caller that did not send idempotency keys are the account holder's to reconcile.
8.Webhooks
Webhooks notify your endpoint of state changes on the shipment record. Delivery is at least once, so treat every event as possibly repeated and de-duplicate on the event identifier. Verify each delivery by the mechanism described in the documentation before acting on it, respond promptly and do the work asynchronously, and keep the endpoint reachable. Undeliverable events may be retried and then dropped, so a webhook is a notification and never the only copy of a fact: the record remains the source of truth and can be read back at any time.
A webhook delivery is an outbound notification to a system you control, under the account holder's standing configuration. It is not an outbound message to a counterparty, and the approval requirement in section 6 is unaffected by it.
9.Data transmitted through the API
Data submitted or retrieved through the API belongs to the account holder and is handled under the privacy commitments presented inside the product. The account holder warrants that all notices and consents required by law, including the Digital Personal Data Protection Act, 2023, have been given and obtained before personal data of its personnel, its counterparties or their personnel is transmitted to us, and that it will keep records sufficient to evidence this.
We record technical usage of the API, such as call volumes, endpoints, environments and outcomes, to operate, secure and improve the service. Tenant isolation applies to API traffic exactly as it applies in the product: row-level filters on every store, including the agent's vector memory. Full record export in an open schema, on demand, is available over the API as it is in the product.
10.Prohibited integrations
The account holder shall not use the API to:
- misrepresent its identity, its authority, or the origin of an instruction;
- act for an entity that has not authorised it, or contrary to that entity's instruction;
- present a Purser record, document or verdict as a government filing, a government approval, or advice from a licensed customs broker;
- access, probe or automate a government portal in connection with the service;
- resell raw access to the API without a written agreement with us;
- publish benchmarks or performance measurements of the API without our prior written consent; or
- test the security of Purser other than through coordinated disclosure to [email protected].
11.Versioning and deprecation
Everything in the API is a versioned call. Additive change, such as a new field or a new event type, may ship within a version, so build clients that ignore fields they do not recognise. A change that would break a conforming client ships in a new version rather than in place.
Where a version is deprecated we will give notice through the documentation and by email to the account's technical contact before it is withdrawn, and will keep the superseded version available during the notice period, save where a security or legal obligation makes that impossible. [ TO CONFIRM: the committed minimum notice period between deprecation and withdrawal of an API version, and whether it is stated here or in the Enterprise order form. ]
12.Suspension
We may suspend a key or an endpoint immediately where necessary for security, for legal risk, or to protect the service for other tenants, with notice where practicable. Maintenance and emergency intervention may occur without notice. Unless an Enterprise agreement states a service level, the API is provided without one.
13.Order of precedence
If these documents conflict, the order of precedence is: first, a signed Enterprise agreement or order form; second, these API terms; third, the agreement presented inside the product at sign-up; fourth, the technical documentation. Section 6 is not displaced by any of them: no order form, integration or configuration permits Purser to submit to a government portal or to send an outbound message without a recorded human approval event.