Java SDK - Vortex

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.

Installation

<dependency>
  <groupId>com.vortexsoftware</groupId>
  <artifactId>vortex-java-sdk</artifactId>
</dependency>

Quick Start

Generate a secure token for Vortex components

VortexClient client = new VortexClient(System.getenv("VORTEX_API_KEY"));

GenerateTokenPayload payload = new GenerateTokenPayload()
    .setUser(new TokenUser().setId("user-123").setEmail("user@example.com"));

String token = client.generateToken(payload);

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 Java project

<dependency>
<groupId>com.vortexsoftware</groupId>
<artifactId>vortex-java-sdk</artifactId>
</dependency>

Initialize the client

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

import com.vortexsoftware.sdk.VortexClient;

VortexClient client = new VortexClient(System.getenv("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

String token = client.generateToken(
new GenerateTokenPayload().setUser(
    new TokenUser().setId(currentUser.getId())
)
);

Pass the token to your frontend

Include the token in your page response or API response

response.put("vortexToken", token);

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()`

Generate a signed token for use with Vortex widgets

generateToken(GenerateTokenPayload payload): String

Parameters:

Name	Type	Required	Description
`payload`	`GenerateTokenPayload`	✓	Data to sign (user, component, scope, vars, etc.)

Returns: String — Signed JWT token string

`getInvitation()`

Get a specific invitation by ID

getInvitation(String invitationId): InvitationResult

Parameters:

Name	Type	Required	Description
`invitationId`	`String`	✓	The invitation ID

Returns: InvitationResult — The invitation details

Example

InvitationResult invitation = client.getInvitation("inv-123");
System.out.println("Status: " + invitation.getStatus());

`acceptInvitation()`

Accept a single invitation (recommended method)

acceptInvitation(String invitationId, AcceptUser user): InvitationResult

Parameters:

Name	Type	Required	Description
`invitationId`	`String`	✓	Single invitation ID to accept
`user`	`AcceptUser`	✓	User object with email and/or phone

Returns: InvitationResult — The accepted invitation result

Example

AcceptUser user = new AcceptUser()
.setEmail("user@example.com")
.setName("John Doe");
InvitationResult result = client.acceptInvitation("inv-123", user);

Additional Methods

`generateJwt()`

Generate a JWT using the same algorithm as the Node.js SDK

generateJwt(Object> params): String

Parameters:

Name	Type	Required	Description
`params`	`Object>`	✓	Map containing “user” key with User object

Returns: String — JWT token string

`getInvitationsByTarget()`

Get invitations by target (email, username, phoneNumber)

getInvitationsByTarget(String targetType, String targetValue): List<InvitationResult>

Parameters:

Name	Type	Required	Description
`targetType`	`String`	✓	Type of target (email, phone, etc.)
`targetValue`	`String`	✓	The target value

Returns: List<InvitationResult> — List of invitations

`revokeInvitation()`

Revoke (delete) an invitation

revokeInvitation(String invitationId): void

Parameters:

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

Returns: void

`deleteInvitationsByScope()`

Delete all invitations for a specific scope

deleteInvitationsByScope(String scopeType, String scope): void

Parameters:

Name	Type	Required	Description
`scopeType`	`String`	✓	The scope type (organization, team, etc.)
`scope`	`String`	✓	The scope identifier

Returns: void

`getInvitationsByScope()`

Get all invitations for a specific scope

getInvitationsByScope(String scopeType, String scope): List<InvitationResult>

Parameters:

Name	Type	Required	Description
`scopeType`	`String`	✓	The scope type (organization, team, etc.)
`scope`	`String`	✓	The scope identifier

Returns: List<InvitationResult> — List of invitations for the scope

`reinvite()`

Reinvite a user (send invitation again)

reinvite(String invitationId): InvitationResult

Parameters:

Name	Type	Required	Description
`invitationId`	`String`	✓	The invitation ID to reinvite

Returns: InvitationResult — The reinvited invitation result

`getAutojoinDomains()`

Get autojoin domains configured for a specific scope

getAutojoinDomains(String scopeType, String scope): 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: AutojoinDomainsResponse — AutojoinDomainsResponse with autojoin domains and invitation

`configureAutojoin()`

Configure autojoin domains for a specific scope

configureAutojoin(ConfigureAutojoinRequest request): AutojoinDomainsResponse

Parameters:

Name	Type	Required	Description
`request`	`ConfigureAutojoinRequest`	✓	The configure autojoin request

Returns: AutojoinDomainsResponse — AutojoinDomainsResponse with updated autojoin domains

Types

Type Definitions

`GenerateTokenPayload`

Field	Type	Description
`user`	`TokenUser`	The authenticated user who will be using the Vortex component. Required for most operations to attribute invitations correctly.
`component`	`String`	Component ID to generate token for (from your Vortex dashboard). If not specified, uses the default component for your account.
`trigger`	`String`	Trigger context for the invitation (e.g., “signup”, “share-button”, “referral-page”). Used for analytics to track which UI elements drive the most invitations.
`embed`	`String`	Embed mode identifier for embedded invitation widgets. Determines how the component renders in your UI.
`scope`	`String`	Scope identifier to restrict invitations to a specific team/org/workspace. Format: “scopeType:scopeId” (e.g., “team:team-123”).
`vars`	`Map<String, Object>`	Custom variables to pass to the component for template rendering. These can be used in email templates and invitation messages.

`TokenUser`

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”). If not provided, falls back to email or a generic message.
`email`	`String`		User’s email address. Used for reply-to in invitation emails and shown to recipients so they know who invited them.
`avatarUrl`	`String`		URL to user’s avatar image. Displayed in invitation emails and widgets to personalize the invitation experience.
`adminScopes`	`List<String>`		List of scope IDs where this user has admin privileges. Admins can manage invitations and view analytics for these scopes. Format: [“scopeType:scopeId”, …] (e.g., [“team:team-123”, “org:org-456”]).
`allowedEmailDomains`	`List<String>`		Restrict invitations to specific email domains. If set, users can only invite people with emails matching these domains. Useful for enterprise accounts (e.g., [“acme.com”, “acme.co.uk”]).

`AcceptUser`

Field	Type	Description
`email`	`String`	Email address of the user accepting the invitation. At least one of email or phone is required.
`phone`	`String`	Phone number of the user accepting the invitation. At least one of email or phone is required. Include country code (e.g., “+1555123456”).
`name`	`String`	Display name of the accepting user. Used in notifications to the inviter (e.g., “John Doe accepted your invitation”).
`isExisting`	`Boolean`	Whether the accepting user was already registered in your system. Set to true for existing users, false for new signups, null if unknown. Used for analytics to track new vs existing user conversion rates.

`InvitationResult`

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`	`Map<String, Object>`		Invitation form data submitted by the user, including invitee identifiers (such as email addresses, phone numbers, or internal IDs) and the values of any custom fields.
`configurationAttributes`	`Map<String, Object>`		Deprecated: Use formSubmissionData instead. Contains the same data.
`attributes`	`Map<String, Object>`		Custom attributes attached to this invitation
`createdAt`	`String`		ISO 8601 timestamp when the invitation was created
`deactivated`	`boolean`	✓	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: PERSONAL (1:1) or BROADCAST (1:many)
`modifiedAt`	`String`		ISO 8601 timestamp of last modification
`status`	`InvitationStatus`		Current status: CREATED, DELIVERED, CLICKED, ACCEPTED, or EXPIRED
`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, may be null)
`scope`	`String`		Primary scope identifier (e.g., “team-123”)
`scopeType`	`String`		Type of the primary scope (e.g., “team”, “organization”)
`expired`	`boolean`	✓	Whether this invitation has passed its expiration date
`expires`	`String`		ISO 8601 timestamp when this invitation expires
`metadata`	`Map<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`

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`

Represents a group associated with an invitation. This matches the MemberGroups table structure from the API response.

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

`AutojoinDomain`

Represents an 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”)

`CreateInvitationScope`

Field	Type	Required	Description
`type`	`String`	✓	Scope type (e.g., “team”, “organization”, “workspace”)
`groupId`	`String`		Your internal scope/group identifier
`name`	`String`		Display name shown to invitees (e.g., “Engineering Team”)

`CreateInvitationTarget`

Field	Type	Required	Description
`type`	`CreateInvitationTargetType`	✓	Delivery channel: EMAIL, PHONE, SHARE (link), 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)

