typescript SDK

Vortex handles the complete invitation lifecycle — sending invites via email/SMS/share links, tracking clicks and conversions, managing referral programs, and optimizing your invitation flows with A/B testing. You focus on your product; Vortex handles the growth mechanics.

Installation

npm install @teamvortexsoftware/vortex-node-22-sdk

Quick Start

Generate a secure token for Vortex components

import { Vortex } from '@teamvortexsoftware/vortex-node-22-sdk';

const vortex = new Vortex(process.env.VORTEX_API_KEY!);

// Generate a token for the current user
const token = vortex.generateToken({
  user: { id: 'user-123', email: 'user@example.com' }
});

// Pass the token to your frontend component
// <VortexInvite token={token} />

Integration 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.

Install the backend SDK

Add this SDK to your Node.js server

npm install @teamvortexsoftware/vortex-node-22-sdk

Initialize the client

Create a Vortex client with your API key (keep this on the server!)

import { Vortex } from '@teamvortexsoftware/vortex-node-22-sdk';

const vortex = new Vortex(process.env.VORTEX_API_KEY);

Generate a token for the current user

When a user loads a page with a Vortex component, generate a signed token on your server

const token = vortex.generateToken({ user: { id: currentUser.id } });

Pass the token to your frontend

Include the token in your page response or API response

res.json({ vortexToken: token, ...otherData });

Render a Vortex component with the token

Use the React/Angular/Web Component with the token

import { VortexInvite } from '@teamvortexsoftware/vortex-react';

<VortexInvite token={vortexToken} />

Vortex handles the rest

The component securely communicates with Vortex servers, displays the invitation UI, sends emails/SMS, tracks conversions, and reports analytics

Methods

Core Methods

`generateToken()`

Sign a payload for use with Vortex widgets This method generates a signed JWT token containing your payload data. The token can be passed to widgets via the token prop to authenticate and authorize the request.

generateToken(payload: GenerateTokenData, options?: GenerateTokenOptions | undefined): string

Parameters:

Name	Type	Required	Description
`payload`	`GenerateTokenData`	✓	Data to sign (user, component, scope, vars, etc.)
`options`	`GenerateTokenOptions	undefined`		Optional configuration (expiresIn)

Returns: string — Signed JWT token string

Example

// --- Backend (Node.js/Express) ---
import { Vortex } from '@teamvortexsoftware/vortex-node-22-sdk';

const vortex = new Vortex(process.env.VORTEX_API_KEY);

app.get('/api/invite-token', (req, res) => {
  const token = vortex.generateToken({
    user: { id: req.user.id, email: req.user.email }
  });
  res.json({ token });
});

// --- Frontend (React) ---
import { VortexInvite } from '@teamvortexsoftware/vortex-react';

function InvitePage() {
  const { data } = useFetch('/api/invite-token');
  return <VortexInvite token={data.token} />;
}

`getInvitation()`

Get a single invitation by ID

getInvitation(invitationId: string): Promise<InvitationResult>

Parameters:

Name	Type	Required	Description
`invitationId`	`string`	✓	The invitation ID to retrieve

Returns: Promise<InvitationResult> — The invitation details

Example

const invitation = await vortex.getInvitation('inv-123');
console.log(invitation.status);

`acceptInvitation()`

Accept a single invitation This is the recommended method for accepting invitations.

acceptInvitation(invitationId: string, user: AcceptUser): Promise<InvitationResult>

Parameters:

Name	Type	Required	Description
`invitationId`	`string`	✓	Single invitation ID to accept
`user`	`AcceptUser`	✓	User object with email or phone (and optional name)

Returns: Promise<InvitationResult> — Invitation result

Example

await vortex.acceptInvitation('inv-123', { email: 'user@example.com', name: 'John' });

Additional Methods

`generateJwt()`

Generate a JWT token for a user

generateJwt(params: { [key: string]: any; user: User; }, options?: GenerateJwtOptions | undefined): string

Parameters:

Name	Type	Required	Description
`params`	`{ [key: string]: any; user: User; }`	✓	Object containing user and optional additional properties
`options`	`GenerateJwtOptions	undefined`		Optional configuration (expiresIn)

Returns: string — JWT token string

Example

const token = vortex.generateJwt({
  user: {
    id: "user-123",
    email: "user@example.com",
    adminScopes: ['autojoin']
  }
});

