Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
POST /v1/firm-control/users/invitations — invite a trader to your firm.
POST /v1/firm-control/users/invitations
operationId: inviteFirmUser
Creates or activates a firm relationship and sends an invitation email for a trader or staff user.
For purely API-driven trader onboarding (no email step), use Generate account.
| Header | Notes |
|---|---|
X-Firm-ID | Firm UUID. Auto-injected for firm API keys. |
X-Firm-Entity-Slug | Optional RBAC entity slug. |
| Field | Required | Notes |
|---|---|---|
email | yes | Invitee email. |
firm_id | no | Required for multi-firm JWT sessions when X-Firm-ID is absent. |
relationship_type | no | TRADER or STAFF. Defaults to TRADER. |
role_name | no | RBAC role to assign on acceptance (typically for STAFF). |
curl -X POST "$TRADARA_BASE_URL/v1/firm-control/users/invitations" \
-H "X-Tradara-Api-Key: $TRADARA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"relationship_type": "TRADER"
}'
201 Created{
"relationship": {
"id": "rel_01HW...",
"firm_id": "8f4a1d6e-2b1c-4e9a-9d3b-5e6c7a0d1f23",
"user_id": "8e9ad12c-2b1c-4e9a-9d3b-5e6c7a0d1f23",
"relationship_type": "TRADER",
"status": "INVITED",
"invited_email": "[email protected]",
"invitation_token_hash": "…",
"invitation_expires_at": "2026-07-03T00:00:00Z",
"created_at": "2026-06-26T16:00:00Z",
"updated_at": "2026-06-26T16:00:00Z"
},
"user_id": "8e9ad12c-2b1c-4e9a-9d3b-5e6c7a0d1f23",
"email": "[email protected]",
"user_created": true,
"relationship_status": "INVITED",
"entitlement_granted": false,
"activated": false
}
| HTTP | Meaning |
|---|---|
400 | Missing email or invalid relationship_type. |
403 | Caller not permitted to invite into this firm. |
409 | Active relationship already exists for this email. |
502 / 503 | Downstream identity/relationship service unavailable. |