Invitation

Create sales user invitation

Creates an invitation for a new sales user at an introducing broker within the regulated user's regulated entity.

Required entitlement: regulated.sales-users.canInviteSalesUser
Entitles the regulated user to invite and onboard sales users within their regulated entity

post/api-regulated/v1/invitations/sales

Request

  • Base URL: https://api.currencyguard.com
  • URL: https://api.currencyguard.com/api-regulated/v1/invitations/sales
  • Auth: OAuth 2 (implicit, authorization URL https://auth.currencyguard.com/oauth2/authorize, scopes: regulated.sales-users.canInviteSalesUser)

Request body

emailstring required

Email address of the person being invited

firstNamestring required

First name of the person being invited

lastNamestring required

Last name of the person being invited

introducingBrokerIdstring uuid required

The introducing broker ID the sales user will belong to

messagestring

Optional welcome message for the invitation

entitlementsTemplateNamestring

Entitlements template name to assign to the invited user

Example request

{
  "email": "jane.doe@salesteam.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "introducingBrokerId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Welcome to our sales team! Please complete your onboarding.",
  "entitlementsTemplateName": "Sales User"
}

Response

Invitation created

idstring uuid

The ID for this invitation.

inviterUserIdstring uuid

The ID of the user who sent this invitation.

inviterUserPiiDataInvitationDTOInviterUserPiiData

Extensible JSONB field - The PII data for this user as encrypted JSON. This field accepts any valid JSON structure and can be extended with additional properties as needed. Note: While the structure is extensible, known fields shown in the example are subject to application validation.

inviteeUserIdstring uuid

The ID of the user created for this invitation (email stored in PII). Null for new invitations until acceptance.

inviteeUserPiiDataInvitationDTOInviteeUserPiiData

Extensible JSONB field - The PII data for this user as encrypted JSON. This field accepts any valid JSON structure and can be extended with additional properties as needed. Note: While the structure is extensible, known fields shown in the example are subject to application validation.

userType'INTERNAL' | 'REGULATED' | 'CUSTOMER'

The type of user being invited.

entitlementsTemplateIdstring uuid

The entitlements template ID to assign to the invited user.

entitlementsTemplateTemplateNamestring

The unique name of the entitlements template.

regulatedEntityIdstring uuid

The regulated entity ID (for sales users and customers).

companyIdstring uuid

The company ID (for customer users only).

invitationTokenstring

The unique invitation token for validation.

status'PENDING' | 'COMPLETED' | 'EXPIRED' | 'REVOKED'

The current status of the invitation.

expiresAtstring

When the invitation expires in UTC.

completedAtstring

When the invitation was completed in UTC.

piiDataInvitationDTOPiiData

Extensible JSONB field - Encrypted PII data for the invitee (email, first_name, last_name). Stored on invitation so user creation is deferred to acceptance. This field accepts any valid JSON structure and can be extended with additional properties as needed. Note: While the structure is extensible, known fields shown in the example are subject to application validation.

perimeterIdstring uuid

The tenant perimeter whose KMS key encrypts this record's PII.

introducingBrokerIdstring uuid

The introducing broker ID (for sales user invitations).

createdUserIdstring uuid

DEPRECATED: Use invitee_user_id instead. The ID of the user created after successful onboarding.

versionNumberinteger

The strictly monotonically increasing version number for this record.

updatedBystring

The username of the person or entity that updated this record.

updatedAtstring

The timestamp of the last update in UTC.

createdAtstring

The timestamp of creation in UTC.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "inviterUserId": "550e8400-e29b-41d4-a716-446655440001",
  "inviterUserPiiData": {
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+44 20 7946 0958",
    "jobTitle": "Risk Manager",
    "department": "Trading"
  },
  "inviteeUserId": "550e8400-e29b-41d4-a716-446655440005",
  "inviteeUserPiiData": {
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+44 20 7946 0958",
    "jobTitle": "Risk Manager",
    "department": "Trading"
  },
  "userType": "REGULATED",
  "entitlementsTemplateId": "550e8400-e29b-41d4-a716-446655440001",
  "entitlementsTemplateTemplateName": "Super User",
  "regulatedEntityId": "550e8400-e29b-41d4-a716-446655440002",
  "companyId": "550e8400-e29b-41d4-a716-446655440003",
  "invitationToken": "eyJhbGciOiJIUzI1NiJ9...",
  "status": "PENDING",
  "expiresAt": "2024-10-25T12:30:40Z",
  "completedAt": "2024-10-20T14:15:30Z",
  "piiData": {
    "status": "ENCRYPTED",
    "value": "...",
    "key": "arn:aws:kms:..."
  },
  "perimeterId": "cccccccc-cc11-4001-8000-000000000000",
  "introducingBrokerId": "550e8400-e29b-41d4-a716-446655440006",
  "createdUserId": "550e8400-e29b-41d4-a716-446655440004",
  "versionNumber": 1,
  "updatedBy": "jbloggs24",
  "updatedAt": "2024-10-18T12:30:40Z",
  "createdAt": "2024-10-18T12:30:40Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.