Skip to main content
POST
/
app-invites
Create an app invite
curl --request POST \
  --url https://api-dev.narrative.io/app-invites \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "base_url": "https://example.com/invite",
  "installation_id": 42,
  "data": {
    "key": "value"
  },
  "display_name": "Partner onboarding invite",
  "invitee_name": "Jane Smith",
  "tags": [
    "onboarding"
  ]
}
'
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "activated_at": null,
  "app": {
    "id": 100,
    "name": "Test App",
    "slug": "test-app"
  },
  "code": "abc123def456ghi789jkl012",
  "company": {
    "id": 42,
    "logo": "https://example.com/logo.png",
    "name": "Acme Corp"
  },
  "created_at": "2025-01-01T00:00:00Z",
  "data": {
    "key": "value"
  },
  "display_name": "Partner onboarding invite",
  "invitee_name": "Jane Smith",
  "status": "pending",
  "tags": [
    "onboarding",
    "partner"
  ],
  "updated_at": "2025-01-01T00:00:00Z",
  "url": "https://example.com/invite?code=abc123def456ghi789jkl012"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request body for creating a new app invite.

​
base_url
string
required

The base URL for the invite link. Must be a valid URI with a scheme and host.

Example:

"https://example.com/invite"

​
installation_id
integer<int64>
required

The ID of the app installation to create the invite for.

Example:

42

​
data
object

Optional custom JSON data to associate with the invite.

Example:
{ "key": "value" }
​
display_name
string | null

An optional display name for the invite. Maximum 1000 characters.

Example:

"Partner onboarding invite"

​
invitee_name
string | null

An optional name for the invitee. Maximum 1024 characters.

Example:

"Jane Smith"

​
tags
string[]

A list of tags to associate with the invite. Each tag is max 128 characters.

Example:
["onboarding"]

Response

Successfully created the app invite.

An app invite with full details.

​
id
string<uuid>
required

Unique identifier for the app invite.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
app
object
required

Summary information about an app.

Example:
{
  "id": 100,
  "name": "Test App",
  "slug": "test-app"
}
​
code
string
required

The 24-character invite code.

Example:

"abc123def456ghi789jkl012"

​
company
object
required

Summary information about a company.

Example:
{
  "id": 42,
  "logo": "https://example.com/logo.png",
  "name": "Acme Corp"
}
​
created_at
string<date-time>
required

The timestamp when the invite was created.

Example:

"2025-01-01T00:00:00Z"

​
status
enum<string>
required

The lifecycle status of an app invite.

Available options:
pending,
active,
archived
Example:

"pending"

​
updated_at
string<date-time>
required

The timestamp when the invite was last updated.

Example:

"2025-01-15T10:30:00Z"

​
url
string
required

The full invite URL constructed from the base URL and invite code.

Example:

"https://example.com/invite?code=abc123def456ghi789jkl012"

​
activated_at
string<date-time> | null

The timestamp when the invite was activated, or null if not yet activated.

Example:

"2025-01-15T10:30:00Z"

​
data
object

Custom JSON data associated with the invite.

Example:
{ "key": "value" }
​
display_name
string | null

An optional display name for the invite.

Example:

"Partner onboarding invite"

​
invitee_name
string | null

An optional name for the invitee. Maximum 1024 characters.

Example:

"Jane Smith"

​
tags
string[]

A list of tags associated with the invite. Each tag is max 128 characters.

Example:
["onboarding", "partner"]