> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scripxhq.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Register a firm
> Register a client firm on your ScripX desk: the first step of the firm lifecycle, followed by API-driven verification and authorization from your own UI.
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](/api-reference/firms/verify) from your own UI under the firm's mandate, then [authorize](/api-reference/firms/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}`](/api-reference/firms/get) or the firm list.
### Request example
```bash theme={"dark"}
curl -X POST "https://api.scripxhq.com/v1/firms" \
-H "X-ScripX-Key: " \
-H "Content-Type: application/json" \
-d '{"iec": "0512345678", "name": "Acme Exports Pvt Ltd", "email": "ops@acmeexports.example", "role": "exporter"}'
```
`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](mailto:amin@eximfiles.io) to have it enabled.
### Response example
```json theme={"dark"}
{
"created": true,
"firm": {
"iec": "0512345678",
"name": "Acme Exports Pvt Ltd",
"email": "ops@acmeexports.example",
"role": "exporter",
"state": "registered",
"created_at": "2026-07-24T13:20:11+05:30"
}
}
```
### Firm states
| `state` | Meaning |
| ---------------------- | ------------------------------------------------------------------------------- |
| `registered` | On your desk; verification not yet run |
| `connecting` | Verification in progress |
| `verification_pending` | Awaiting the one-time [authorization code](/api-reference/firms/authorize) |
| `connected` | Ready; the firm can trade |
| `attention_needed` | The connection needs attention; run [verify](/api-reference/firms/verify) again |
| `reconnect_needed` | The connection lapsed; run [verify](/api-reference/firms/verify) again |
### 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](/annexure/terminology#iec), [connection state](/annexure/terminology#connection-state), [API key](/annexure/terminology#api-key), [scope](/annexure/terminology#scope). Full list in the [terminology annexure](/annexure/terminology).
### Next steps
* [Verify](/api-reference/firms/verify), then [authorize](/api-reference/firms/authorize).
* [List firms](/api-reference/firms/list), [get](/api-reference/firms/get), [update](/api-reference/firms/update), [delete](/api-reference/firms/delete).
## OpenAPI
````yaml POST /v1/firms
openapi: 3.1.0
info:
title: ScripX Partner API
version: 1.2.0
description: >-
Automate duty-credit-scrip trading: quote, order, positions, market,
webhooks. Auth: `X-ScripX-Key: scripx_live_…`. Money = integer paise; price
= bps of face.
contact:
name: ScripX API Support
email: amin@eximfiles.io
url: https://scripxhq.com
servers:
- url: https://api.scripxhq.com
description: >-
Production and sandbox share one host; a scripx_test_ key selects the
sandbox.
security:
- ApiKeyAuth: []
tags:
- name: Firms
description: >-
client-firm lifecycle: register, verify, authorize, credits, update,
offboard
- name: Trading
description: quote, orders, positions, market
- name: Group
description: intra-group netting + positions (enterprise/broker)
- name: Cross
description: 'broker cross-desk: block deals + intra-group transfers'
- name: Webhooks
description: event subscriptions + delivery
- name: Account
description: usage + metering
- name: Keys
description: self-serve scoped child keys (sub-accounts)
paths:
/v1/firms:
post:
tags:
- Firms
summary: Register a client firm on your desk
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FirmRequest'
responses:
'201':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FirmCreated'
'401':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- ApiKeyAuth: []
components:
schemas:
FirmRequest:
type: object
required:
- iec
- name
- role
properties:
iec:
type: string
description: the firm's Importer-Exporter Code
name:
type: string
email:
type: string
role:
type: string
enum:
- exporter
- importer
description: one side per firm; dual-role firms are not supported yet
description: >-
Registration only; credential fields are rejected outright. Verification
is the separate verify step.
FirmCreated:
type: object
properties:
created:
type: boolean
firm:
$ref: '#/components/schemas/Firm'
Error:
type: object
properties:
error:
type: string
code:
type: string
description: stable machine code
enum:
- bad_request
- unauthorized
- forbidden
- not_found
- conflict
- unprocessable
- rate_limited
- internal
message:
type: string
detail:
type: object
Firm:
type: object
properties:
iec:
type: string
name:
type: string
email:
type: string
role:
type: string
enum:
- exporter
- importer
state:
type: string
enum:
- registered
- connecting
- verification_pending
- connected
- attention_needed
- reconnect_needed
created_at:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-ScripX-Key
description: >-
Your API key, e.g. `scripx_live_…`. Bound to one firm; tenant isolation
is enforced.
````