Skip to main content
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

composer require teamvortexsoftware/vortex-php-sdk

Quick Start

Generate a secure token for Vortex components
<?php
use TeamVortexSoftware\VortexSDK\VortexClient;

$client = new VortexClient(getenv('VORTEX_API_KEY'));

// Generate a token for the current user
$token = $client->generateToken([
    'user' => ['id' => 'user-123', 'email' => 'user@example.com']
]);

// Pass the token to your frontend component

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

Install the backend SDK

Add this SDK to your PHP project
composer require teamvortexsoftware/vortex-php-sdk
2

Initialize the client

Create a Vortex client with your API key (keep this on the server!)
<?php
use TeamVortexSoftware\VortexSDK\VortexClient;

$client = new VortexClient(getenv('VORTEX_API_KEY'));
3

Generate a token for the current user

When a user loads a page with a Vortex component, generate a signed token on your server
$token = $client->generateToken([
'user' => ['id' => $currentUser->id]
]);
4

Pass the token to your frontend

Include the token in your page response or API response
return response()->json(['vortexToken' => $token]);
5

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} />
6

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(array $payload, ?array $options = null): string
Parameters:
NameTypeRequiredDescription
payloadarrayData to sign (user, component, scope, vars, etc.)
options`arraynull`Optional configuration (expiresIn)
Returns: string — Signed JWT token
$vortex = new VortexClient($_ENV['VORTEX_API_KEY']);
$token = $vortex->generateToken(['user' => ['id' => 'user-123']]);
$token = $vortex->generateToken([
'component' => 'widget-abc',
'user' => ['id' => 'user-123', 'name' => 'Peter'],
'scope' => 'workspace_456',
'vars' => ['company_name' => 'Acme']
]);
$token = $vortex->generateToken(
['user' => ['id' => 'user-123']],
['expiresIn' => '1h']  // or 3600 for seconds
);
public function generateToken(array $payload, ?array $options = null): string

getInvitation()

Get a specific invitation by ID public function getInvitation(string $invitationId): array
getInvitation(string $invitationId): array
Parameters:
NameTypeRequiredDescription
invitationIdstringThe invitation ID
Returns: array — The invitation data

acceptInvitation()

Accept a single invitation (recommended method) This is the recommended method for accepting invitations.
acceptInvitation(string $invitationId, array $user): array
Parameters:
NameTypeRequiredDescription
invitationIdstringSingle invitation ID to accept
userarrayUser array with ‘email’/‘phone’/‘name’ keys
Returns: array — The accepted invitation result
$user = ['email' => 'user@example.com', 'name' => 'John Doe'];
$result = $client->acceptInvitation('inv-123', $user);
public function acceptInvitation(string $invitationId, array $user): array

getInvitationsByTarget()

Get invitations by target (email or sms) public function getInvitationsByTarget(string targetType,stringtargetType, string targetValue): array
getInvitationsByTarget(string $targetType, string $targetValue): array
Parameters:
NameTypeRequiredDescription
targetTypestringType of target (‘email’ or ‘phone’)
targetValuestringTarget value (email address or phone number)
Returns: array — List of invitations

revokeInvitation()

Revoke (delete) an invitation public function revokeInvitation(string $invitationId): array
revokeInvitation(string $invitationId): array
Parameters:
NameTypeRequiredDescription
invitationIdstringThe invitation ID to revoke
Returns: array — Success response

acceptInvitations()

