openapi: 3.0.0
info:
  title: Capmo REST Organisation Companies Organisation People API
  description: External REST API Documentation for Capmo
  version: '1.0'
  contact: {}
servers:
- url: https://api.capmo.de
  description: Production
tags:
- name: Organisation People
  description: ''
paths:
  /api/v1/organisation/people:
    get:
      description: This can be used to list all organisation contact book people in a paginated response.
      operationId: getOrganisationPeople
      parameters:
      - 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: source_id
        required: false
        in: query
        description: '[Filtering Parameter] The unique identifier of the source. This is a user-generated string, used to link the person to a resource in an external system.'
        schema:
          maxLength: 255
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
      - name: email
        required: false
        in: query
        description: '[Filtering Parameter] The email address of the person. '
        schema:
          maxLength: 255
          example: john.doe@example.com
          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 organisation 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/ReadOrganisationPersonDto'
        '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:
      - Organisation People
    post:
      description: This can be used to add a new organisation contact book person.
      operationId: createOrganisationPerson
      parameters:
      - 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/CreateOrganisationPersonDto'
      responses:
        '201':
          description: The organisation contact book person has been successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
                  data:
                    $ref: '#/components/schemas/ReadOrganisationPersonDto'
        '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:
      - Organisation People
  /api/v1/organisation/people/{personId}:
    get:
      description: This can be used to retrieve a specific organisation person by its ID.
      operationId: getOrganisationPerson
      parameters:
      - 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 organisation person has been successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
                  data:
                    $ref: '#/components/schemas/ReadOrganisationPersonDto'
        '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:
      - Organisation People
    patch:
      description: This can be used to update a specific organisation contact book person by its ID.
      operationId: updateOrganisationPerson
      parameters:
      - 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/UpdateOrganisationPersonDto'
      responses:
        '200':
          description: The organisation contact book person has been successfully updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
                  data:
                    $ref: '#/components/schemas/ReadOrganisationPersonDto'
        '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:
      - Organisation People
    delete:
      description: This can be used to delete an organisation contact book person. If the person is a member of the organisation, their membership will be deleted as well.
      operationId: deleteOrganisationPerson
      parameters:
      - 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 organisation 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:
      - Organisation People
components:
  schemas:
    CreateOrganisationPersonDto:
      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
    ReadOrganisationPersonDto:
      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.
        membership_id:
          type: string
          nullable: true
          example: 123e4567-e89b-12d3-a456-426614174000
          description: The organisation membership ID of to the person. If given, the person is a member of the organisation.
      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
      - 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
    UpdateOrganisationPersonDto:
      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
  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