Invite a user to an organization
Invite a user to the organization by email. If the email already belongs to a Kintsugi user, they are added to the organization directly and the response outcome is ADDED with the new user; otherwise an invitation is sent and outcome is INVITED with the pending invite. Idempotent on the email: if they are already a member, or already have an invitation outstanding, the existing one is returned unchanged with a 200 instead of 201, and their role is not modified. Use PATCH /users/{userId} to change a role. Requires a user credential (an API key is rejected) that is an Owner or Admin of the organization. Select a client organization with Organization-Id, or omit it for the partner firm team. Only an Owner can assign the Owner role (403). Applies to organizations using Kintsugi-managed sign-in; an organization federated to its own identity provider manages invitations there.
Authorization
Headers
Release date, as YYYY-MM-DD. Defaults to 2026-07-21.
Target client organization. Omit to manage the partner firm team when the bearer is an Owner or Admin of exactly one portfolio.
Target connection id; resolves to its organization.
Platform entity id; resolves to a connection's organization.
Optional source to disambiguate an Entity-Id.
Body
Email address of the user to invite or add to the organization.
Primary role to grant the user in the organization.
OWNERADMINMEMBEROptional additional role names to assign alongside the primary role.
Response
INVITED when the result is an invitation, ADDED when an existing user holds membership directly. Branch on this rather than on which of invite / user is populated. Whether it was newly created is the response status: 201 created, 200 already existed.
INVITEDADDEDThe invitation when outcome is INVITED; null otherwise.
The member when outcome is ADDED; null otherwise.
The user was already a member of the organization, or already had an invitation outstanding. The existing one was returned unchanged; nothing was created and no role was modified.
Successful Response
The request was invalid.
Authentication failed or was missing.
The credential is not permitted for this request.
The requested resource was not found.
The request failed validation.
A service this request depends on was unavailable. Retry the request.