Skip to main content
GET
/
api
/
v1
/
invitations
/
{invitationId}
Get an invitation by ID
curl --request GET \
  --url https://api.example.com/api/v1/invitations/{invitationId} \
  --header 'x-api-key: <api-key>'
{
  "id": "invitation-12345",
  "accountId": "account-12345",
  "attributes": {},
  "clickThroughs": 5,
  "configurationAttributes": {},
  "createdAt": "2023-10-01T12:00:00Z",
  "deactivated": false,
  "deliveryCount": 3,
  "deliveryTypes": [
    "email",
    "phone"
  ],
  "foreignCreatorId": "creator-12345",
  "invitationType": "single_use",
  "modifiedAt": "2023-10-01T12:00:00Z",
  "status": "queued",
  "target": [
    {
      "type": "email",
      "value": "foo@bar.com"
    }
  ],
  "views": 10,
  "widgetConfigurationId": "widget-12345",
  "deploymentId": "deployment-12345",
  "projectId": "project-67890",
  "groups": [
    {
      "type": "workspace",
      "id": "workspace-12345",
      "name": "Development Team"
    }
  ],
  "accepts": [
    {
      "id": "accept-12345",
      "status": "accepted"
    }
  ],
  "scope": "6b366c56-c0a9-4689-b763-20c890481bc8",
  "scopeType": "project",
  "expired": false,
  "source": "email",
  "subtype": "pymk",
  "expires": "2023-11-01T12:00:00Z",
  "metadata": {
    "customerId": "12345",
    "source": "web"
  },
  "passThrough": "eyJhbGciOiJBMjU2R0NNIiwiZW5jIjoiQTI1NkdDTSJ9..."
}

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
invitationId
string
required

The ID of the invitation

Response

​
id
string
required

The ID of the invitation

Example:

"invitation-12345"

​
accountId
string
required

The ID of the account associated with the invitation

Example:

"account-12345"

​
attributes
object
required

Various attributes of the invitation, none exist at the moment, but this acts as a placeholder for future use

​
clickThroughs
number
required

The number of times the invitation has been clicked

Example:

5

​
configurationAttributes
object
required

The configuration attributes for the invitation. Includes raw data from widgets.

Example:
{}
​
createdAt
string<date-time>
required

The date and time when the invitation was created

Example:

"2023-10-01T12:00:00Z"

​
deactivated
boolean
required

Indicates whether the invitation has been deactivated

Example:

false

​
deliveryCount
number
required

The number of times the invitation has been delivered. For example, for email invitations this would be the invitation email plus the total number of reminders the invitee received.

Example:

3

​
deliveryTypes
string[]
required

The types of delivery methods used for the invitation. Valid values: email, phone, share, internal

Example:
["email", "phone"]
​
foreignCreatorId
string
required

The inviter’s ID in your system.

Example:

"creator-12345"

​
invitationType
enum<string>
required

The type of the invitation. A single_use invitation (e.g., email invitation) can only be accepted once. A multi_use invitation (e.g., shareable links) can be accepted multiple times. And autojoin allows people to join based on their email domain.

Available options:
single_use,
multi_use,
autojoin
Example:

"single_use"

​
modifiedAt
string<date-time>
required

The date and time when the invitation was last modified

Example:

"2023-10-01T12:00:00Z"

​
status
enum<string>
required

The current status of the invitation

Available options:
queued,
sending,
delivered,
accepted,
shared,
unfurled,
accepted_elsewhere,
sent
Example:

"queued"

​
target
object[]
required

The target(s) for the invitation, such as email or phone

Example:
[{ "type": "email", "value": "foo@bar.com" }]
​
views
number
required

The number of times the invitation has been viewed

Example:

10

​
widgetConfigurationId
string
required

The ID of the widget configuration associated with the invitation

Example:

"widget-12345"

​
deploymentId
string
required

The ID of the deployment associated with the invitation

Example:

"deployment-12345"

​
projectId
string
required

The ID of the project associated with the invitation

Example:

"project-67890"

​
groups
object[]
required

DEPRECATED: The groups associated with the invitation, such as workspaces or teams

Example:
[
  {
    "type": "workspace",
    "id": "workspace-12345",
    "name": "Development Team"
  }
]
​
accepts
object[]
required

The acceptance details for the invitation

Example:
[
  {
    "id": "accept-12345",
    "status": "accepted"
  }
]
​
scope
string
required

Defines the context for the invitation, and should be the ID in your system of the entity to which the invitation applies (e.g., workspace, org, etc.).

Example:

"6b366c56-c0a9-4689-b763-20c890481bc8"

​
scopeType
string
required

The name of the entity that the ID passed in scope refers to (e.g., “workspace”, “organization”, “team”). Allows you to establish context for an invitation if you have multiple types of entities to which someone can be invited.

Example:

"project"

​
expired
boolean
required

Indicates whether the invitation has expired based on the expiry configuration. Always false if the invitation has no expiry configured.

Example:

false

​
source
string

The source of the invitation (email, phone, internal, share, etc.)

Example:

"email"

​
subtype
string

Customer-defined subtype for categorizing this invitation (e.g., pymk, find-friends, profile-button)

Example:

"pymk"

​
expires
string<date-time>

The date and time when the invitation will expire or has expired. Only present if the invitation has an expiry configuration (expiryDays > 0).

Example:

"2023-11-01T12:00:00Z"

​
metadata
object

Information passed to Vortex on the metadata parameter in the client code when the invitation was created is returned here.

Example:
{ "customerId": "12345", "source": "web" }
​
passThrough
string

Encrypted passthrough data from the JWT, passed through without decryption. Can be used to securely pass context from the invitation creator to the acceptance flow.

Example:

"eyJhbGciOiJBMjU2R0NNIiwiZW5jIjoiQTI1NkdDTSJ9..."