Skip to main content
POST
Create a platform customer
Create a platform customer for each exporter you generate certificates for. This is the first call in the lifecycle: the returned id is the platformCustomerId you pass to every IRM and generation endpoint.

Onboarding is two calls, not one

A client you have only created cannot file. Creation always returns isActive: false, whatever you send in the body. The client becomes active only when its DGFT credentials are verified against the DGFT portal by Validate Customer.
1

Create the client

POST /platform-customers stores the exporter’s profile and returns its id. The client is inactive and has no DGFT connection.
2

Validate the DGFT credentials

POST /platform-customers/{id}/check-dgft-credentials performs a real login against the DGFT portal. On success the DGFT connection is stored and isActive flips to true.
Passing dgftUsername and dgftPassword to this endpoint stores them but does not verify them, does not create the DGFT connection, and does not activate the client. You must still call Validate Customer. The eBRC console behaves the same way: it collects the credentials on the onboarding form and verifies them in a second step.

Request example

Request fields

Any other property is rejected with 400, with one exception: id, platformId, isActive, createdAt and updatedAt are still accepted for backward compatibility and silently ignored. Do not send them. In particular, isActive: true in the body does nothing.

About the IEC

The Importer Exporter Code is the 10 character identifier DGFT issues to every Indian exporter. It is the number DGFT itself keys an exporter’s remittances and certificates on, so recording it against the client makes reconciliation between your records, ours and DGFT’s unambiguous. The API accepts iec in any case, trims surrounding whitespace and stores it uppercase. The format is validated: exactly 10 letters and digits, no spaces or punctuation. It is optional here so existing integrations keep working, and required in the eBRC console. Send it anyway. A client with no IEC on file is materially harder to support when a filing is queried.

Response example

Returns 201 with the client in the data field of the standard envelope:
Optional fields you did not send are absent from the create response rather than null. Read them back with Get Customer by Id, where an unset field comes back as null.

The client object

Every endpoint in this section returns this object. The stored DGFT password is encrypted at rest and is never returned on any surface.
Your API key prefix decides the mode: a dev_ key creates test clients, a prod_ key creates live clients, and mode headers are ignored when a key is present. The same email can therefore exist twice under your account, once in test and once in live. Those are two different clients with two different ids. See Environments.

Errors

  • 400 Validation failed with errors: ["email: email must be an email"] when the email fails format validation.
  • 400 Validation failed with errors: ["iec: iec must be exactly 10 alphanumeric characters (Importer Exporter Code)"] when the IEC is not 10 letters and digits.
  • 400 Validation failed with errors: ["<field>: property <field> should not exist"] for any property outside the table above.
  • 400 User with email already exists when that email is already on your account in this mode. The same email in the other mode, or under another platform, is not a conflict.
  • 400 DGFT username already in use when the dgftUsername you sent is already linked to another of your clients in this mode.
  • 401 No API key provided, or Invalid API key when the key is unknown or revoked. See authentication errors.
  • 403 Only platform users can access this resource, or Master Platform Agreement not signed yet. Both dev_ and prod_ keys require a signed agreement before issuance.
See common validation errors for the full error body shape.

Next steps

Authorizations

x-api-key
string
header
required

Body

application/json
name
string
required
email
string<email>
required

Unique per platform account, per mode.

type
enum<string>
default:customer
required
Available options:
customer
companyName
string

The exporter's registered legal name. Optional here, required by the eBRC console.

iec
string

Importer Exporter Code: exactly 10 alphanumeric characters, accepted in any case and stored uppercase. Optional here, required by the eBRC console.

Required string length: 10
Pattern: ^[A-Za-z0-9]{10}$
address
string

Free text. Not collected by the eBRC console.

dgftUsername
string

Optional. Stored WITHOUT verification and unique per platform account, per mode. You must still call check-dgft-credentials.

dgftPassword
string<password>

Optional. Stored WITHOUT verification, encrypted at rest, never returned.

Response

Client created, inactive until DGFT credentials are validated

id
string

Unique identifier of the platform customer. This is the platformCustomerId used in every later call.

name
string
email
string<email>
type
enum<string>
default:customer
Available options:
customer
companyName
string | null

The exporter's registered legal name. Required by the eBRC console, optional on this API.

iec
string | null

Importer Exporter Code: exactly 10 alphanumeric characters, stored uppercase. Required by the eBRC console, optional on this API.

Required string length: 10
Pattern: ^[A-Za-z0-9]{10}$
address
string | null

Free text. Not collected by the eBRC console, so console-onboarded clients have none.

platformId
string

Platform account that owns this client

mode
enum<string>

Fixed at creation from the API key prefix and never editable. Returned by create, update and validate; omitted by the list and get endpoints.

Available options:
test,
live
isActive
boolean

Always false at creation. Becomes true only when DGFT credentials are verified by POST /platform-customers/{id}/check-dgft-credentials.

hasDgftCredentials
boolean

Derived: true once DGFT credentials are on file. Branch on this; the raw DGFT credential fields are not part of the response contract and the password is never returned on any surface.

createdAt
string<date-time>
updatedAt
string<date-time>

Not returned by GET /platform-customers (list).