// With custom expiration
const tokenWithCustomExpiry = vortex.generateJwt(
  { user: { id: "user-123", email: "user@example.com" } },
  { expiresIn: '24h' }  // Custom expiration (default: 30 days)
);

`getInvitationsByTarget()`

Get invitations by target (email, username, or phone number)

getInvitationsByTarget(targetType: "email" | "username" | "phoneNumber", targetValue: string): Promise<InvitationResultBase[]>

Parameters:

Name	Type	Required	Description
`targetType`	`“email"	"username"	"phoneNumber”`	✓	The type of target identifier
`targetValue`	`string`	✓	The target value to search for

Returns: Promise<InvitationResultBase[]> — Array of invitation results matching the target

Example

const invitations = await vortex.getInvitationsByTarget('email', 'user@example.com');

`revokeInvitation()`

Revoke (delete) an invitation

revokeInvitation(invitationId: string): Promise<{}>

Parameters:

Name	Type	Required	Description
`invitationId`	`string`	✓	The invitation ID to revoke

Returns: Promise<{}> — Empty object on success

Example

await vortex.revokeInvitation('inv-123');

`acceptInvitations()`

Accept one or more invitations for a user

acceptInvitations(invitationIds: string[], userOrTarget: AcceptUser | InvitationTarget | InvitationTarget[]): Promise<InvitationResult>

Parameters:

Name	Type	Required	Description
`invitationIds`	`string[]`	✓	Array of invitation IDs to accept
`userOrTarget`	`AcceptUser	InvitationTarget	InvitationTarget[]`	✓	User object with email or phone, or legacy target format

Returns: Promise<InvitationResult> — The accepted invitation result

Example

await vortex.acceptInvitations(['inv-123'], { email: 'user@example.com' });

`deleteInvitationsByGroup()`

Delete all invitations for a specific group

deleteInvitationsByGroup(groupType: string, groupId: string): Promise<{}>

Parameters:

Name	Type	Required	Description
`groupType`	`string`	✓	The type of group (e.g., “team”, “organization”)
`groupId`	`string`	✓	The group identifier

Returns: Promise<{}> — Empty object

`getInvitationsByGroup()`

Get all invitations for a specific group

getInvitationsByGroup(groupType: string, groupId: string): Promise<InvitationResult[]>

Parameters:

Name	Type	Required	Description
`groupType`	`string`	✓	The type of group (e.g., “team”, “organization”)
`groupId`	`string`	✓	The group identifier

Returns: Promise<InvitationResult[]> — Array of invitation results

`deleteInvitationsByScope()`

Delete all invitations for a specific scope

deleteInvitationsByScope(scopeType: string, scope: string): Promise<{}>

Parameters:

Name	Type	Required	Description
`scopeType`	`string`	✓	The type of scope (e.g., “team”, “organization”)
`scope`	`string`	✓	The scope identifier (customer’s scope ID)

Returns: Promise<{}> — Empty object

Example

await vortex.deleteInvitationsByScope('team', 'team-123');

`getInvitationsByScope()`

Get all invitations for a specific scope

getInvitationsByScope(scopeType: string, scope: string): Promise<InvitationResult[]>

Parameters:

Name	Type	Required	Description
`scopeType`	`string`	✓	The type of scope (e.g., “team”, “organization”)
`scope`	`string`	✓	The scope identifier (customer’s scope ID)

Returns: Promise<InvitationResult[]> — Array of invitation results

Example

const invitations = await vortex.getInvitationsByScope('team', 'team-123');

`reinvite()`

Resend an invitation (reinvite)

reinvite(invitationId: string): Promise<InvitationResult>

Parameters:

Name	Type	Required	Description
`invitationId`	`string`	✓	The invitation ID to resend

Returns: Promise<InvitationResult> — The updated invitation

Example

const invitation = await vortex.reinvite('inv-123');

`getAutojoinDomains()`

Get autojoin domains configured for a specific scope

getAutojoinDomains(scopeType: string, scope: string): Promise<AutojoinDomainsResponse>

Parameters:

Name	Type	Required	Description
`scopeType`	`string`	✓	The type of scope (e.g., “organization”, “team”, “project”)
`scope`	`string`	✓	The scope identifier (customer’s group ID)

Returns: Promise<AutojoinDomainsResponse> — Autojoin domains and associated invitation

Example

const result = await vortex.getAutojoinDomains('organization', 'acme-org');
console.log(result.autojoinDomains); // [{ id: '...', domain: 'acme.com' }]

`configureAutojoin()`

Configure autojoin domains for a specific scopeThis endpoint syncs autojoin domains - it will add new domains, remove domains not in the provided list, and deactivate the autojoin invitation if all domains are removed (empty array).

configureAutojoin(params: ConfigureAutojoinRequest): Promise<AutojoinDomainsResponse>

Parameters:

Name	Type	Required	Description
`params`	`ConfigureAutojoinRequest`	✓	Configuration parameters

Returns: Promise<AutojoinDomainsResponse> — Updated autojoin domains and associated invitation

Example

const result = await vortex.configureAutojoin({
  scope: 'acme-org',
  scopeType: 'organization',
  scopeName: 'Acme Corporation',
  domains: ['acme.com', 'acme.org'],
  componentId: 'component-123',
});

`syncInternalInvitation()`

Sync an internal invitation action (accept or decline)This method notifies Vortex that an internal invitation was accepted or declined within your application, so Vortex can update the invitation status accordingly.

syncInternalInvitation(params: SyncInternalInvitationRequest): Promise<SyncInternalInvitationResponse>

Parameters:

Name	Type	Required	Description
`params`	`SyncInternalInvitationRequest`	✓	Sync parameters

Returns: Promise<SyncInternalInvitationResponse> — Object with processed count and invitation IDs

Example

const result = await vortex.syncInternalInvitation({
  creatorId: 'user-123',
  targetValue: 'user-456',
  action: 'accepted',
  componentId: 'component-uuid-789',
});
console.log(`Processed ${result.processed} invitations`);

`getEnvironments()`

List all environments configured for the authenticated account.Environments represent deployment targets (e.g., “development”, “staging”, “production”) and form a promotion chain via nextEnvironmentId / previousEnvironmentId. The account is derived from the API key.

getEnvironments(): Promise<Environment[]>

Returns: Promise<Environment[]> — Array of environments belonging to the account

Example

const environments = await vortex.getEnvironments();
const production = environments.find((env) => env.role === 'production');

`getDeployments()`

List deployments for the authenticated account, optionally filtered by widget, environment, or project.Each deployment row joins the deployment record with its target environment, the widget being deployed, and the widget configurations referenced in the deployment’s distribution. This is useful for resolving a widgetConfigurationId from a componentId (widget) for a given environment. The account is derived from the API key.

getDeployments(params?: GetDeploymentsParams): Promise<DeploymentResult[]>

Parameters:

Name	Type	Required	Description
`params`	`GetDeploymentsParams`		Filter parameters

Returns: Promise<DeploymentResult[]> — Array of deployment results, each including widget, environment, and associated widget configurations

Example

// Resolve the active widgetConfigurationId for a widget in an environment
const deployments = await vortex.getDeployments({
  widgetId: 'widget-uuid-456',
  environmentId: 'env-uuid-789',
});

const widgetConfigurationId =
  deployments[0]?.deployment.widgetConfigurationDistributions[0]
    ?.widgetConfigurationId;

Types

Type Definitions

`InvitationTarget`

Target recipient of an invitation

Field	Type	Required	Description
`type`	`“email"	"phone"	"share"	"internal”`	✓	Delivery channel type
`value`	`string`	✓	Target address (email, phone number, or share link ID)
`name`	`string	null	undefined`		Display name of the person being invited
`avatarUrl`	`string	null	undefined`		Avatar URL for the person being invited

`ScopeInput`

ScopeInput is used when creating JWTs - represents customer’s scope data Supports both ‘id’ (legacy) and ‘groupId’ (preferred) for backward compatibility

Field	Type	Required	Description
`type`	`string`	✓	Scope type (e.g., ‘team’, ‘organization’, ‘workspace’)
`id`	`string	undefined`		⚠️ Deprecated: Use scopeId instead
`scopeId`	`string	undefined`		The scope identifier (preferred)
`groupId`	`string	undefined`		⚠️ Deprecated: Use scopeId instead
`name`	`string`	✓	Display name for the scope

`GroupInput`

