Look up an invitation · Ownrecord docs

Shows what an invitation link offers: the organization, the role and scope, who invited, when it expires and its status. The invited address is shown in full only when you're signed in with it.

Who can call it: any signed-in user holding the token from the invitation link.

At a glance

REST: POST /api/v1/invitations/lookup
MCP tool: invitations_lookup
Operation ID: invitations.lookup
Scope: Platform
Permission: account:read
Risk tier: read
Dry run: Not supported
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the account:read scope
Since: M1

Request

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`token`	string	Yes

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"invitation_preview"`
`status`	one of `pending`, `accepted`, `revoked`, `expired`
`organization`	object
`organization.name`	string
`organization.slug`	string
`role`	one of `org_owner`, `org_admin`, `billing_admin`, `finance`, `tax_manager`, `support`, `developer`, `viewer`
`scope`	object
`scope.type`	one of `org`, `entity`, `brand`
`scope.name`	string or null
`email`	string
`emailMatches`	boolean
`invitedBy`	string or null
`expiresAt`	date-time

Examples

A pending invitation for the signed-in address

HTTP

POST /api/v1/invitations/lookup
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "token": "ExampleOnlyNotARealInvitationToken000000000"
}

Response (200):

JSON

{
  "object": "invitation_preview",
  "status": "pending",
  "organization": {
    "name": "Acme",
    "slug": "acme"
  },
  "role": "finance",
  "scope": {
    "type": "entity",
    "name": "Acme Digital d.o.o."
  },
  "email": "finance@acme.example",
  "emailMatches": true,
  "invitedBy": "Olivia Owner",
  "expiresAt": "2026-10-20T12:00:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	The token is malformed.	Fix the fields listed in `details.issues` and send the request again.
`invitation_invalid`	404	No invitation has this token.	Check that you opened the whole link from the invitation email, or ask the person who invited you to send a new invitation.
`permission_denied`	403	The caller isn't a signed-in user.	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, resource_not_found, idempotency_key_required, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

A pending invitation for the signed-in address#

Errors#