`Group`

Field	Type	Required	Description
`type`	`String`	✓	Scope type (e.g., “team”, “organization”, “workspace”)
`id`	`String`	✓	Legacy scope identifier. Use scopeId instead.
`scope`	`String`		Your internal scope/group identifier (preferred over id)
`name`	`String`		Display name for the scope (e.g., “Engineering Team”)

`Identifier`

Represents an 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.)

`InvitationAcceptance`

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
`targetType`	`String`		How the recipient was identified: “email” or “phone”
`targetValue`	`String`		The email or phone number of the person who accepted
`identifiers`	`Map<String, String>`		Additional identifiers for the accepting user (e.g., external IDs)

`Inviter`

Field	Type	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

`JWTPayload`

Field	Type	Description
`userId`	`String`	Your internal user ID (required - used for invitation attribution)
`userEmail`	`String`	User’s email address (preferred format for user identification)
`userIsAutojoinAdmin`	`Boolean`	Whether user can manage autojoin settings for their scopes
`identifiers`	`List<Identifier>`	Legacy: List of user identifiers. Use userEmail instead.
`groups`	`List<Group>`	Legacy: List of groups/scopes. Use scope parameter in generateToken instead.
`role`	`String`	Legacy: User role. No longer used.

`UnfurlConfig`

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)

`User`

