API reference · Invitations
Invite someone by email (a pending invitation to the same address is replaced)
/v1/orgs/{org_id}/invitationsEmails an invitation to join the organization with the given role, which may be no higher than your own. The invitee accepts it while signed in with that verified address, before expires_at.
Console session only: no API key can be granted the member:invite permission it needs. Requires the member:invite permission (a key's scope, or a role that includes it).
Request
| Header | Required | Description |
|---|---|---|
Idempotency-Key | no | Makes a retry safe: the same key and request within 24 hours return the original response (see Idempotency). The SDKs send one for you. |
Path parameters
org_idstringYour organization. The SDKs and the CLI fill it in from the API key.
ID with prefix org_
Body
JSON (application/json): CreateInvitationRequest.
emailstring (email)requiredEmail address to invite; the invitation is sent there
up to 320 characters
One of
owneradmindeveloperbillingviewer
Response
201 Invitation — The invitation (emailed to the invitee)
objectstringrequiredAlways `invitation`: the type of this object
One of
invitationidstringrequiredUnique ID (`inv_…`)
ID with prefix inv_
org_idstringrequiredOrganization it belongs to
ID with prefix org_
emailstringrequiredEmail address the invitation was sent to
rolestring | nullrequiredRole the invitee gets on accepting; null when none was recorded
One of
owneradmindeveloperbillingviewerstatusstringrequired`pending` (can still be accepted until `expires_at`), `accepted`, `rejected` or `canceled`
expires_atstring (date-time)requiredWhen it expires (null: never) (ISO 8601, UTC)
inviter_user_idstringrequiredID of the inviter user
inviterobject | nullrequiredWho sent the invitation
ShowHide 3 fields of
inviterobjectstringrequiredAlways `person`
One of
personidstringrequiredThe person’s user ID (`usr_…`)
namestring | nullrequiredTheir name as they set it; null when they are no longer a member of the organization
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
Example response
{
"object": "invitation",
"id": "inv_01jc5zq4m8k3v6x9t2w7r0b1e4",
"org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
"email": "string",
"role": "owner",
"status": "pending",
"expires_at": "2026-01-01T00:00:00.000Z",
"inviter_user_id": "string",
"inviter": {
"object": "person",
"id": "string",
"name": "string"
},
"created_at": "2026-01-01T00:00:00.000Z"
}Errors
Errors use the standard envelope. What this operation can answer:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
409 | conflict_error idempotency_in_progress | A request with the same Idempotency-Key is still running. |
422 | idempotency_error idempotency_key_reused | The Idempotency-Key was used with a different request. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |