Installation
Quick Start
Generate a secure token for Vortex componentsIntegration Flow
Vortex uses a split architecture: your backend signs tokens with the SDK, and your frontend renders components that use those tokens to securely interact with Vortex.Generate a token for the current user
When a user loads a page with a Vortex component, generate a signed token on your server
Methods
Core Methods
GenerateToken()
Generate a signed token for use with Vortex widgets
| Name | Type | Required | Description |
|---|---|---|---|
payload | GenerateTokenPayload | ✓ | Data to sign (user, component, scope, vars, etc.) |
options | GenerateTokenOptions? | Optional configuration (ExpiresIn) |
string — Signed JWT token string
GetInvitationAsync()
Get a specific invitation by ID
| Name | Type | Required | Description |
|---|---|---|---|
invitationId | string | ✓ | The invitation ID |
Task<Invitation> — The invitation details
AcceptInvitationAsync()
Accept a single invitation (recommended method)
| Name | Type | Required | Description |
|---|---|---|---|
invitationId | string | ✓ | Single invitation ID to accept |
user | AcceptUser | ✓ | User with email or phone (and optional name) |
Task<Invitation> — Invitation result
Additional Methods
Additional Methods
GetInvitationsByTargetAsync()
Get invitations by target (email or sms)| Name | Type | Required | Description |
|---|---|---|---|
targetType | string | ✓ | Type of target (email, phone) |
targetValue | string | ✓ | The target value |
Task<List<Invitation>> — List of invitationsRevokeInvitationAsync()
Revoke (delete) an invitation| Name | Type | Required | Description |
|---|---|---|---|
invitationId | string | ✓ | The invitation ID to revoke |
TaskAcceptInvitationsAsync()
Accept multiple invitations using the new User format (preferred)| Name | Type | Required | Description |
|---|---|---|---|
invitationIds | List<string> | ✓ | List of invitation IDs to accept |
user | AcceptUser | ✓ | User with email or phone (and optional name) |
Task<Invitation> — Invitation resultDeleteInvitationsByScopeAsync()
Delete all invitations for a specific scope| Name | Type | Required | Description |
|---|---|---|---|
groupType | string | ✓ | The scope type (organization, team, etc.) |
groupId | string | ✓ | The scope identifier |
TaskGetInvitationsByScopeAsync()
Get all invitations for a specific scope| Name | Type | Required | Description |
|---|---|---|---|
groupType | string | ✓ | The scope type (organization, team, etc.) |
groupId | string | ✓ | The scope identifier |
Task<List<Invitation>> — List of invitations for the scopeReinviteAsync()
Reinvite a user (send invitation again)| Name | Type | Required | Description |
|---|---|---|---|
invitationId | string | ✓ | The invitation ID to reinvite |
Task<Invitation> — The reinvited invitation resultCreateInvitationAsync()
Create an invitation from your backend. This method allows you to create invitations programmatically using your API key, without requiring a user JWT token. Useful for server-side invitation creation, such as “People You May Know” flows or admin-initiated invitations.| Name | Type | Required | Description |
|---|---|---|---|
request | CreateInvitationRequest | ✓ | The create invitation request |
Task<CreateInvitationResponse> — CreateInvitationResponse with id, shortLink, status, and createdAtExample
Example
GetAutojoinDomainsAsync()
Get autojoin domains configured for a specific scope| Name | Type | Required | Description |
|---|---|---|---|
scopeType | string | ✓ | The type of scope (e.g., “organization”, “team”, “project”) |
scope | string | ✓ | The scope identifier (customer’s group ID) |
Task<AutojoinDomainsResponse> — AutojoinDomainsResponse with autojoin domains and invitationConfigureAutojoinAsync()
Configure autojoin domains for a specific scope| Name | Type | Required | Description |
|---|---|---|---|
request | ConfigureAutojoinRequest | ✓ | The configure autojoin request |
Task<AutojoinDomainsResponse> — AutojoinDomainsResponse with updated autojoin domainsSyncInternalInvitationAsync()
Sync an internal invitation action (accept or decline)| Name | Type | Required | Description |
|---|---|---|---|
request | SyncInternalInvitationRequest | ✓ | The sync internal invitation request |
Task<SyncInternalInvitationResponse> — SyncInternalInvitationResponse with processed count and invitationIdsExample
Example
Types
Type Definitions
Type Definitions
GenerateTokenPayload
Payload for GenerateToken - used to generate secure tokens for Vortex components| Field | Type | Required | Description |
|---|---|---|---|
user | TokenUser? | The authenticated user who will be using the Vortex component | |
component | string? | Component ID to generate token for (from your Vortex dashboard) | |
scope | string? | Scope identifier to restrict invitations to a specific team/org (format: “scopeType:scopeId”) | |
vars | Dictionary<string, object>? | Custom variables to pass to the component for template rendering |
TokenUser
User data for GenerateToken - represents the authenticated user sending invitations| Field | Type | Required | Description |
|---|---|---|---|
id | string? | Unique identifier for the user in your system. Used to attribute invitations and track referral chains. | |
name | string? | Display name shown to invitation recipients (e.g., “John invited you”) | |
email | string? | User’s email address. Used for reply-to in invitation emails. | |
avatarUrl | string? | URL to user’s avatar image. Displayed in invitation emails and widgets. | |
adminScopes | List<string>? | List of scope IDs where this user has admin privileges (e.g., [“team:team-123”]) |
AcceptUser
User data for accepting invitations - identifies who accepted the invitation| Field | Type | Required | Description |
|---|---|---|---|
email | string? | Email address of the user accepting. At least one of Email or Phone is required. | |
phone | string? | Phone number with country code (e.g., “+15551234567”). At least one of Email or Phone is required. | |
name | string? | Display name of the accepting user (shown in notifications to inviter) | |
isExisting | bool? | Whether user was already registered. true=existing, false=new signup, null=unknown. Used for conversion analytics. |
Invitation
Complete invitation details as returned by the Vortex API| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Unique identifier for this invitation |
accountId | string | Your Vortex account ID | |
clickThroughs | int | Number of times the invitation link was clicked | |
formSubmissionData | Dictionary<string, object>? | Data submitted through the invitation form, including standard fields and any custom fields configured on your widget. | |
configurationAttributes | Dictionary<string, object>? | ||
attributes | Dictionary<string, object>? | Custom attributes attached to this invitation | |
createdAt | string | ISO 8601 timestamp when the invitation was created | |
deactivated | bool | Whether this invitation has been revoked or expired | |
deliveryCount | int | Number of times the invitation was sent (including reminders) | |
deliveryTypes | List<DeliveryType> | Channels used to deliver this invitation (email, sms, share link) | |
foreignCreatorId | string | Your internal user ID for the person who created this invitation | |
invitationType | InvitationType | Type of invitation: single_use (1:1), multi_use (1:many), or autojoin | |
modifiedAt | string? | ISO 8601 timestamp of last modification | |
status | InvitationStatus | Current status: queued, sending, sent, delivered, accepted, shared, unfurled | |
target | List<InvitationTarget> | List of invitation recipients with their contact info and status | |
views | int | Number of times the invitation page was viewed | |
widgetConfigurationId | string | Widget configuration ID used for this invitation | |
deploymentId | string | Deployment ID this invitation belongs to | |
groups | List<InvitationScope> | Scopes (teams/orgs) this invitation grants access to | |
accepts | List<InvitationAcceptance>? | List of acceptance records if the invitation was accepted (optional) | |
scope | string? | Primary scope identifier (e.g., “team-123”) | |
scopeType | string? | Type of the primary scope (e.g., “team”, “organization”) | |
expired | bool | Whether this invitation has passed its expiration date | |
expires | string? | ISO 8601 timestamp when this invitation expires | |
metadata | Dictionary<string, object>? | Custom metadata attached to this invitation | |
passThrough | string? | Pass-through data returned unchanged in webhooks and callbacks | |
source | string? | Source identifier for tracking (e.g., “ios-app”, “web-dashboard”) | |
subtype | string? | Subtype for analytics segmentation (e.g., “pymk”, “find-friends”) | |
creatorName | string? | Display name of the user who created this invitation | |
creatorAvatarUrl | string? | Avatar URL of the user who created this invitation |
InvitationTarget
Represents the target recipient of an invitation| Field | Type | Required | Description |
|---|---|---|---|
type | InvitationTargetType | ✓ | Delivery channel: email, phone, share (link), or internal (in-app) |
value | string | Target address: email, phone number with country code, or share link ID | |
name | string? | Display name of the recipient (e.g., “John Doe”) | |
avatarUrl | string? | Avatar URL for the recipient, shown in invitation lists and widgets |
InvitationScope
Invitation group from API responses This matches the MemberGroups table structure from the API| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Vortex internal UUID |
accountId | string | Vortex account ID | |
groupId | string | Customer’s group ID (the ID they provided to Vortex) | |
type | string | ✓ | Group type (e.g., “workspace”, “team”) |
name | string | Group name | |
createdAt | string | ISO 8601 timestamp when the group was created |
CreateInvitationTarget
Target recipient when creating an invitation| Field | Type | Required | Description |
|---|---|---|---|
type | CreateInvitationTargetTypeEnum | ✓ | Delivery channel: email, phone, or internal (in-app) |
value | string | Target address: email, phone number (with country code), or internal user ID | |
name | string? | Display name of the recipient (shown in invitation emails and UI) | |
avatarUrl | string? | Avatar URL for the recipient (displayed in invitation lists) |
Inviter
Information about the user sending the invitation - used for attribution and display| Field | Type | Required | Description |
|---|---|---|---|
userId | string | ✓ | Your internal user ID for the inviter (required for attribution) |
userEmail | string? | Inviter’s email address (used for reply-to and identification) | |
name | string? | Display name shown to recipients (e.g., “John invited you to…”) | |
avatarUrl | string? | Avatar URL displayed in invitation emails and widgets |
User
User data for JWT generation - represents the authenticated user sending invitations. Only Id is required. Email is optional but recommended for invitation attribution.| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Your internal user ID (required for invitation attribution) |
email | string? | User’s email address (optional, used for reply-to in invitation emails) | |
name | string? | Display name shown to recipients (e.g., “John invited you”) | |
avatarUrl | string? | Avatar URL displayed in invitation emails and widgets (must be HTTPS) | |
adminScopes | List<string>? | List of scopes where user has admin privileges (e.g., [“autojoin”]) | |
allowedEmailDomains | List<string>? | Restrict invitations to these email domains (e.g., [“acme.com”]) |
Identifier
Identifier for a user - used in JWT generation to link user across channels| Field | Type | Required | Description |
|---|---|---|---|
type | string | ✓ | Identifier type: “email”, “phone”, “username”, or custom type |
value | string | The identifier value (email address, phone number, etc.) |
Group
Scope/group for JWT generation - defines user’s team/org membership in tokens| Field | Type | Required | Description |
|---|---|---|---|
type | string | ✓ | Scope type (e.g., “team”, “organization”, “workspace”) |
id | string? | Legacy scope identifier. Use Scope/groupId instead. | |
groupId | string? | Your internal scope/group identifier (preferred) | |
name | string | Display name for the scope (e.g., “Engineering Team”) |
InvitationAcceptance
Record of an invitation being accepted| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Unique identifier for this acceptance record |
accountId | string | Your Vortex account ID | |
acceptedAt | string | ISO 8601 timestamp when the invitation was accepted | |
target | InvitationTarget? | The target that accepted the invitation |
CreateInvitationScope
Group information for creating invitations| Field | Type | Required | Description |
|---|---|---|---|
type | string | ✓ | Group type (e.g., “team”, “organization”) |
groupId | string | Your internal group ID | |
name | string | Display name of the group |
UnfurlConfig
Configuration for link unfurl (Open Graph) metadata. Controls how the invitation link appears when shared on social platforms or messaging apps.| Field | Type | Required | Description |
|---|---|---|---|
title | string? | The title shown in link previews (og:title) | |
description | string? | The description shown in link previews (og:description) | |
image | string? | The image URL shown in link previews (og:image) - must be HTTPS | |
type | string? | The Open Graph type (og:type) - e.g., ‘website’, ‘article’, ‘product’ | |
siteName | string? | The site name shown in link previews (og:site_name) |
AutojoinDomain
Autojoin domain - users with matching email domains automatically join the scope| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Unique identifier for this autojoin configuration |
domain | string | Email domain that triggers autojoin (e.g., “acme.com”) |
Webhooks
Webhooks let your server receive real-time notifications when events happen in Vortex. Use them to sync invitation state with your database, trigger onboarding flows, update your CRM, or send internal notifications.Setup
- Go to your Vortex dashboard → Integrations → Webhooks tab
- Click “Add Webhook”
- Enter your endpoint URL (must be HTTPS in production)
- Copy the signing secret — you’ll use this to verify webhook signatures
- Select which events you want to receive
Example
ASP.NET Core webhook handlerEvents
| Event | Description |
|---|---|
invitation.created | A new invitation was created |
invitation.accepted | An invitation was accepted by the recipient |
invitation.deactivated | An invitation was deactivated (revoked or expired) |
invitation.email.delivered | Invitation email was successfully delivered |
invitation.email.bounced | Invitation email bounced (invalid address) |
invitation.email.opened | Recipient opened the invitation email |
invitation.link.clicked | Recipient clicked the invitation link |
invitation.reminder.sent | A reminder email was sent for a pending invitation |
member.created | A new member was created from an accepted invitation |
group.member.added | A member was added to a scope/group |
deployment.created | A new deployment configuration was created |
deployment.deactivated | A deployment was deactivated |
abtest.started | An A/B test was started |
abtest.winner_declared | An A/B test winner was declared |
email.complained | Recipient marked the email as spam |
Use Cases
- Activate users on acceptance — When invitation.accepted fires, mark the user as active in your database and trigger your onboarding flow.
- Track invitation performance — Monitor email.delivered, email.opened, and link.clicked events to measure invitation funnel metrics.
- Sync team membership — Use member.created and group.member.added to keep your internal membership records in sync.
- Alert on delivery issues — Watch for email.bounced events to proactively reach out via alternative channels.
Error Handling
| Error | Description |
|---|---|
VortexException | Thrown for validation errors (e.g., missing API key, invalid parameters) or API failures |