Skip to main content
POST
Add a company membership

Authorizations

Authorization
string
header
required

Partner API Bearer key: Authorization: Bearer <key>. Keys are created only through authorized portal or staff flows.

Headers

Idempotency-Key
string
required

Required client-supplied key scoped to the Partner owner, method, operation and path. An exact retry replays the original response while it is retained, including after credential rotation or replacement. Current permissions are required.

Path Parameters

company_id
string<uuid>
required

UUID of the managed company in this request.

Body

application/json

A user's membership in a managed company.

email
string<email>
required

Email address used to identify and invite the user.

Required string length: 1 - 128
first_name
string
required

Given name of the user.

Required string length: 1 - 128
last_name
string
required

Family name of the user.

Required string length: 1 - 128
role
enum<string>
required

Permissions the user receives within the managed company. The first nonterminal company membership must have role admin; cancelled and revoked memberships do not count as existing memberships for this rule.

Available options:
admin,
tax_consultant,
member,
readonly,
developer
skip_email_verification
boolean
default:false
write-only

Assert that a newly created global user's email ownership was verified out of band. Defaults to false and requires a staff-controlled Partner entitlement. The membership still remains pending_setup until the invitation is accepted.

Response

Create/resend response: the membership plus its one-time setup_url.

Same rule as the webhook signing secret: the link is the invite token, shown exactly once on the response of the command that issued it. Reads use MembershipSerializer (no such field) and the view redacts the field from the idempotency snapshot, so replays omit it as well.

created_at
string<date-time>
required
read-only

Time at which the membership was created.

email
string<email>
required

Email address submitted with the invitation while it is unaccepted; after acceptance, reflects the user's current profile.

Maximum string length: 128
first_name
string
required

Given name submitted with the invitation while it is unaccepted; after acceptance, reflects the user's current profile.

Maximum string length: 128
id
string<uuid>
required
read-only

Stable identifier of this user's membership in the managed company. Use it as membership_id in the company users endpoints.

invite_expires_at
string<date-time> | null
required
read-only

Expiry time of the setup invitation while the membership is pending_setup; null when no pending setup invitation is attached.

last_name
string
required

Family name submitted with the invitation while it is unaccepted; after acceptance, reflects the user's current profile.

Maximum string length: 128
revocation_reason
string
required
read-only

Reason recorded when the membership was revoked.

revoked_at
string<date-time> | null
required
read-only

Time at which the membership was revoked.

revoked_by_token_id
string<uuid> | null
required
read-only

Partner credential that revoked the membership, when applicable.

role
enum<string>
required

Permissions the user receives within the managed company.

  • admin - admin
  • tax_consultant - tax_consultant
  • member - member
  • readonly - readonly
  • developer - developer
Available options:
admin,
tax_consultant,
member,
readonly,
developer
sandbox_origin
enum<string>
required

Provenance of the user behind this membership — sandbox_native for a subject created inside the sandbox (a test resource), production_mirror for a read-only copy of a production user, unclassified otherwise (always so in production).

  • production_mirror - Production mirror
  • sandbox_native - Sandbox native
  • unclassified - Unclassified
Available options:
production_mirror,
sandbox_native,
unclassified
status
enum<string>
required

Membership lifecycle state: pending_setup awaits invitation acceptance; active grants access; cancelled ends a pending invitation; revoked removes an active membership's access.

Available options:
pending_setup,
active,
cancelled,
revoked
updated_at
string<date-time>
required
read-only

Time at which the membership was last updated.

setup_url
string<uri> | null
read-only

One-time setup invitation link. Returned on a fresh membership invitation or resend; omitted from idempotent replays. Treat the link as a secret.