DocsAPI reference

Invitations

Invite people to the organization by email.

Updated Sep 22, 2026

An invitation is addressed to one email and expires after seven days by default. The link is returned once, when the invitation is created or resent. Resending replaces the previous link and renews the expiry. Acceptance requires the invited email and creates a membership with the invitation's selected permissions.

See Membership management for invitations, joining and managing access in the app.

List invitations

GET/api/v1/invitationsSession or API keyRequires membership.invite

Returns the organization's invitations in every status, newest first.

Request

Parameters

Parameter	Type	Description
`limit`	query · integer	How many invitations to return. Defaults to 100.

Response

Response codes

Status	Body	Description
`200`	object	The invitations
`401`	ErrorResponse	You are not signed in
`403`	ErrorResponse	You cannot invite people

Response body200

invitationsarray<Invitation>required

Example

GET /api/v1/invitations

curl -X GET "$WITHHUMAN_URL/api/v1/invitations" \
  -H "Authorization: Bearer $WITHHUMAN_API_KEY"

200 response

{
  "invitations": [
    {
      "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "organization_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "email": "[email protected]",
      "grants": [
        {
          "scope_kind": "organization",
          "scope_id": "string",
          "permissions": [
            "string"
          ]
        }
      ],
      "invited_by_membership_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "status": "pending",
      "expires_at": "2026-09-08T12:02:11Z",
      "accepted_membership_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "created_at": "2026-09-08T12:02:11Z",
      "updated_at": "2026-09-08T12:02:11Z"
    }
  ]
}

Invite a person

POST/api/v1/invitationsSession cookieRequires membership.invite

Invite a member with explicit permission policies. Every permission must be held by the inviter at the selected scope or wider.

Request

Request body

emailemailrequired

Where to send the invitation. The person must accept with this address.

permission_policiesarray<PermissionPolicySpec>required

Response

Response codes

Status	Body	Description
`201`	InvitationWithURL	The invitation and its link. The link appears only in this response
`403`	ErrorResponse	You cannot invite people, or a grant exceeds what you hold or needs a fresher sign-in
`409`	ErrorResponse	A member or a pending invitation with this email already exists, or the organization is at its seat limit

Response body201

invitationInvitationrequired

An invitation to join the organization.

invite_urluri

The link to send to the person. It contains the invitation's secret token, appears only in this response, and only on a deployment with no email delivery configured.

Example

POST /api/v1/invitations

curl -X POST "$WITHHUMAN_URL/api/v1/invitations" \
  -b "withhuman_session=$WITHHUMAN_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]",
  "permission_policies": [
    {
      "scope_kind": "organization",
      "resource_ids": [
        "string"
      ],
      "permissions": [
        "string"
      ]
    }
  ]
}'

201 response

{
  "invitation": {
    "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "organization_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "email": "[email protected]",
    "grants": [
      {
        "scope_kind": "organization",
        "scope_id": "string",
        "permissions": [
          "string"
        ]
      }
    ],
    "invited_by_membership_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "status": "pending",
    "expires_at": "2026-09-08T12:02:11Z",
    "accepted_membership_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "created_at": "2026-09-08T12:02:11Z",
    "updated_at": "2026-09-08T12:02:11Z"
  },
  "invite_url": "https://example.com/webhooks/withhuman"
}

Resend an invitation

POST/api/v1/invitations/{id}/resendSession cookieRequires membership.invite

Issues a new link for a pending invitation and extends its expiry by seven days. The previous link stops working. The new link appears only in this response.

Request

Parameters

Parameter	Type	Description
`id`required	path · uuid	The invitation's id.

Response

Response codes

Status	Body	Description
`200`	InvitationWithURL	The invitation and its new link. The link appears only in this response
`403`	ErrorResponse	You cannot invite people
`404`	ErrorResponse	No such invitation, or it is no longer pending

Response body200

invitationInvitationrequired

An invitation to join the organization.

invite_urluri

The link to send to the person. It contains the invitation's secret token, appears only in this response, and only on a deployment with no email delivery configured.

Example

POST /api/v1/invitations/{id}/resend

curl -X POST "$WITHHUMAN_URL/api/v1/invitations/{id}/resend" \
  -b "withhuman_session=$WITHHUMAN_SESSION"

200 response

{
  "invitation": {
    "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "organization_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "email": "[email protected]",
    "grants": [
      {
        "scope_kind": "organization",
        "scope_id": "string",
        "permissions": [
          "string"
        ]
      }
    ],
    "invited_by_membership_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "status": "pending",
    "expires_at": "2026-09-08T12:02:11Z",
    "accepted_membership_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "created_at": "2026-09-08T12:02:11Z",
    "updated_at": "2026-09-08T12:02:11Z"
  },
  "invite_url": "https://example.com/webhooks/withhuman"
}

Revoke an invitation

DELETE/api/v1/invitations/{id}Session or API keyRequires membership.invite

Revokes a pending invitation. Its link stops working. A revoked invitation cannot be resent. Invite the person again instead.

Request

Parameters

Parameter	Type	Description
`id`required	path · uuid	The invitation's id.

Response

Response codes

Status	Body	Description
`204`		The invitation is revoked
`403`	ErrorResponse	You cannot invite people
`404`	ErrorResponse	No such invitation, or it is no longer pending

Example

DELETE /api/v1/invitations/{id}

curl -X DELETE "$WITHHUMAN_URL/api/v1/invitations/{id}" \
  -H "Authorization: Bearer $WITHHUMAN_API_KEY"