Accept multiple invitations Supports three formats: 1. User array (preferred): [‘email’ => ’…’, ‘phone’ => ’…’, ‘name’ => ’…’] 2. Target array (deprecated): [‘type’ => ‘email’, ‘value’ => ’…’] 3. Array of targets (deprecated): [[‘type’ => ‘email’, ‘value’ => ’…’], …]
acceptInvitations(array $invitationIds, array $userOrTarget): array
Parameters:
NameTypeRequiredDescription
invitationIdsarrayList of invitation IDs to accept
userOrTargetarrayUser array with ‘email’/‘phone’/‘name’ keys, OR legacy target(s)
Returns: array — The accepted invitation result
$user = ['email' => 'user@example.com', 'name' => 'John Doe'];
$result = $client->acceptInvitations(['inv-123'], $user);
$target = ['type' => 'email', 'value' => 'user@example.com'];
$result = $client->acceptInvitations(['inv-123'], $target);
public function acceptInvitations(array $invitationIds, array $userOrTarget): array

deleteInvitationsByScope()

Delete all invitations for a specific group public function deleteInvitationsByScope(string scopeType,stringscopeType, string scope): array
deleteInvitationsByScope(string $scopeType, string $scope): array
Parameters:
NameTypeRequiredDescription
scopeTypestringThe group type
scopestringThe group ID
Returns: array — Success response

getInvitationsByScope()

Get all invitations for a specific group public function getInvitationsByScope(string scopeType,stringscopeType, string scope): array
getInvitationsByScope(string $scopeType, string $scope): array
Parameters:
NameTypeRequiredDescription
scopeTypestringThe group type
scopestringThe group ID
Returns: array — List of invitations for the group

reinvite()

Reinvite a user (send invitation again) public function reinvite(string $invitationId): array
reinvite(string $invitationId): array
Parameters:
NameTypeRequiredDescription
invitationIdstringThe invitation ID to reinvite
Returns: array — The reinvited invitation result

getAutojoinDomains()

Get autojoin domains configured for a specific scope
getAutojoinDomains(string $scopeType, string $scope): array
Parameters:
NameTypeRequiredDescription
scopeTypestringThe type of scope (e.g., “organization”, “team”, “project”)
scopestringThe scope identifier (customer’s group ID)
Returns: array — Response with ‘autojoinDomains’ array and ‘invitation’
$result = $client->getAutojoinDomains('organization', 'acme-org');
foreach ($result['autojoinDomains'] as $domain) {
echo "Domain: " . $domain['domain'] . "\n";
}
public function getAutojoinDomains(string $scopeType, string $scope): array

configureAutojoin()

Configure autojoin domains for a specific scope This 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(
        string $scope,
        string $scopeType,
        array $domains,
        string $componentId,
        ?string $scopeName = null,
        ?array $metadata = null
    ): array
Parameters:
NameTypeRequiredDescription
scopestringThe scope identifier (customer’s group ID)
scopeTypestringThe type of scope (e.g., “organization”, “team”)
domainsarrayArray of domain strings to configure for autojoin
componentIdstringThe component ID
scopeName`stringnull`Optional display name for the scope
metadata`arraynull`Optional metadata to attach to the invitation
Returns: array — Response with ‘autojoinDomains’ array and ‘invitation’
$result = $client->configureAutojoin(
'acme-org',
'organization',
['acme.com', 'acme.org'],
'component-123',
'Acme Corporation'
);
public function configureAutojoin(
string $scope,
string $scopeType,
array $domains,
string $componentId,
?string $scopeName = null,
?array $metadata = null
): array

Types

GenerateTokenPayload

Payload for generateToken() - used to generate secure tokens for Vortex components
FieldTypeRequiredDescription
userTokenUserThe authenticated user who will be using the Vortex component
componentstringComponent ID to generate token for (from your Vortex dashboard)
scopestringScope identifier to restrict invitations (format: “scopeType:scopeId”)
varsarrayCustom variables to pass to the component for template rendering

TokenUser

User data for token generation - represents the authenticated user sending invitations
FieldTypeRequiredDescription
idstringUnique identifier for the user in your system. Used to attribute invitations.
emailstringUser’s email address. Used for reply-to in invitation emails.
namestringDisplay name shown to invitation recipients (e.g., “John invited you”)
avatarUrlstringURL to user’s avatar image. Displayed in invitation emails and widgets.
adminScopesstring[]List of scope IDs where this user has admin privileges
allowedEmailDomainsstring[]Restrict invitations to specific email domains (e.g., [“acme.com”])

