Skip to content
Toriidocs

Search invitations using structured filters

POST
/api/server/v1/invitations/search
curl --request POST \
  --url 'https://api.toriiauth.eu/api/server/v1/invitations/search?limit=20&cursor=01931a73-8b00-7000-8000-000000000000' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "statuses": [ "PENDING" ], "emailSearch": "@example.com", "publicMetadata": { "tenant": { "id": "acme" }, "tags": [ "municipal" ] }, "privateMetadata": { "source": { "system": "crm" } } }'

Returns invitations matching every supplied filter. Status values are ORed within the status set. Email and both metadata filters are ANDed with it. Metadata uses PostgreSQL JSONB containment: nested objects may have additional keys, arrays may have additional values in any order, and JSON value types are significant. Private metadata may filter results but is never returned in the summary page.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer format: int32
default: 20 >= 1 <= 100

Maximum number of items in the returned page, from 1 through 100.

Example
20
cursor
string format: uuid

Cursor from the previous page’s nextCursor.

Example
01931a73-8b00-7000-8000-000000000000

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

All supplied dimensions are combined with AND semantics. Status values are ORed. Metadata values use JSONB containment.

object
statuses

Return invitations having any supplied lifecycle status.

Array<string>
unique items
Allowed values: PENDING ACCEPTED REVOKED EXPIRED
emailSearch

Literal case-insensitive email substring, at most 320 characters.

string | null
>= 1 characters <= 320 characters
Example
@example.com
publicMetadata

Public metadata that each result must contain.

object | null
Example
{
  "tenant": {
    "id": "acme"
  },
  "tags": [
    "municipal"
  ]
}
privateMetadata

Private metadata that each result must contain. This bag is never returned by search.

object | null
Example
{
  "source": {
    "system": "crm"
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

Page of matching invitation summaries without metadata.

Media typeapplication/json

A single page of results in a cursor-paginated list. Pass nextCursor as the cursor query parameter to fetch the following page.

object
items
required

Items in this page, in stable order.

Array<object>
object
id
required
string format: uuid
environmentId
required
string format: uuid
email
required
string
status
required
string
Allowed values: PENDING ACCEPTED REVOKED EXPIRED
expiresAt
required
string format: date-time
createdAt
required
string format: date-time
acceptedAt
string | null format: date-time
revokedAt
string | null format: date-time
nextCursor
required

Cursor to pass to fetch the next page. Null when this is the last page.

string | null format: uuid
hasMore
required

True if more pages are available (equivalent to nextCursor != null).

boolean
Example
{
  "items": [
    {
      "status": "PENDING"
    }
  ],
  "nextCursor": "01931a73-8b00-7000-8000-000000000000",
  "hasMore": true
}

400

Section titled “400”

Malformed or unknown filters, blank or overlong email search, metadata over 8 KB, a body over 24 KiB, an invalid cursor, or a limit outside 1 through 100.

Media typeapplication/problem+json
object
type
string format: uri
title
string
status
integer format: int32
detail
string
instance
string format: uri
properties
object
key
additional properties
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "properties": {
    "additionalProperty": "example"
  }
}

401

Section titled “401”

Missing or invalid secret key.

Media typeapplication/problem+json
object
type
string format: uri
title
string
status
integer format: int32
detail
string
instance
string format: uri
properties
object
key
additional properties
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "properties": {
    "additionalProperty": "example"
  }
}