Skip to main content
POST
Validate DGFT credentials
Validate the exporter’s DGFT portal credentials and store the connection. This is the second and required half of onboarding: a client created by Create Customer is inactive and cannot file until this call succeeds. Call it again whenever the exporter’s DGFT password changes. Re-submitting the same username with a new password updates the stored password. Submitting a different username is rejected.
This endpoint performs a real login against the DGFT portal, so it is synchronous and can take several seconds. It is limited to 4 calls per minute. Five failed checks in fifteen minutes are refused for another fifteen minutes. Services are enabled after 24 hours of successful validation.

What success changes

On a successful validation the client’s isActive becomes true immediately, the DGFT connection is stored against the client, and hasDgftCredentials becomes true. Nothing else on the client is modified. This is the same operation the eBRC console runs when a platform user submits or rotates a client’s DGFT credentials, so a client onboarded either way reaches the same state.

Request example

Both fields are required. Credentials are encrypted at rest, redacted from logs, and never shown back by any endpoint.
Submitting an exporter’s DGFT credentials is what grants the mandate to act on their behalf, and the submission is recorded as consent evidence. Only submit credentials the exporter has authorised you to hold. See the API Terms.

Response example

Returns 201 with the client in the data field. isActive and hasDgftCredentials are now both true.
The stored DGFT password is never present in any response. See the client object for every field.
Read dgftApiStatus before the first refresh. If the exporter already held DGFT API credentials, the response carries "state": "activation_pending" with an activatesAt timestamp: DGFT enables our IP on that account after 24 hours, and IRM refreshes until then answer 409 DGFT_IP_ACTIVATION_PENDING. Nothing is wrong and nothing needs re-submitting. See the 24-hour activation.

Errors

  • 400 Invalid DGFT credentials when the DGFT portal rejects the username and password. The client stays inactive.
  • 400 DGFT credentials are already set for this customer when you send a username different from the one already stored. Password rotation is supported, changing the username is not.
  • 400 DGFT username already in use when that username is already linked to another of your clients in this mode.
  • 400 DGFT username already aligned with another platform customer when the DGFT account is already connected to a different client of yours in this mode.
  • 400 Validation failed when dgftUsername or dgftPassword is missing or empty.
  • 401 No API key provided or Invalid API key. See authentication errors.
  • 404 Platform customer not found when no client with that id exists under your account in the mode your key selects. A dev_ key cannot reach a live client.
  • 429 when you exceed 4 calls per minute. See rate limits.
  • 500 Error checking DGFT credentials when the portal check could not be completed. Retry after a short delay.
Filings and downloads made later with a stale password return DGFT_CREDENTIALS_INVALID. Recover by calling this endpoint again with the new password. See DGFT credential error codes.

Next steps

Authorizations

x-api-key
string
header
required

Path Parameters

id
string
required

The customer ID

Body

application/json
dgftUsername
string
required

DGFT portal username

dgftPassword
string<password>
required

DGFT portal password

Response

Credentials validated, client is now active

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).