---
updatedAt: 2026-05-27T07:27:25.000Z
agentTools:
  projectIndex: https://capmoapi.readme.io/llms.txt
---

# /api/v1/projects/{projectId}/memberships

This can be used to invite a project contact book person to a project identified by projectId. As a result, a project membership for them will be created.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "paths": {
    "/api/v1/projects/{projectId}/memberships": {
      "post": {
        "description": "This can be used to invite a project contact book person to a project identified by projectId. As a result, a project membership for them will be created.",
        "operationId": "inviteProjectPerson",
        "parameters": [
          {
            "name": "projectId",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Request-Id",
            "in": "header",
            "description": "The HTTP `Request-Id` request header is an optional and unofficial HTTP header, used to trace individual HTTP requests from the client to the server and back again. It allows the client and server to correlate each HTTP request. If not provided by the client, the server should generate a unique request ID and include it in the response.",
            "schema": {}
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InviteProjectMemberDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The project membership for contact book person has been successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Success"
                    },
                    "data": {
                      "$ref": "#/components/schemas/ReadProjectMembershipDto"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request, Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "example": "https://capmoapi.readme.io/reference/errors#bad-request"
                    },
                    "message": {
                      "type": "string",
                      "example": "An error occurred"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "example": "BAD_REQUEST"
                          },
                          "message": {
                            "type": "string",
                            "example": "Bad request"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "example": "https://capmoapi.readme.io/reference/errors#unauthorized"
                    },
                    "message": {
                      "type": "string",
                      "example": "An error occurred"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "example": "UNAUTHORIZED"
                          },
                          "message": {
                            "type": "string",
                            "example": "Unauthorized"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "example": "https://capmoapi.readme.io/reference/errors#forbidden"
                    },
                    "message": {
                      "type": "string",
                      "example": "An error occurred"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "example": "FORBIDDEN"
                          },
                          "message": {
                            "type": "string",
                            "example": "Forbidden"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Object not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "example": "https://capmoapi.readme.io/reference/errors#not-found"
                    },
                    "message": {
                      "type": "string",
                      "example": "An error occurred"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "example": "NOT_FOUND"
                          },
                          "message": {
                            "type": "string",
                            "example": "Object not found"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "example": "https://capmoapi.readme.io/reference/errors#conflict"
                    },
                    "message": {
                      "type": "string",
                      "example": "An error occurred"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "example": "CONFLICT"
                          },
                          "message": {
                            "type": "string",
                            "example": "Conflict"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "example": "https://capmoapi.readme.io/reference/errors#internal-server-error"
                    },
                    "message": {
                      "type": "string",
                      "example": "An error occurred"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "example": "INTERNAL_SERVER_ERROR"
                          },
                          "message": {
                            "type": "string",
                            "example": "Internal server error"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "CapmoAuth": []
          }
        ],
        "summary": "",
        "tags": [
          "Project Memberships"
        ]
      }
    }
  },
  "info": {
    "title": "Capmo REST API",
    "description": "External REST API Documentation for Capmo\n\n## Changelog\n\n### 2026-11-16 — Plan name validation messages number sections by Plan Code position\n\nWhen a plan name does not match the active Plan Code, the error message now numbers the failed section by its position in the Plan Code, counting separators, the same way the Capmo web app does. Before, it counted only the sections that hold values, starting at 0.\n\nThe response format is unchanged.\n\n### 2026-10-15 — CAD files (DWG/DXF) in plans\n\nPlans can now have CAD files (DWG and DXF) as well as PDF files. Each plan is returned with one file, chosen with the new optional `type` query parameter on `GET /api/v1/projects/{projectId}/plans` and `GET /api/v1/projects/{projectId}/plans/{planId}`:\n\n- Without `type`, nothing changes: plans that have a PDF file are returned, each with its latest PDF.\n- With `type=PDF` or `type=CAD`, every plan is returned with its latest file of that type, or of the other type when it has none.\n\nPlan responses include two new fields: `type` (`PDF` or `CAD`) and `extension` (`.pdf`, `.dwg` or `.dxf`). CAD files have no preview, so `image_url` returns a generic placeholder image for them.\n\nCreating or updating a plan with a `.dwg` or `.dxf` file adds a CAD file, and the response returns the uploaded file.\n\n### 2026-10-01 — Pending invitees leave organisation memberships\n\nNotice period: 30 days. Sunset: Sat, 31 Oct 2026 00:00:00 GMT.\n\n`GET`, `PATCH` and `DELETE` `/api/v1/organisation/memberships/{id}` will stop resolving a pending invitee on the sunset date. A pending invitation id returns 404 there.\n\n`GET /api/v1/organisation/memberships` will stop including pending invitees on the same date.\n\nPending invitees move to `/api/v1/organisation/invitations` (list, read, create, role update, revoke).\n\nAccepted memberships on `/api/v1/organisation/memberships` are unchanged.\n\nUntil the sunset date, a response that resolves a pending invitee on `GET`, `PATCH` or `DELETE` `/api/v1/organisation/memberships/{id}` includes:\n\n- `Deprecation: @1790812800` (1 October 2026, RFC 9745)\n- `Sunset: Sat, 31 Oct 2026 00:00:00 GMT` (RFC 8594)",
    "version": "1.0",
    "contact": {}
  },
  "tags": [
    {
      "name": "Project Memberships",
      "description": ""
    }
  ],
  "servers": [
    {
      "url": "https://api.capmo.de",
      "description": "Production"
    }
  ],
  "components": {
    "securitySchemes": {
      "CapmoAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "For authentication, use the custom prefix followed by a space and then your API key. Example: \"Capmo YOUR_API_KEY\"."
      }
    },
    "schemas": {
      "ProjectRole": {
        "type": "string",
        "enum": [
          "ADMIN",
          "GUEST"
        ],
        "description": "The role assigned to the user in the project."
      },
      "ReadProjectMembershipDto": {
        "type": "object",
        "properties": {
          "updated_by": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "nullable": true,
            "description": "The unique identifier of the last user who updated the entity."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2021-07-01T00:00:00.000Z",
            "description": "The date when the entity was created (on the client)."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2021-07-01T00:00:00.000Z",
            "description": "The date when the entity was last updated (on the client)."
          },
          "deleted_at": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "example": "2021-07-01T00:00:00.000Z",
            "description": "The date when the entity was deleted (on the client)."
          },
          "server_created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2021-07-01T00:00:00.000Z",
            "description": "The date when the entity was created (on the server)."
          },
          "server_updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2021-07-01T00:00:00.000Z",
            "description": "The date when the entity was last updated (on the server)."
          },
          "server_deleted_at": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "example": "2021-07-01T00:00:00.000Z",
            "description": "The date when the entity was deleted (on the server)."
          },
          "id": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "The unique identifier of the membership."
          },
          "user_id": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "The unique identifier of the user assigned to the membership."
          },
          "user_signed_up": {
            "type": "boolean",
            "example": true,
            "description": "The flag indicating whether the user has signed up for the platform."
          },
          "role": {
            "example": "ADMIN",
            "description": "The role assigned to the user in the project.",
            "allOf": [
              {
                "$ref": "#/components/schemas/ProjectRole"
              }
            ]
          },
          "person_id": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "The unique identifier of the contact person assigned to the membership."
          },
          "invited_by": {
            "type": "string",
            "nullable": true,
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "The unique identifier of the user who invited the user linked to the membership."
          }
        },
        "required": [
          "updated_by",
          "created_at",
          "updated_at",
          "deleted_at",
          "server_created_at",
          "server_updated_at",
          "server_deleted_at",
          "id",
          "user_id",
          "user_signed_up",
          "role",
          "person_id",
          "invited_by"
        ]
      },
      "InviteProjectMemberDto": {
        "type": "object",
        "properties": {
          "person_id": {
            "type": "string",
            "description": "The ID of the person to invite to the project.",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          },
          "role": {
            "description": "The role assigned to the user in the project. Note: GUEST is deprecated and will be removed.",
            "example": "ADMIN",
            "deprecated": true,
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/ProjectRole"
              }
            ]
          },
          "permission_set_id": {
            "type": "string",
            "nullable": true,
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "Optional permission set ID to assign to the invited user. If omitted, the project default permission set is used."
          },
          "skip_invitation_email": {
            "type": "boolean",
            "example": false,
            "description": "When true, creates the project membership without sending an invitation email. Defaults to false."
          }
        },
        "required": [
          "person_id"
        ]
      }
    }
  },
  "x-readme": {
    "headers": [
      {
        "key": "Request-Id",
        "value": "YOUR_REQUEST_ID"
      }
    ]
  }
}
```