Skip to main content
POST
/
api
/
v1
/
invitations
Create an invitation
curl --request POST \
  --url https://api.example.com/api/v1/invitations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "widgetConfigurationId": "550e8400-e29b-41d4-a716-446655440000",
  "target": {
    "type": "email",
    "value": "[email protected]"
  },
  "inviter": {
    "userId": "user-12345",
    "userEmail": "[email protected]",
    "userName": "John Doe",
    "userAvatarUrl": "https://example.com/avatar.jpg"
  },
  "groups": [
    {
      "type": "team",
      "groupId": "team-abc123",
      "name": "Engineering Team"
    }
  ],
  "source": "api",
  "templateVariables": {
    "companyName": "Acme Inc",
    "teamName": "Engineering"
  },
  "metadata": {
    "referralCode": "ABC123",
    "campaign": "summer2024"
  },
  "unfurlConfig": {
    "title": "Join our team!",
    "description": "You have been invited to collaborate",
    "image": "https://example.com/og-image.png",
    "type": "website",
    "siteName": "Acme App"
  }
}
'
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "shortLink": "https://vrtx.link/i/abc123",
  "status": "queued",
  "createdAt": "2024-01-15T12:00:00Z"
}

Authorizations

​
x-api-key
string
header
required

Body

application/json

Invitation details

​
widgetConfigurationId
string
required

The ID of the widget configuration to use for this invitation

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
target
object
required

The target of the invitation (who is being invited)

​
inviter
object
required

Information about the user creating the invitation

​
groups
object[]

Groups/scopes to associate with this invitation

​
source
string

The source of the invitation for analytics (e.g., "api", "backend", "pymk")

Example:

"api"

​
templateVariables
object

Template variables for email customization

Example:
{
  "companyName": "Acme Inc",
  "teamName": "Engineering"
}
​
metadata
object

Custom metadata to attach to the invitation (passed through to webhooks)

Example:
{
  "referralCode": "ABC123",
  "campaign": "summer2024"
}
​
unfurlConfig
object

Link unfurl (Open Graph) configuration for social/messaging previews

Response

Successfully created invitation

​
id
string
required

The ID of the created invitation

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
shortLink
string
required

The short link for the invitation (if applicable)

Example:

"https://vrtx.link/i/abc123"

​
status
string
required

The status of the invitation

Example:

"queued"

​
createdAt
string
required

When the invitation was created

Example:

"2024-01-15T12:00:00Z"