openapi: 3.0.0 info: title: Capmo REST Organisation Companies Project People API description: External REST API Documentation for Capmo version: '1.0' contact: {} servers: - url: https://api.capmo.de description: Production tags: - name: Project People description: '' paths: /api/v1/projects/{projectId}/people: get: description: This can be used to list all project contact book people in a paginated response. operationId: getProjectPeople parameters: - name: projectId required: true in: path schema: type: string - name: order_by required: false in: query description: Field to order by. schema: default: server_created_at example: server_updated_at type: string enum: - server_created_at - server_updated_at - first_name - last_name - email - created_at - updated_at - name: order_direction required: false in: query description: Order direction of the `order_by` field. It can be `asc` or `desc`. schema: default: asc example: asc type: string enum: - asc - desc - name: after required: false in: query description: The last element from the previous page. This is a cursor. It will be returned in the output to be used in the next request. When it is not present, the first page is returned. When it is `null`, there are no more pages. schema: type: string - name: limit required: false in: query description: How many items should be in the output. schema: minimum: 1 maximum: 1000 default: 200 example: 20 type: number - 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: {} responses: '200': description: The project contact book people have been successfully retrieved. content: application/json: schema: type: object properties: message: type: string example: Success data: allOf: - $ref: '#/components/schemas/PaginatedOutputDto' - properties: items: type: array items: $ref: '#/components/schemas/ReadProjectPersonDto' '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 People post: description: This can be used to add a new project contact book person. operationId: createProjectPerson 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/CreateProjectPersonDto' responses: '201': description: The project contact book person has been successfully created. content: application/json: schema: type: object properties: message: type: string example: Success data: $ref: '#/components/schemas/ReadProjectPersonDto' '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 People /api/v1/projects/{projectId}/people/{personId}: get: description: This can be used to retrieve a specific project person by its ID. operationId: getProjectPerson parameters: - name: projectId required: true in: path schema: type: string - name: personId 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: {} responses: '200': description: The project person has been successfully retrieved. content: application/json: schema: type: object properties: message: type: string example: Success data: $ref: '#/components/schemas/ReadProjectPersonDto' '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 People patch: description: This can be used to update a project contact book person. operationId: updateProjectPerson parameters: - name: projectId required: true in: path schema: type: string - name: personId 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/UpdateProjectPersonDto' responses: '201': description: The project contact book person has been successfully updated. content: application/json: schema: type: object properties: message: type: string example: Success data: $ref: '#/components/schemas/ReadProjectPersonDto' '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 People delete: description: This can be used to delete a project contact book person. If the person is a member of the project, their membership will be deleted as well. operationId: deleteProjectPerson parameters: - name: projectId required: true in: path schema: type: string - name: personId 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: {} responses: '200': description: The project contact book person has been successfully deleted. '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 People /api/v1/projects/{projectId}/people-from-organisation: post: description: This can be used to add an organisation contact book person to a project. operationId: createProjectPersonFromOrganisation 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/CreatePersonFromOrganisationDto' responses: '201': description: The organisation contact book person has been successfully added to the project. content: application/json: schema: type: object properties: message: type: string example: Success data: $ref: '#/components/schemas/ReadProjectPersonDto' '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 People components: schemas: ReadProjectPersonDto: type: object properties: source_id: type: string description: The unique identifier of the source. This is a user-generated string. You can use this to link the person to a resource in an external system. example: 123e4567-e89b-12d3-a456-426614174000 created_by: type: string nullable: true example: 123e4567-e89b-12d3-a456-426614174000 description: The unique identifier of the creator of the entity. 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 person. first_name: type: string example: John description: The first name of the person. last_name: type: string example: Doe description: The last name of the person. email: type: string example: john.doe@example.com description: The email address of the person. position: type: string nullable: true example: accountant description: The position of the person. phone_number: type: string nullable: true example: '+491764445566' description: The phone number of the person. It consists of between 1 and 15 digits and an optional leading "+" character. company_id: type: string nullable: true example: 123e4567-e89b-12d3-a456-426614174000 description: The company ID assigned to the person. created_from_id: type: string nullable: true example: 123e4567-e89b-12d3-a456-426614174000 description: The unique identifier of the organisation person that has been used to create the project person. If null, the person has been created manually on the project level. membership_id: type: string nullable: true example: 123e4567-e89b-12d3-a456-426614174000 description: The project membership ID of to the person. If given, the person is a member of the project. required: - created_by - updated_by - created_at - updated_at - deleted_at - server_created_at - server_updated_at - server_deleted_at - id - first_name - last_name - email - position - phone_number - company_id - created_from_id - membership_id PaginatedOutputDto: type: object properties: after: type: string example: null count: type: number example: 1 total: type: number example: 1 required: - after - count - total CreatePersonFromOrganisationDto: type: object properties: person_id: type: string example: 123e4567-e89b-12d3-a456-426614174000 description: The unique identifier of the organisation contact book person that should be added to the project. required: - person_id UpdateProjectPersonDto: type: object properties: source_id: type: string description: The unique identifier of the source. This is a user-generated string. You can use this to link the person to a resource in an external system. example: 123e4567-e89b-12d3-a456-426614174000 first_name: type: string description: The first name of the person. example: John maxLength: 255 last_name: type: string description: The last name of the person. example: Doe maxLength: 255 email: type: string description: The email address of the person. example: john.doe@example.com maxLength: 255 position: type: string description: The position of the person. example: accountant maxLength: 255 phone_number: type: string description: The phone number of the person. It must consist of between 1 and 15 digits and an optional leading "+" character. example: '+491764445566' company_id: type: string description: The company ID assigned to the person. example: 123e4567-e89b-12d3-a456-426614174000 CreateProjectPersonDto: type: object properties: source_id: type: string description: The unique identifier of the source. This is a user-generated string. You can use this to link the person to a resource in an external system. example: 123e4567-e89b-12d3-a456-426614174000 first_name: type: string description: The first name of the person. example: John maxLength: 255 last_name: type: string description: The last name of the person. example: Doe maxLength: 255 email: type: string description: The email address of the person. example: john.doe@example.com maxLength: 255 position: type: string description: The position of the person. example: accountant maxLength: 255 phone_number: type: string description: The phone number of the person. It must consist of between 1 and 15 digits and an optional leading "+" character. example: '+491764445566' company_id: type: string description: The company ID assigned to the person. example: 123e4567-e89b-12d3-a456-426614174000 required: - first_name - last_name - email 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".' x-readme: headers: - key: Request-Id value: YOUR_REQUEST_ID