Integrations · For developers
The SCMTR.io Connect API: jobs in, filings and events out
Updated
SCMTR.io works beside the software you already run, and this is what your developers build against: send a job and get a draft CSN back, read each filing’s state, CSN number and CINs, and read events as they happen. What goes in and what comes out is all there is to know — a person still checks, signs and sends every filing on SCMTR.io.
Send jobs in — POST /api/v1/shipments
Takes jobs as JSON; gives back a draft CSN for each.
- Takes: up to 50 jobs in one request, each one master bill with your own job number, its vessel call, its house bills and their containers
- Gives: for each job, whether a draft was made, already existed or was refused — with the reason in words — the draft’s link, and the notes made on any value that was changed or could not be read
- The same job number sent again makes nothing new: the answer is the filing it already made, and says whether what you sent now differs
- Import CSNs; a field name SCMTR.io does not know is said back, never dropped
Send a spreadsheet in — POST /api/v1/batches
Takes the sheet your system already exports; gives back the same answer, bill by bill.
- Takes: an .xlsx or .csv file as exported, and the name of the import profile to read it under
- Gives: each master bill’s draft, and the rows no draft took, with the reason for each
- With no profile named, your organisation’s default is used
- Where the profile names your job-number column, a sheet sent again makes each filing once
Read filings — GET /api/v1/filings
Takes your job number, or a time; gives each filing’s state and numbers.
- Takes: your own job number, “changed since”, a state, or nothing for the newest first
- Gives: each filing’s state, its CSN number and date, the MCIN or PCIN, its bills once sent, and its page on SCMTR.io
- Nothing of a filing’s contents is returned
Read events — GET /api/v1/events, or signed webhooks
Takes the last event you have; gives what happened since.
- Takes: the number of the last event you read
- Gives: the events since, oldest first, each with its kind, its time and what it is about — a draft made, a CSN sent, customs’ reply recorded among them — a short settling time after each happens, and the place to ask from next time
- The same events are pushed as signed webhooks to an address of yours, if your system can receive them
- Each event is kept on the feed for 30 days
Keys and permissions
An Org Admin makes each key under Settings → API and gives it only what it needs.
- filings:write — send jobs and spreadsheets in
- filings:read — read your filings’ state and numbers
- events:read — read the event feed
- A key is shown once when it is made, and can be ended at any time
The API description
Published for your developers and for the makers of your software.
- The API description (OpenAPI) at /api/v1/openapi.json, with every call above
- Public: it needs no key to read, and an API client or a code generator takes it as it is
- It says what each call takes and gives, and nothing else
What the API does not do
- It files nothing with customs: signing and sending stay with a person on SCMTR.io, with their own DSC
- It returns nothing of another organisation’s filings
- It does not say what a draft still needs: it answers whether each job made a draft and what was noticed while reading it, and the person who opens the draft sees the rest
Questions developers ask first
Read next
Does the API file with customs?
No. Every job arrives as a draft: a person checks it, signs it with their own DSC and sends it to ICEGATE. Nothing is sent to customs without a person. The API brings jobs in as drafts and gives numbers and events back.
Is it safe to send the same job twice?
Yes. A job sent again under the same job number makes nothing new: the answer is the filing it already made, with a flag saying whether what you sent now differs. A filing is never overwritten.
Our system cannot receive webhooks. What then?
Read the event feed instead: ask for the events after the last one you have, on your own schedule. It carries the same events, kept for 30 days.
How do we get a key?
An Org Admin makes it under Settings → API, choosing its permissions. Every organisation has the API; nothing has to be switched on.
Is there an API description we can generate a client from?
Yes: an OpenAPI description at /api/v1/openapi.json. It is public and needs no key to read.
What does it cost?
Nothing. Connect is free on every plan, like the API. The API keys, the webhooks, the event feed, the import profiles and the write-back sheet are all part of it.
Build against inputs and outputs
Filing is free — every filing feature, no caps, no card. Connect is free on every plan, like the API.