Invitation

Create regulated user invitation

Creates an invitation for a new regulated user at the same regulated entity. The new regulated user will have access to the same regulated entity as the inviter.

Required entitlement: regulated.users.canInviteRegulatedUser
Entitles the regulated user to invite and onboard other regulated users within their organization

post/api-regulated/v1/invitations/regulated

Request

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

Query parameters

sendEmailboolean

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

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",
  "message": "Welcome to our sales team! Please complete your onboarding.",
  "entitlementsTemplateName": "Regulated 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.