AcceptUser

User data for accepting invitations - identifies who accepted the invitation
FieldTypeRequiredDescription
emailstringEmail address of the accepting user. At least one of email or phone is required.
phonestringPhone number with country code. At least one of email or phone is required.
namestringDisplay name of the accepting user (shown in notifications to inviter)
isExistingboolWhether user was already registered. true=existing, false=new signup, null=unknown.

CreateInvitationTarget

Target specification when creating an invitation - where to send the invite
FieldTypeRequiredDescription
typestringDelivery channel: “email”, “phone”, “share”, or “internal”
valuestringTarget address: email address, phone number with country code, or internal user ID
namestringDisplay name of the recipient (used in email greetings)

CreateInvitationScope

Scope specification when creating an invitation - what group/team to invite into
FieldTypeRequiredDescription
typestringScope type (e.g., “team”, “organization”, “workspace”)
groupIdstringYour internal identifier for this scope/group
namestringDisplay name for the scope (shown in invitation emails)

Identifier

Email or phone identifier for looking up users
FieldTypeRequiredDescription
typestringIdentifier type: “email” or “phone”
valuestringThe email address or phone number (with country code for phone)

ConfigureAutojoinRequest

Request to configure autojoin domains for a scope
FieldTypeRequiredDescription
scopeTypestringType of scope (e.g., “team”, “workspace”)
scopeIdstringYour internal identifier for the scope
domainsstring[]List of email domains to enable autojoin for (e.g., [“acme.com”])

SyncInternalInvitationRequest

Request to sync an internal invitation (for tracking invitations made outside Vortex)
FieldTypeRequiredDescription
inviterIdstringYour internal user ID for the person who sent the invitation
targetCreateInvitationTargetThe invitation recipient
scopesCreateInvitationScope[]Scopes/groups the invitation grants access to

InvitationResult

Complete invitation details as returned by the Vortex API
FieldTypeRequiredDescription
idstringUnique identifier for this invitation
accountIdstringYour Vortex account ID
clickThroughsintNumber of times the invitation link was clicked
createdAtstringISO 8601 timestamp when the invitation was created
deactivatedboolWhether this invitation has been revoked or expired
deliveryCountintNumber of times the invitation was sent (including reminders)
deliveryTypesstring[]Channels used to deliver: “email”, “phone”, “share”, “internal”
foreignCreatorIdstringYour internal user ID for the person who created this invitation
invitationTypestringType: “single_use”, “multi_use”, or “autojoin”
statusstringCurrent status: queued, sending, sent, delivered, accepted, shared
targetInvitationTarget[]List of invitation recipients with their contact info and status
viewsintNumber of times the invitation page was viewed
groupsInvitationScope[]Scopes (teams/orgs) this invitation grants access to
expiredboolWhether this invitation has passed its expiration date
expiresstringISO 8601 timestamp when this invitation expires
inviterInviterInformation about who sent the invitation

InvitationTarget

Target recipient of an invitation (from API response)
FieldTypeRequiredDescription
typestringDelivery channel: “email”, “phone”, “share”, or “internal”
valuestringTarget address: email, phone number with country code, or share link ID
namestringDisplay name of the recipient
avatarUrlstringAvatar URL for the recipient
statusstringDelivery status for this specific target

InvitationScope

Scope/group that the invitation grants access to (from API response)
FieldTypeRequiredDescription
idstringVortex internal UUID for this scope record
accountIdstringYour Vortex account ID
groupIdstringYour internal scope/group identifier
typestringScope type (e.g., “team”, “organization”, “workspace”)
namestringDisplay name for the scope
createdAtstringISO 8601 timestamp when the scope was created

InvitationAcceptance

