Manage a trader relationship

Use these endpoints to control whether a trader has an active relationship with your firm. Your API key needs the users:write scope. Suspending or revoking a relationship emits a lifecycle event that revokes the trader’s firm-scoped market data entitlements. Entitlement changes are asynchronous and normally take effect shortly after the relationship update succeeds.

Action	Result
Suspend	Changes `ACTIVE` to `SUSPENDED`. You can restore the relationship later.
Restore	Changes `SUSPENDED` to `ACTIVE`. Eligible firm-scoped market data is granted again.
Revoke	Changes the relationship to `REVOKED`. This is permanent. Invite the trader again to create a new relationship.

Request body

All three endpoints accept the same body.

Field	Required	Notes
`user_id`	yes	UUID of the trader.
`firm_id`	no	Firm UUID. Omit when the gateway supplies `X-Firm-ID`, including firm API key requests.
`reason`	no	Audit note with a maximum length of 500 characters.

Suspend a trader

POST /v1/firm-control/traders/suspend

operationId: suspendTraderRelationship

curl -X POST "$TRADARA_BASE_URL/v1/firm-control/traders/suspend" \
  -H "X-Tradara-Api-Key: $TRADARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "8e9ad12c-2b1c-4e9a-9d3b-5e6c7a0d1f23",
    "reason": "Trader is no longer active"
  }'

Calling this endpoint for an already suspended relationship is idempotent.

Restore a trader

POST /v1/firm-control/traders/restore

operationId: restoreTraderRelationship

curl -X POST "$TRADARA_BASE_URL/v1/firm-control/traders/restore" \
  -H "X-Tradara-Api-Key: $TRADARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "8e9ad12c-2b1c-4e9a-9d3b-5e6c7a0d1f23",
    "reason": "Trader access approved"
  }'

Only a suspended relationship can be restored. A revoked relationship cannot be restored.

Revoke a trader

POST /v1/firm-control/traders/revoke

operationId: revokeTraderRelationship

curl -X POST "$TRADARA_BASE_URL/v1/firm-control/traders/revoke" \
  -H "X-Tradara-Api-Key: $TRADARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "8e9ad12c-2b1c-4e9a-9d3b-5e6c7a0d1f23",
    "reason": "Trader offboarded"
  }'

Revocation is permanent for the relationship. Use suspension when you may restore the trader later.

Response

Each endpoint returns the updated relationship.

{
  "id": "7d7d4ec8-9f56-4d33-93e8-2c4cfa617f27",
  "firm_id": "7b8a77ca-fdb3-4bd8-a31a-e527fb784cf8",
  "user_id": "8e9ad12c-2b1c-4e9a-9d3b-5e6c7a0d1f23",
  "relationship_type": "TRADER",
  "status": "SUSPENDED",
  "created_at": "2026-06-01T14:12:00Z",
  "updated_at": "2026-08-21T16:45:00Z"
}

Errors

Status	Meaning
`400`	The request, firm scope, user UUID, or reason is invalid.
`403`	The API key or staff member lacks `users:write`.
`404`	The user has no trader relationship with the active firm.
`409`	The requested transition is not valid from the relationship’s current status.
`502`	The identity service could not complete the transition.

Use Relationships to check the current status. Subscribe to relationship events to observe lifecycle changes.

Overview

Account Provisioning

Terminal Embed

Firm & Users

Staff & RBAC

Offerings & Acceptance

API Keys

Webhooks

Realtime WebSocket

Operations

Firm Backoffice Reads

Terminal Onboarding (JWT)

Manage a trader relationship

Request body

Suspend a trader

Restore a trader

Revoke a trader

Response

Errors

​Request body

​Suspend a trader

​Restore a trader

​Revoke a trader

​Response

​Errors

Request body

Suspend a trader

Restore a trader

Revoke a trader

Response

Errors