Field	Type	Required	Description
`type`	`string`	✓	Scope type (e.g., ‘team’, ‘organization’, ‘workspace’)
`id`	`string	undefined`		⚠️ Deprecated: Use scopeId instead
`scopeId`	`string	undefined`		The scope identifier (preferred)
`groupId`	`string	undefined`		⚠️ Deprecated: Use scopeId instead
`name`	`string`	✓	Display name for the scope

`InvitationScope`

InvitationScope represents a scope in 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
`scopeId`	`string`	✓	The customer’s scope ID (preferred)
`groupId`	`string`	✓	⚠️ Deprecated: Use scopeId instead
`type`	`string`	✓	Scope type (e.g., ‘workspace’, ‘team’)
`name`	`string`	✓	Display name for the scope
`createdAt`	`string`	✓	ISO timestamp when the scope was created

`InvitationGroup`

Field	Type	Required	Description
`id`	`string`	✓	Vortex internal UUID
`accountId`	`string`	✓	Vortex account ID
`scopeId`	`string`	✓	The customer’s scope ID (preferred)
`groupId`	`string`	✓	⚠️ Deprecated: Use scopeId instead
`type`	`string`	✓	Scope type (e.g., ‘workspace’, ‘team’)
`name`	`string`	✓	Display name for the scope
`createdAt`	`string`	✓	ISO timestamp when the scope was created

`InvitationAcceptance`

Record of a user accepting an invitation

Field	Type	Required	Description
`id`	`string`	✓	Unique acceptance record ID
`accountId`	`string`	✓	Vortex account ID
`acceptedAt`	`string`	✓	ISO timestamp when the invitation was accepted
`target`	`InvitationTarget`	✓	The user who accepted the invitation

`InvitationResultBase`

Base invitation result without target information. Used by endpoints like getInvitationsByTarget where target is already known.

Field	Type	Required	Description
`id`	`string`	✓	Unique invitation identifier
`accountId`	`string`	✓	Vortex account ID that owns this invitation
`clickThroughs`	`number`	✓	Number of times the invitation link was clicked
`formSubmissionData`	`Record<string, any>	null`	✓	Invitation form data submitted by the user, including email addresses of invitees and the values of any custom fields.
`configurationAttributes`	`Record<string, any>	null`	✓	⚠️ Deprecated: Use formSubmissionData instead. This field contains the same data.
`attributes`	`Record<string, any>	null`	✓	Custom attributes attached to this invitation
`createdAt`	`string`	✓	ISO timestamp when the invitation was created
`deactivated`	`boolean`	✓	Whether the invitation has been deactivated
`deliveryCount`	`number`	✓	Number of delivery attempts made
`deliveryTypes`	`(“email"	"phone"	"share"	"internal”)[]`	✓	Delivery channels used for this invitation
`foreignCreatorId`	`string`	✓	Your user ID who created this invitation
`invitationType`	`“single_use"	"multi_use"	"autojoin”`	✓	Type of invitation: single_use (one accept), multi_use (unlimited), or autojoin (domain-based)
`modifiedAt`	`string	null`	✓	ISO timestamp when the invitation was last modified
`status`	`“queued"	"sending"	"sent"	"delivered"	"accepted"	"shared"	"unfurled"	"accepted_elsewhere”`	✓	Current status of the invitation
`views`	`number`	✓	Number of times the invitation was viewed
`widgetConfigurationId`	`string`	✓	ID of the component configuration used
`scopes`	`InvitationScope[]`	✓	Scopes associated with this invitation (preferred)
`groups`	`InvitationScope[]`	✓	⚠️ Deprecated: Use scopes instead
`accepts`	`InvitationAcceptance[]	undefined`		List of users who accepted this invitation
`expired`	`boolean`	✓	Whether the invitation has expired
`expires`	`string	undefined`		ISO timestamp when the invitation expires
`source`	`string	undefined`		Source identifier (e.g., campaign name)
`subtype`	`string	null	undefined`		Customer-defined subtype for categorizing this invitation (e.g., pymk, find-friends, profile-button)
`creatorName`	`string	null	undefined`		Display name of the invitation creator
`creatorAvatarUrl`	`string	null	undefined`		Avatar URL of the invitation creator

`InvitationResult`

