---
title: "Create customer invitation"
method: POST
path: "/api-regulated/v1/invitations/customers"
tags: ["Invitation"]
---

# Create customer invitation

`POST /api-regulated/v1/invitations/customers`

## Request

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

Creates an invitation for a new customer user at one of the companies managed by this regulated user.

**Required entitlement:** `regulated.customers.canInviteCustomer`  
_Entitles the regulated user to invite and onboard customer users_

## Request body

- CreateCustomerInvitationBySalesUserDTO: Request to create a customer user invitation
  - `email` string, required: Email address of the person being invited
  - `firstName` string, required: First name of the person being invited
  - `lastName` string, required: Last name of the person being invited
  - `companyId` string, uuid, required: The company ID the customer user will belong to
  - `message` string: Optional welcome message for the invitation
  - `entitlementsTemplateName` string: Entitlements template name to assign to the invited user

## Response `201`

Invitation created

- InvitationDTO: Schema for representing a Invitation
  - `id` string, uuid: The ID for this invitation.
  - `inviterUserId` string, uuid: The ID of the user who sent this invitation.
  - `inviterUserPiiData` InvitationDTOInviterUserPiiData: **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.
  - `inviteeUserId` string, uuid: The ID of the user created for this invitation (email stored in PII). Null for new invitations until acceptance.
  - `inviteeUserPiiData` InvitationDTOInviteeUserPiiData: **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.
  - `entitlementsTemplateId` string, uuid: The entitlements template ID to assign to the invited user.
  - `entitlementsTemplateTemplateName` string: The unique name of the entitlements template.
  - `regulatedEntityId` string, uuid: The regulated entity ID (for sales users and customers).
  - `companyId` string, uuid: The company ID (for customer users only).
  - `invitationToken` string: The unique invitation token for validation.
  - `status` 'PENDING' | 'COMPLETED' | 'EXPIRED' | 'REVOKED': The current status of the invitation.
  - `expiresAt` string: When the invitation expires in UTC.
  - `completedAt` string: When the invitation was completed in UTC.
  - `piiData` InvitationDTOPiiData: **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.
  - `perimeterId` string, uuid: The tenant perimeter whose KMS key encrypts this record's PII.
  - `introducingBrokerId` string, uuid: The introducing broker ID (for sales user invitations).
  - `createdUserId` string, uuid: DEPRECATED: Use invitee_user_id instead. The ID of the user created after successful onboarding.
  - `versionNumber` integer: The strictly monotonically increasing version number for this record.
  - `updatedBy` string: The username of the person or entity that updated this record.
  - `updatedAt` string: The timestamp of the last update in UTC.
  - `createdAt` string: The timestamp of creation in UTC.

## Other responses

- `400`: Invalid request data — [`http/malformed-request`](/problems/http/malformed-request/)
- `401`: Not authenticated — [`security/authentication-failed`](/problems/security/authentication-failed/)
- `403`: Not authorized - company not managed by this regulated user — [`security/insufficient-permissions`](/problems/security/insufficient-permissions/)
- `409`: User already exists or invitation pending — [`http/resource-conflict`](/problems/http/resource-conflict/)
- `500`: Server error — [`server/internal-error`](/problems/server/internal-error/)

---

[API](https://skmtc.dev/currencyguard/apis/currencyguard-trading-system-api-external.md) · [All operations](https://skmtc.dev/currencyguard/apis/currencyguard-trading-system-api-external/llms.txt) · [OpenAPI document](https://skmtc.dev/currencyguard/apis/currencyguard-trading-system-api-external/revisions/a1f3f854190d?raw)