Skip to main content
POST
Register a client firm on your desk
The first call of every integration: register a client firm on your desk, an exporter who will sell credits or an importer who will buy them, the same call either way. Requires the firms scope. Returns 201 with the firm row in state registered. Registration never carries credentials; a credential-looking field here is rejected with a 422. Verification is the separate, deliberate next step: verify from your own UI under the firm’s mandate, then authorize. The onboarding experience is entirely yours to build.
Trading for a firm needs its connection state to be connected. Register, verify, authorize, then watch the state via GET /v1/firms/{iec} or the firm list.

Request example

iec, name and role are required; email is the firm’s contact on record. role is one of exporter or importer, exactly one side per firm: a firm that both sells credits and buys them cannot register as both yet. Register the side the firm will trade; dual-role firms are on the roadmap.
Registering a firm with role: "importer" requires the buy side to be active on your key. Write to amin@eximfiles.io to have it enabled.

Response example

Firm states

Errors

  • 409 conflict, the IEC is already registered on your desk.
  • 422 unprocessable, missing iec/name, role not exactly one of exporter/importer, or a credential-looking field in the body.
  • 403 forbidden, role: "importer" while the buy side is not active on your key.
Terms used here: IEC, connection state, API key, scope. Full list in the terminology annexure.

Next steps

Authorizations

X-ScripX-Key
string
header
required

Your API key, e.g. scripx_live_…. Bound to one firm; tenant isolation is enforced.

Body

application/json

Registration only; credential fields are rejected outright. Verification is the separate verify step.

iec
string
required

the firm's Importer-Exporter Code

name
string
required
role
enum<string>
required

one side per firm; dual-role firms are not supported yet

Available options:
exporter,
importer
email
string

Response

OK

created
boolean
firm
object