Skip to content
Hayonix

API reference · Invitations

Invite someone by email (a pending invitation to the same address is replaced)

POST/v1/orgs/{org_id}/invitations
Console sessionmember:inviteOrganizationIdempotency-Key

Emails 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

Headers
HeaderRequiredDescription
Idempotency-KeynoMakes 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_idstring

    Your organization. The SDKs and the CLI fill it in from the API key.

    ID with prefix org_

Body

JSON (application/json): CreateInvitationRequest.

  • emailstring (email)required

    Email address to invite; the invitation is sent there

    up to 320 characters

  • roleRolerequired

    One ofowneradmindeveloperbillingviewer

Response

201 Invitation — The invitation (emailed to the invitee)

  • objectstringrequired

    Always `invitation`: the type of this object

    One ofinvitation

  • idstringrequired

    Unique ID (`inv_…`)

    ID with prefix inv_

  • org_idstringrequired

    Organization it belongs to

    ID with prefix org_

  • emailstringrequired

    Email address the invitation was sent to

  • rolestring | nullrequired

    Role the invitee gets on accepting; null when none was recorded

    One ofowneradmindeveloperbillingviewer

  • statusstringrequired

    `pending` (can still be accepted until `expires_at`), `accepted`, `rejected` or `canceled`

  • expires_atstring (date-time)required

    When it expires (null: never) (ISO 8601, UTC)

  • inviter_user_idstringrequired

    ID of the inviter user

  • inviterobject | nullrequired

    Who sent the invitation

    Show 3 fields of inviter
    • objectstringrequired

      Always `person`

      One ofperson

    • idstringrequired

      The person’s user ID (`usr_…`)

    • namestring | nullrequired

      Their name as they set it; null when they are no longer a member of the organization

  • created_atstring (date-time)required

    When it was created (ISO 8601, UTC)

Example response
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:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
409conflict_error idempotency_in_progressA request with the same Idempotency-Key is still running.
422idempotency_error idempotency_key_reusedThe Idempotency-Key was used with a different request.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.