Full invitation result including target information. Used by getInvitation, getInvitationsByScope, and other endpoints that return targets.

Field	Type	Required	Description
`id`	`string`	✓	Unique invitation identifier
`accountId`	`string`	✓	Vortex account ID that owns this invitation
`clickThroughs`	`number`	✓	Number of times the invitation link was clicked
`formSubmissionData`	`Record<string, any>	null`	✓	Invitation form data submitted by the user, including email addresses of invitees and the values of any custom fields.
`configurationAttributes`	`Record<string, any>	null`	✓	⚠️ Deprecated: Use formSubmissionData instead. This field contains the same data.
`attributes`	`Record<string, any>	null`	✓	Custom attributes attached to this invitation
`createdAt`	`string`	✓	ISO timestamp when the invitation was created
`deactivated`	`boolean`	✓	Whether the invitation has been deactivated
`deliveryCount`	`number`	✓	Number of delivery attempts made
`deliveryTypes`	`(“email"	"phone"	"share"	"internal”)[]`	✓	Delivery channels used for this invitation
`foreignCreatorId`	`string`	✓	Your user ID who created this invitation
`invitationType`	`“single_use"	"multi_use"	"autojoin”`	✓	Type of invitation: single_use (one accept), multi_use (unlimited), or autojoin (domain-based)
`modifiedAt`	`string	null`	✓	ISO timestamp when the invitation was last modified
`status`	`“queued"	"sending"	"sent"	"delivered"	"accepted"	"shared"	"unfurled"	"accepted_elsewhere”`	✓	Current status of the invitation
`views`	`number`	✓	Number of times the invitation was viewed
`widgetConfigurationId`	`string`	✓	ID of the component configuration used
`scopes`	`InvitationScope[]`	✓	Scopes associated with this invitation (preferred)
`groups`	`InvitationScope[]`	✓	⚠️ Deprecated: Use scopes instead
`accepts`	`InvitationAcceptance[]	undefined`		List of users who accepted this invitation
`expired`	`boolean`	✓	Whether the invitation has expired
`expires`	`string	undefined`		ISO timestamp when the invitation expires
`source`	`string	undefined`		Source identifier (e.g., campaign name)
`subtype`	`string	null	undefined`		Customer-defined subtype for categorizing this invitation (e.g., pymk, find-friends, profile-button)
`creatorName`	`string	null	undefined`		Display name of the invitation creator
`creatorAvatarUrl`	`string	null	undefined`		Avatar URL of the invitation creator
`target`	`InvitationTarget[]`	✓	List of invitation targets (recipients)

`AcceptUser`

User type for accepting invitations Requires either email or phone (or both)

Field	Type	Required
`email`	`string	undefined`	Email address of the accepting user
`phone`	`string	undefined`	Phone number of the accepting user
`name`	`string	undefined`	Display name of the accepting user
`isExisting`	`boolean	undefined`	Whether the accepting user is an existing user in your system.
Set to true if the user was already registered before accepting the invitation.
Set to false if this is a new user signup.
Leave undefined if unknown.
Used for analytics to track new vs existing user conversions.

`AcceptInvitationRequest`

Request body for accepting invitations

Field	Type	Required	Description
`invitationIds`	`string[]`	✓	Array of invitation IDs to accept
`user`	`AcceptUser`	✓	Information about the user accepting the invitations

`AcceptInvitationRequestLegacy`

Legacy request body for accepting invitations

Field	Type	Required	Description
`invitationIds`	`string[]`	✓	Array of invitation IDs to accept
`target`	`InvitationTarget`	✓	Target information (legacy format)

`SyncInternalInvitationRequest`

Request body for syncing an internal invitation action

Field	Type	Required	Description
`creatorId`	`string`	✓	The inviter’s user ID
`targetValue`	`string`	✓	The invitee’s user ID
`action`	`“accepted"	"declined”`	✓	The action taken: “accepted” or “declined”
`componentId`	`string`	✓	The widget component UUID

`SyncInternalInvitationResponse`

Response from syncing an internal invitation action

Field	Type	Required	Description
`processed`	`number`	✓	Number of invitations processed
`invitationIds`	`string[]`	✓	IDs of the invitations that were processed

`User`

User type for JWT generation Only id is required. Email is optional but recommended for invitation attribution.

Field	Type	Required	Description
`id`	`string`	✓	Unique user identifier in your system
`email`	`string	undefined`		User’s email address (optional, used for reply-to in invitation emails)
`name`	`string	undefined`		User’s display name (preferred)
`avatarUrl`	`string	undefined`		User’s avatar URL (preferred)
`userName`	`string	undefined`		⚠️ Deprecated: Use `name` instead
`userAvatarUrl`	`string	undefined`		⚠️ Deprecated: Use `avatarUrl` instead
`adminScopes`	`string[]	undefined`		Admin scope permissions (e.g., [‘autojoin’])
`allowedEmailDomains`	`string[]	undefined`		Optional list of allowed email domains for invitation restrictions.
When present, email invitations will only be allowed to addresses
matching one of these domains (e.g., [‘acme.com’, ‘acme.org’]).
Domain matching is case-insensitive.

`AutojoinDomain`

Autojoin domain configuration Allows users with matching email domains to automatically join a scope

Field	Type	Required	Description
`id`	`string`	✓	Unique domain configuration ID
`domain`	`string`	✓	Email domain (e.g., ‘acme.com’)

`AutojoinDomainsResponse`

Response from autojoin API endpoints

Field	Type	Required	Description
`autojoinDomains`	`AutojoinDomain[]`	✓	List of configured autojoin domains
`invitation`	`InvitationResult	null`	✓	The autojoin invitation if one exists, null otherwise

`ConfigureAutojoinRequest`

Request body for configuring autojoin domains

Field	Type	Required	Description
`scope`	`string`	✓	Scope ID in your system
`scopeType`	`string`	✓	Type of scope (e.g., ‘team’, ‘organization’)
`scopeName`	`string	undefined`		Display name for the scope
`domains`	`string[]`	✓	List of email domains that can autojoin (e.g., [‘acme.com’, ‘acme.org’])
`componentId`	`string`	✓	Component ID to use for autojoin invitations
`metadata`	`Record<string, any>	undefined`		Custom metadata to attach to autojoin invitations

`Inviter`

Information about the user creating the invitation (the inviter)

Field	Type	Required	Description
`userId`	`string`	✓	The internal user ID of the person creating the invitation (from your system)
`userEmail`	`string	undefined`		The email address of the person creating the invitation
`name`	`string	undefined`		The display name of the person creating the invitation (preferred)
`avatarUrl`	`string	undefined`		Avatar URL for the person creating the invitation (preferred)
`userName`	`string	undefined`		⚠️ Deprecated: Use `name` instead
`userAvatarUrl`	`string	undefined`		⚠️ Deprecated: Use `avatarUrl` instead

`GenerateTokenUser`

User object for generateToken - flexible structure Only id is required for secure attribution

Field	Type	Required	Description
`id`	`string	number`	✓	User ID - required for secure attribution
`email`	`string	undefined`		User’s email address
`name`	`string	undefined`		User’s display name
`phone`	`string	undefined`		User’s phone number
`avatarUrl`	`string	undefined`		User’s avatar URL

`GenerateTokenData`

Payload structure for generateToken method All fields are optional - sign only what you need

Field	Type	Required
`component`	`string	undefined`	Widget component ID
`trigger`	`string	undefined`	DOM selector for trigger button
`embed`	`string	undefined`	DOM selector for embed container
`user`	`GenerateTokenUser	undefined`	User information - include `id` for secure attribution
`scope`	`string	undefined`	Scope/workspace identifier
`vars`	`Record<string, any>	undefined`	Template variables for customization

`GenerateJwtOptions`

Options for generateJwt method

Field	Type	Required	Description
`expiresIn`	`string	number	undefined`		JWT expiration time

String format: ‘5m’, ‘1h’, ‘24h’, ‘7d’ (minutes, hours, days)
Number format: seconds
Default: 30 days (2592000 seconds) |

`GenerateTokenOptions`

Options for generateToken method

Field	Type	Required	Description
`expiresIn`	`string	number	undefined`		Token expiration time

String format: ‘5m’, ‘1h’, ‘24h’, ‘7d’ (minutes, hours, days)
Number format: seconds
Default: ‘30d’ (30 days) |

`Environment`

Environment as returned by the Vortex API /environments endpoint. Environments represent deployment targets (e.g., “development”, “staging”, “production”).Note: this type matches FullEnvironmentResultDto from the public API and includes sortingWeight. The shape embedded in deployment results (see DeploymentEnvironment) is a different, smaller DTO that does NOT include sortingWeight.

Field	Type	Required	Description
`id`	`string`	✓	Vortex internal UUID for this environment
`name`	`string	null`	✓	Display name of the environment (e.g., “production”)
`description`	`string	null	undefined`		Optional description of the environment
`nextEnvironmentId`	`string	null	undefined`		ID of the next environment in the promotion chain, if any
`previousEnvironmentId`	`string	null	undefined`		ID of the previous environment in the promotion chain, if any
`role`	`string	null	undefined`		Role of the environment (e.g., “production”, “staging”)
`nextEnvironmentName`	`string	null	undefined`		Display name of the next environment in the promotion chain
`previousEnvironmentName`	`string	null	undefined`		Display name of the previous environment in the promotion chain
`sortingWeight`	`number`	✓	Sorting weight used to order environments in the UI

`DeploymentEnvironment`

Environment shape embedded in deployment results.This matches EnvironmentResultDto from apps/public-api/src/deployments/dto/deployment-result.dto.ts, which is a narrower DTO than the one returned by the /environments endpoint. In particular, it does NOT include sortingWeight and name is non-nullable.Use Environment for results from getEnvironments() and DeploymentEnvironment for the environment field of DeploymentResult.

Field	Type	Required	Description
`id`	`string`	✓	Vortex internal UUID for this environment
`name`	`string`	✓	Display name of the environment (e.g., “production”)
`description`	`string	null`	✓	Optional description of the environment
`nextEnvironmentId`	`string	null`	✓	ID of the next environment in the promotion chain, if any
`previousEnvironmentId`	`string	null`	✓	ID of the previous environment in the promotion chain, if any
`role`	`string	null`	✓	Role of the environment (e.g., “production”, “staging”)
`nextEnvironmentName`	`string	null`	✓	Display name of the next environment in the promotion chain
`previousEnvironmentName`	`string	null`	✓	Display name of the previous environment in the promotion chain

`Deployment`

Deployment metadata as returned by the Vortex API. Represents a single deployment record describing how widget configurations are distributed within an environment.

Field	Type	Required	Description
`id`	`string`	✓	Vortex internal UUID for this deployment
`name`	`string`	✓	Display name of the deployment
`description`	`string	null	undefined`	Optional description of the deployment
`widgetConfigurationDistributions`	`WidgetConfigurationDistribution[]`	✓	Distribution of widget configurations served by this deployment
`createdAt`	`string`	✓	ISO timestamp when the deployment was created
`deactivated`	`boolean`	✓	Whether this deployment has been deactivated

`WidgetConfigurationDistribution`

Distribution entry used to split traffic across widget configurations.

Field	Type	Required	Description
`widgetConfigurationId`	`string`	✓	Vortex internal UUID for the widget configuration
`distributionPercentage`	`number`	✓	Percentage of users that will receive this configuration (0-100)

`DeploymentWidget`

Widget summary as included in deployment results.

Field	Type	Required	Description
`id`	`string`	✓	Vortex internal UUID for the widget
`name`	`string`	✓	Widget display name
`type`	`string`	✓	Widget type (e.g., “vortex-invite”)
`projectId`	`string`	✓	ID of the project the widget belongs to

`DeploymentWidgetConfiguration`

Widget configuration summary as included in deployment results.

Field	Type	Required	Description
`id`	`string`	✓	Vortex internal UUID for the widget configuration
`version`	`string`	✓	Version label of the widget configuration
`status`	`string`	✓	Status of the widget configuration

`DeploymentResult`

Single deployment row returned by getDeployments(). Joins deployment, environment, widget and widget configuration metadata.

Field	Type	Required	Description
`accountId`	`string`	✓	Vortex account ID that owns this deployment
`deployment`	`Deployment`	✓	Deployment metadata
`environment`	`DeploymentEnvironment`	✓	Environment the deployment targets.

`GetDeploymentsParams`

Filter parameters for getDeployments(). All fields are optional. The account is derived from the API key.

Field	Type	Required
`widgetId`	`string	undefined`	Optional widget ID filter
`environmentId`	`string	undefined`	Optional environment ID filter
`projectId`	`string	undefined`	Optional project ID filter

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