Details about an invitation acceptance event
FieldTypeRequiredDescription
idstringUnique identifier for this acceptance record
invitationIdstringID of the invitation that was accepted
emailstringEmail of the user who accepted
phonestringPhone of the user who accepted
namestringName of the user who accepted
isExistingboolWhether the user already had an account
createdAtstringISO 8601 timestamp when the acceptance occurred

Inviter

Information about the user who sent an invitation
FieldTypeRequiredDescription
idstringYour internal user ID for the inviter
emailstringEmail address of the inviter
namestringDisplay name of the inviter
avatarUrlstringAvatar URL of the inviter

AutojoinDomain

Autojoin domain configuration - users with matching email domains automatically join
FieldTypeRequiredDescription
idstringUnique identifier for this autojoin configuration
domainstringEmail domain that triggers autojoin (e.g., “acme.com”)

AutojoinDomainsResponse

Response from getAutojoinDomains()
FieldTypeRequiredDescription
domainsAutojoinDomain[]List of configured autojoin domains

SyncInternalInvitationResponse

Response from syncInternalInvitation()
FieldTypeRequiredDescription
invitationInvitationResultThe created or updated invitation
createdboolTrue if a new invitation was created, false if existing was updated

VortexWebhookEvent

Webhook event payload delivered to your endpoint
FieldTypeRequiredDescription
idstringUnique identifier for this webhook delivery
typestringEvent type (e.g., “invitation.accepted”, “member.created”)
timestampstringISO 8601 timestamp when the event occurred
dataarrayEvent-specific payload 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

  1. Go to your Vortex dashboard → Integrations → Webhooks tab
  2. Click “Add Webhook”
  3. Enter your endpoint URL (must be HTTPS in production)
  4. Copy the signing secret — you’ll use this to verify webhook signatures
  5. Select which events you want to receive

Example

Laravel webhook handler
<?php
use TeamVortexSoftware\VortexSDK\VortexWebhooks;
use Illuminate\Http\Request;

class WebhookController extends Controller
{
    public function handleVortex(Request $request)
    {
        $webhooks = new VortexWebhooks(env('VORTEX_WEBHOOK_SECRET'));
        
        $payload = $request->getContent();
        $signature = $request->header('X-Vortex-Signature');
        
        // Verify the signature
        if (!$webhooks->verifySignature($payload, $signature)) {
            return response()->json(['error' => 'Invalid signature'], 400);
        }
        
        // Parse the event
        $event = $webhooks->parseEvent($payload);
        
        switch ($event['type']) {
            case 'invitation.accepted':
                // User accepted an invitation — activate their account
                Log::info('Accepted: ' . json_encode($event['data']));
                break;
            case 'member.created':
                // New member joined via invitation
                Log::info('New member: ' . json_encode($event['data']));
                break;
        }
        
        return response()->json(['received' => true]);
    }
}

Events

EventDescription
invitation.createdA new invitation was created
invitation.acceptedAn invitation was accepted by the recipient
invitation.deactivatedAn invitation was deactivated (revoked or expired)
invitation.email.deliveredInvitation email was successfully delivered
invitation.email.bouncedInvitation email bounced (invalid address)
invitation.email.openedRecipient opened the invitation email
invitation.link.clickedRecipient clicked the invitation link
invitation.reminder.sentA reminder email was sent for a pending invitation
member.createdA new member was created from an accepted invitation
group.member.addedA member was added to a scope/group
deployment.createdA new deployment configuration was created
deployment.deactivatedA deployment was deactivated
abtest.startedAn A/B test was started
abtest.winner_declaredAn A/B test winner was declared
email.complainedRecipient 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

ErrorDescription
VortexWebhookSignatureExceptionThrown when webhook signature verification fails. Check that you are using the raw request body and the correct signing secret.
ExceptionThrown for validation errors (e.g., missing API key, invalid parameters)

Resources