Organisation invite API

POST /v1/organisations/{id}/invites — find or create an identity, add membership, and issue a first-password or sign-in URL

Invite a member by email. The identity is found or created, organisation membership is written, and the response always includes action_url for the invitee.


Method	`POST`
Path	`/v1/organisations/{id}/invites`
Scope	`organisations:write`
Success	`201 Created`

{id} is the organisation UUID or slug.

For the product flow, hosted /invite behaviour, and send: false, see Organisation invites.

Request

POST /v1/organisations/{id}/invites
Authorization: Bearer wocha_mgmt_...
Content-Type: application/json

{
  "email": "alex@acme.com",
  "role": "member",
  "name": { "first": "Alex", "last": "Cole" },
  "return_to": "https://app.example.com/api/auth/login",
  "send": false,
  "require_mfa": true,
  "inviter_name": "Jordan"
}

Field	Type	Default	Description
`email`	string	required	Invitee email (stored lower-case)
`role`	`owner` \| `admin` \| `member`	`member`	Organisation role
`name.first`	string	—	Given name on a newly created identity
`name.last`	string	—	Family name on a newly created identity
`return_to`	https URI	—	Allowlisted URL after password / sign-in. Prefer your OAuth start URL
`send`	boolean	`true`	When `false`, do not send Wocha mail; still return `action_url`
`require_mfa`	boolean	`true`	Require TOTP enrolment on the hosted `/invite` flow
`inviter_name`	string	—	Optional name shown in the Wocha invite email
`branding_org_id`	string	—	Id or slug of another organisation in your tenant whose email template, logo/colours, sender and hosted invite page brand this invite. Membership stays on the path organisation; the invitee's later auth mail keeps the brand

Response `201`

{
  "identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organisation_id": "11111111-2222-3333-4444-555555555555",
  "role": "member",
  "created": true,
  "emailed": false,
  "action_url": "https://id.wocha.ai/invite?flow=…&token=…&return_to=…&org_id=acme&require_mfa=true",
  "expires_at": "2026-08-22T12:00:00.000Z",
  "return_to": "https://app.example.com/api/auth/login"
}

Field	Type	Description
`identity_id`	uuid	Invitee identity
`organisation_id`	uuid	Real organisation UUID (not the slug you may have passed)
`role`	string	Role that was assigned
`created`	boolean	`true` when this call created the identity
`emailed`	boolean	`true` only when Wocha mail was accepted by the provider
`action_url`	uri	Hosted `/invite` magic link, or `/login` if they already have a password
`expires_at`	date-time	Present when a first-password link was issued (typically 24 hours)
`provider`	string	Email provider when `emailed` is true
`return_to`	uri	Echo of the allowlisted `return_to`

action_url is always returned, including when send is false and when Wocha mail fails after the member already exists.

Behaviour

Condition	Result
Unknown email	Identity created (quota / MAU checked), then invited
Email exists in this tenant	Existing identity is reused; `created` is false
Email exists in another tenant	`409 conflict`
Identity has no password	`action_url` is `/invite` with `flow`, `token`, `org_id`, `require_mfa`
Identity already has a password	`action_url` is `/login?org_id=&return_to=`
`send: true` and Resend succeeds	`emailed: true`
`send: true` and Resend fails	`201` with `emailed: false` and `action_url`
`send: false`	No Wocha email; `emailed: false`

This endpoint does not send the recovery / forgot-password template.

SDKs

await wocha.organisations.invite(orgId, {
  email: "alex@example.com",
  role: "member",
  send: false,
  return_to: "https://app.example.com/api/auth/login",
});

client.organisations.invite(
    org_id,
    email="alex@example.com",
    role="member",
    send=False,
    return_to="https://app.example.com/api/auth/login",
)

client.Organisations.Invite(ctx, orgID, &wocha.OrgMemberInviteParams{
    Email:    "alex@example.com",
    Role:     "member",
    ReturnTo: "https://app.example.com/api/auth/login",
})

Loading playground…

Errors

Status	Code	When
`400`	`invalid_request`	Body is not JSON
`400`	`validation_error`	Missing email, invalid role, or `return_to` not allowlisted
`401`	`unauthorized`	Missing or invalid credentials
`403`	`forbidden`	Missing `organisations:write`
`404`	`not_found`	Organisation not found
`409`	`conflict`	Email belongs to another tenant
`502`	`upstream_error`	Identity service could not create the user or link
`503`	`service_unavailable`	Identity service is not configured

Organisation invite API

Request

Response `201`

Behaviour

SDKs

Errors

See also

On this page

Organisation invite API

Request

Response 201

Behaviour

SDKs

Errors

See also

On this page

Response `201`