Field	Type	Required	Description
`id`	`String`	✓	Your internal user ID (required for invitation attribution)
`email`	`String`		User’s email address (used for identification and reply-to)
`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”])

`VortexAnalyticsEvent`

Field	Type	Required	Description
`id`	`String`	✓	Unique identifier for this analytics event
`name`	`String`		Event name (e.g., “widget.opened”, “invite.sent”, “link.clicked”)
`accountId`	`String`		Your Vortex account ID
`organizationId`	`String`		Organization ID if using multi-org setup
`projectId`	`String`		Project ID the event belongs to
`environmentId`	`String`		Environment ID (production, staging, etc.)
`deploymentId`	`String`		Deployment ID the event is associated with
`widgetConfigurationId`	`String`		Widget configuration ID that generated this event
`foreignUserId`	`String`		Your internal user ID who triggered the event
`sessionId`	`String`		Client session ID for grouping related events
`payload`	`Map<String, Object>`		Event-specific payload data
`platform`	`String`		Platform: “web”, “ios”, “android”, “react-native”
`segmentation`	`String`		A/B test segmentation identifier
`timestamp`	`String`		ISO 8601 timestamp when the event occurred

`VortexWebhookEvent`

Field	Type	Required	Description
`id`	`String`	✓	Unique identifier for this webhook event
`type`	`String`	✓	Event type (e.g., “invitation.accepted”, “member.created”)
`timestamp`	`String`		ISO 8601 timestamp when the event occurred
`accountId`	`String`		Your Vortex account ID
`environmentId`	`String`		Environment ID (production, staging, etc.)
`sourceTable`	`String`		Internal: database table that triggered this event
`operation`	`String`		Database operation: “INSERT”, “UPDATE”, or “DELETE”
`data`	`Map<String, Object>`		Event payload containing the relevant entity data

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

Spring Boot webhook handler

import com.vortexsoftware.sdk.VortexWebhooks;
import org.springframework.web.bind.annotation.*;

@RestController
public class WebhookController {
    private final VortexWebhooks webhooks = new VortexWebhooks(
        System.getenv("VORTEX_WEBHOOK_SECRET")
    );

    @PostMapping("/webhooks/vortex")
    public Map<String, Object> handleWebhook(
        @RequestBody String body,
        @RequestHeader("X-Vortex-Signature") String signature
    ) {
        try {
            // Verify the signature
            if (!webhooks.verifySignature(body, signature)) {
                throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Invalid signature");
            }

            // Parse the event
            WebhookEvent event = webhooks.parseEvent(body);

            switch (event.getType()) {
                case "invitation.accepted":
                    // User accepted an invitation — activate their account
                    System.out.println("Accepted: " + event.getData().getTargetEmail());
                    break;
                case "member.created":
                    // New member joined via invitation
                    System.out.println("New member: " + event.getData());
                    break;
            }

            return Map.of("received", true);
        } catch (Exception e) {
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "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
`VortexWebhookSignatureException`	Thrown when webhook signature verification fails. Check that you are using the raw request body and the correct signing secret.
`VortexException`	Thrown for validation errors (e.g., missing API key, invalid parameters) or API failures

SDK Reference

Documentation Index

​Installation

​Quick Start

​Integration Flow

​Methods

​Core Methods

​generateToken()

​getInvitation()

​acceptInvitation()

​generateJwt()

​getInvitationsByTarget()

​revokeInvitation()

​deleteInvitationsByScope()

​getInvitationsByScope()

​reinvite()

​getAutojoinDomains()

​configureAutojoin()

​Types

​GenerateTokenPayload

​TokenUser

​AcceptUser

​InvitationResult

​InvitationTarget

​InvitationScope

​AutojoinDomain

​CreateInvitationScope

​CreateInvitationTarget

​Group

​Identifier

​InvitationAcceptance

​Inviter

​JWTPayload

​UnfurlConfig

​User

​VortexAnalyticsEvent

​VortexWebhookEvent

​Webhooks

​Setup

​Example

​Events

​Use Cases

​Error Handling

​Resources

Installation

Quick Start

Integration Flow

Methods

Core Methods

`generateToken()`

`getInvitation()`

`acceptInvitation()`

`generateJwt()`

`getInvitationsByTarget()`

`revokeInvitation()`

`deleteInvitationsByScope()`

`getInvitationsByScope()`

`reinvite()`

`getAutojoinDomains()`

`configureAutojoin()`

Types

`GenerateTokenPayload`

`TokenUser`

`AcceptUser`

`InvitationResult`

`InvitationTarget`

`InvitationScope`

`AutojoinDomain`

`CreateInvitationScope`

`CreateInvitationTarget`

`Group`

`Identifier`

`InvitationAcceptance`

`Inviter`

`JWTPayload`

`UnfurlConfig`

`User`

`VortexAnalyticsEvent`

`VortexWebhookEvent`

Webhooks

Setup

Example

Events

Use Cases

Error Handling

Resources