Express.js webhook handler

import express from 'express';
import { VortexWebhooks, isWebhookEvent } from '@teamvortexsoftware/vortex-node-22-sdk';

const app = express();
const webhooks = new VortexWebhooks({
  secret: process.env.VORTEX_WEBHOOK_SECRET!,
});

// Important: Use raw body for signature verification
app.post('/webhooks/vortex', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = webhooks.constructEvent(
      req.body,
      req.headers['x-vortex-signature'] as string
    );

    if (isWebhookEvent(event)) {
      switch (event.type) {
        case 'invitation.accepted':
          // User accepted an invitation — activate their account
          console.log('Invitation accepted:', event.data.targetEmail);
          break;
        case 'member.created':
          // New member joined via invitation
          console.log('New member:', event.data);
          break;
      }
    }

    res.json({ received: true });
  } catch (err) {
    console.error('Webhook error:', err);
    res.status(400).send('Webhook Error');
  }
});

Events

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
`VortexWebhookSignatureError`	Thrown when webhook signature verification fails. Check that you are using the raw request body (not parsed JSON) and the correct signing secret from your Vortex dashboard.
`Error`	Thrown for validation errors (e.g., missing API key, invalid user ID in generateToken/generateJwt)

SDK Reference

Documentation Index

​Installation

​Quick Start

​Integration Flow

​Methods

​Core Methods

​generateToken()

​getInvitation()

​acceptInvitation()

​generateJwt()

​getInvitationsByTarget()

​revokeInvitation()

​acceptInvitations()

​deleteInvitationsByGroup()

​getInvitationsByGroup()

​deleteInvitationsByScope()

​getInvitationsByScope()

​reinvite()

​getAutojoinDomains()

​configureAutojoin()

​syncInternalInvitation()

​getEnvironments()

​getDeployments()

​Types

​InvitationTarget

​ScopeInput

​GroupInput

​InvitationScope

​InvitationGroup

​InvitationAcceptance

​InvitationResultBase

​InvitationResult

​AcceptUser

​AcceptInvitationRequest

​AcceptInvitationRequestLegacy

​SyncInternalInvitationRequest

​SyncInternalInvitationResponse

​User

​AutojoinDomain

​AutojoinDomainsResponse

​ConfigureAutojoinRequest

​Inviter

​GenerateTokenUser

​GenerateTokenData

​GenerateJwtOptions

​GenerateTokenOptions

​Environment

​DeploymentEnvironment

​Deployment

​WidgetConfigurationDistribution

​DeploymentWidget

​DeploymentWidgetConfiguration

​DeploymentResult

​GetDeploymentsParams

​Webhooks

​Setup

​Example

​Events

​Use Cases

​Error Handling

​Resources

Installation

Quick Start

Integration Flow

Methods

Core Methods

`generateToken()`

`getInvitation()`

`acceptInvitation()`

`generateJwt()`

`getInvitationsByTarget()`

`revokeInvitation()`

`acceptInvitations()`

`deleteInvitationsByGroup()`

`getInvitationsByGroup()`

`deleteInvitationsByScope()`

`getInvitationsByScope()`

`reinvite()`

`getAutojoinDomains()`

`configureAutojoin()`

`syncInternalInvitation()`

`getEnvironments()`

`getDeployments()`

Types

`InvitationTarget`

`ScopeInput`

`GroupInput`

`InvitationScope`

`InvitationGroup`

`InvitationAcceptance`

`InvitationResultBase`

`InvitationResult`

`AcceptUser`

`AcceptInvitationRequest`

`AcceptInvitationRequestLegacy`

`SyncInternalInvitationRequest`

`SyncInternalInvitationResponse`

`User`

`AutojoinDomain`

`AutojoinDomainsResponse`

`ConfigureAutojoinRequest`

`Inviter`

`GenerateTokenUser`

`GenerateTokenData`

`GenerateJwtOptions`

`GenerateTokenOptions`

`Environment`

`DeploymentEnvironment`

`Deployment`

`WidgetConfigurationDistribution`

`DeploymentWidget`

`DeploymentWidgetConfiguration`

`DeploymentResult`

`GetDeploymentsParams`

Webhooks

Setup

Example

Events

Use Cases

Error Handling

Resources