Invite someone to the organization

Invites a person by email with a role and a scope (the whole organization, one legal entity or one brand). They accept by signing in with that address and opening the link; the invitation expires after 7 days. Live-mode access follows the role (developers start without it; change it after they join).

Ownrecord emails the invitation link to the address right after the change is saved. The response also contains the invitation token (link: /console/invitations/{token}), once: only a hash is stored.

You can't invite anyone with more access than you have. A pending invitation reserves a seat: members plus pending invitations count against the plan's members.max. Needs members:admin and a signed-in member (the invitation says who invited; API keys can't invite). A security-tier change.

At a glance

REST: POST /api/v1/invitations
MCP tool: invitations_create
Operation ID: invitations.create
Scope: Organization
Permission: members:admin
Risk tier: security
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the members:admin scope
Since: M1

Request

Body

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

Field	Type	Required
`email`	string	Yes
`role`	one of `org_owner`, `org_admin`, `billing_admin`, `finance`, `tax_manager`, `support`, `developer`, `viewer`	Yes
`scope`	object	Yes

Response

201 Created with a JSON object:

Field	Type	Description
`id`	`invt_…` ID
`object`	`"invitation"`
`orgId`	`org_…` ID
`email`	string
`role`	one of `org_owner`, `org_admin`, `billing_admin`, `finance`, `tax_manager`, `support`, `developer`, `viewer`
`scope`	object
`status`	one of `pending`, `accepted`, `revoked`, `expired`
`expiresAt`	date-time
`invitedBy`	`usr_…` ID
`acceptedAt`	date-time or null
`revokedAt`	date-time or null
`createdAt`	date-time
`token`	string

Examples

Invite a finance colleague for one entity

HTTP

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

{
  "email": "finance@acme.example",
  "role": "finance",
  "scope": {
    "type": "entity",
    "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2"
  }
}

Response (201):

JSON

{
  "id": "invt_01m4tx5nj8emwbyf7y9vcf47x8",
  "object": "invitation",
  "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
  "email": "finance@acme.example",
  "role": "finance",
  "scope": {
    "type": "entity",
    "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2"
  },
  "status": "pending",
  "expiresAt": "2026-10-20T12:00:00.000Z",
  "invitedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
  "acceptedAt": null,
  "revokedAt": null,
  "createdAt": "2026-10-13T12:00:00.000Z",
  "token": "ExampleOnlyNotARealInvitationToken000000000"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	The email, role or scope is malformed, or the role isn't allowed at the scope.	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	The scope's entity or brand doesn't exist in the organization.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`role_not_grantable`	403	The role and scope give more access than you have.	Ask an organization owner to grant this role and scope, or pick a role and scope within your own access.
`membership_exists`	409	The person is already a member at this scope.	Change the role of the existing membership instead of adding another one.
`invitation_exists`	409	The person already has a pending invitation at this scope.	Ask them to use the invitation they have, or revoke it and invite them again.
`entitlement_required`	403	Members and pending invitations already fill `members.max`.	Upgrade the organization's plan, or remove something to get back under the limit.
`permission_denied`	403	You can't manage members of this organization, or the caller is an API key.	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, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

Invite a finance colleague for one entity#

Errors#