> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Member

> Register a member of your client's team on a workspace

Register a member of your client's team on a workspace. Cases then resolve that person as an owner or an assignee, instead of mistaking the team for contacts.

<Note>
  Members created through the API are always **silent**: Penbox never emails them, and the flag cannot be overridden from the payload. A partner can never create a member Penbox would contact.
</Note>

## Idempotency

The call is idempotent on the pair (`workspace.id`, `email`): re-posting a member who already exists returns that member with a `200` instead of failing on the uniqueness constraint. A `201` means the member was created.

Emails are lowercased and trimmed before the lookup, so `Jane@Acme.com` and `jane@acme.com` are the same member.

## Roles

| Field        | Default | Meaning                                          |
| ------------ | ------- | ------------------------------------------------ |
| `is_handler` | `true`  | Can be set as the owner or an assignee of a case |
| `is_admin`   | `false` | Can administer the workspace and its settings    |

<Warning>
  `workspace.id` is always explicit — it is never inferred from the token. A token that does not cover the workspace returns a `404`.
</Warning>


## OpenAPI

````yaml POST /members
openapi: 3.0.0
info:
  title: Penbox API
  version: '1.0'
  description: >-
    The Penbox API provides programmatic access to Penbox's form management,
    case management, and document processing capabilities. Authenticate using
    Bearer tokens created at https://app.penbox.io/workspace/settings/api
servers:
  - url: https://connect.penbox.io/v1
    description: Production
  - url: https://connect.aiboov.com/v1
    description: Staging
security:
  - BearerAuth: []
paths:
  /members:
    post:
      summary: Create Member
      description: >-
        Register a member of your client's team on a workspace, so cases resolve
        them as an owner or an assignee instead of treating the team as
        contacts. Members created through the API are always silent: Penbox
        never emails them, and the flag cannot be set from the payload.


        Idempotent on the pair (`workspace.id`, `email`): a member who already
        exists is returned with a 200 instead of an error. Emails are trimmed
        and lowercased before the lookup.
      operationId: create-member
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - workspace
                - email
              properties:
                workspace:
                  type: object
                  required:
                    - id
                  description: >-
                    Workspace to add the member to. Always explicit, never
                    inferred from the token.
                  properties:
                    id:
                      type: string
                      format: uuid
                email:
                  type: string
                  format: email
                  description: >-
                    Member email address. Linked to the existing Penbox account
                    when there is one.
                given_name:
                  type: string
                  maxLength: 100
                  description: First name
                family_name:
                  type: string
                  maxLength: 100
                  description: Last name
                locale:
                  type: string
                  maxLength: 10
                  description: Language the member is addressed in
                  example: fr
                is_admin:
                  type: boolean
                  default: false
                  description: >-
                    Whether the member can administer the workspace and its
                    settings
                is_handler:
                  type: boolean
                  default: true
                  description: >-
                    Whether the member can be set as the owner or an assignee of
                    a case
      responses:
        '200':
          description: >-
            A member with this email already exists on the workspace, and is
            returned unchanged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '201':
          description: The member was created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '404':
          description: The token does not cover the requested workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Member:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Member UUID
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        email:
          type: string
          format: email
          description: Member email address, trimmed and lowercased
        given_name:
          type: string
          nullable: true
          description: First name
        family_name:
          type: string
          nullable: true
          description: Last name
        locale:
          type: string
          nullable: true
          description: Language the member is addressed in
        is_admin:
          type: boolean
          description: Whether the member can administer the workspace and its settings
        is_handler:
          type: boolean
          description: Whether the member can be set as the owner or an assignee of a case
        silent:
          type: boolean
          description: >-
            Whether Penbox refrains from emailing this member. Always true for a
            member created through the API.
        active:
          type: boolean
          description: >-
            Whether the email is already linked to a Penbox user account. False
            while the member has not signed up.
        workspace:
          type: object
          description: Workspace the member belongs to
          properties:
            id:
              type: string
              format: uuid
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: string
              title:
                type: string
              detail:
                type: string
              source:
                type: object
                properties:
                  pointer:
                    type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: >-
        API token (starts with pnbx_). Create at
        https://app.penbox.io/workspace/settings/api. Include as: Authorization:
        Bearer {token}

````