---
title: "Add a membership"
method: POST
path: "/organization_memberships"
tags: ["Organization memberships"]
---

# Add a membership

`POST /organization_memberships`

## Request

- Base URL: `https://www.happyscribe.com/api/v1`
- URL: `https://www.happyscribe.com/api/v1/organization_memberships`
- Auth: API key in header `Authorization`

Adds a user to the workspace. If the email belongs to an existing HappyScribe
user they become a member instantly (`201 Created`); otherwise an invitation
email is sent (`202 Accepted`).

Requires an `owner` or `admin` role. Only the `admin` and `member` roles can be
assigned through this endpoint.

## Request body

- object
  - `organization_id` string, required: Workspace ID, beginning with `wks_`. Treat it as an opaque string. Integer workspace ids are still accepted.
  - `email` string, required: Email address of the user to add.
  - `role` 'admin' | 'member', required: Role to assign.

## Response `201`

The email belongs to an existing user — membership created immediately.

- object
  - `member` Membership
    - `id` integer
    - `organization_id` string: Workspace ID, beginning with `wks_`. Treat it as an opaque string.
    - `organization_name` string
    - `email` string
    - `name` string
    - `role` 'owner' | 'admin' | 'member' | 'guest'
    - `created_at` string, date-time
    - `updated_at` string, date-time

## Other responses

- `202`: The email is new to HappyScribe — an invitation was emailed.
- `400`: `organization_id` missing, or `role` is not one of `admin`, `member`.
- `401`: Caller is not an `owner` or `admin` of the workspace.
- `404`: Organization does not exist, is archived, or the caller is not a member.
- `422`: Email is invalid, already a member, already invited, plan does not allow the requested role, or the plan seat limit is reached.

---

[API](https://skmtc.dev/happyscribe/apis/happyscribe-api.md) - [All operations](https://skmtc.dev/happyscribe/apis/happyscribe-api/llms.txt) - [OpenAPI document](https://skmtc.dev/happyscribe/apis/happyscribe-api/revisions/1281bd968c3d?raw)