---
title: "Create a company membership (invite)"
method: POST
path: "/v1/company_memberships"
tags: ["Company membership"]
---

# Create a company membership (invite)

`POST /v1/company_memberships`

## Request

- Base URL: `https://api.cardda.com`
- URL: `https://api.cardda.com/v1/company_memberships`
- Auth: HTTP bearer

Creates a membership for a company, generating an invitation token and
sending the invitation email. When the invitee already exists they are
linked; otherwise a pending invitation (no `user_id`) is created for the
email.

## Parameters

- `#/paths/~1v1~1users/get/parameters/0` (unresolved $ref)

## Request body

- object
  - `email` string, email, required
  - `role` string, required
  - `company_id` string, uuid, required
  - `legal_representative` boolean
  - `has_powers_to_act` boolean
  - `partner` boolean
  - `partner_type` integer
  - `participation_rate` number
  - `is_indirect_participation_corporate` boolean
  - `identification_file` string: Attachment (identification document).
  - `power_file` string: Attachment (powers document).

## Response `201`

The created membership.

- CompanyMembership: Links a user (or a pending email invitation) to a company with a role and KYC-related attributes (legal representative, partner, participation rate).
  - `id` string, uuid, required
  - `user_id` string, nullable: Firebase UID of the member. Null while the invitation is still pending.
  - `company_id` string, uuid, required
  - `email` string, nullable
  - `role` string: Role name (e.g. `owner`, `admin`, `member`, or a custom company role name).
  - `status` 'pending' | 'active' | 'canceled'
  - `legal_representative` boolean
  - `has_powers_to_act` boolean, nullable
  - `partner` boolean
  - `partner_type` integer, nullable
  - `participation_rate` number, nullable: Ownership participation percentage (0-100).
  - `is_indirect_participation_corporate` boolean, nullable
  - `company_role_id` string, uuid, nullable
  - `permissions` object[]: Permissions granted to the membership (only `id` and `name` are returned). **Only included by the list endpoint** (`GET /v1/company_memberships`); the create/update/destroy/resend/create_many responses do not embed it.
    - `id` string, uuid
    - `name` string
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `401`: Unauthorized
- `403`: Assigning the `owner` role requires the caller to be an owner of the company. Nothing is created.
- `422`: Validation failed

---

[API](https://skmtc.dev/cardda/apis/organization-api.md) - [All operations](https://skmtc.dev/cardda/apis/organization-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardda/apis/organization-api/revisions/32a4430278a8?raw)