Nfon System Integrators API

openapi: 3.1.0
info:
  description: 'The NFON Call History API provides endpoints for retrieving, streaming, and deleting call history records for an authenticated NFON Cloud Telephony user.


    This API is currently offered as part of **Login with NFON (Early Access)**. As an early access offering, the API is subject to change. Updates may occur on short notice, though we strive to provide advance notice where possible.


    For more information, see: https://www.nfon.com/en/integrations/login-with-nfon/'
  title: NFON Call History Accounts System Integrators API
  version: 2.0-early-access
  termsOfService: https://www.nfon.com/en/legal/gtc
  contact:
    name: NFON
    email: integration@nfon.com
  license:
    name: NFON proprietary
servers:
- url: https://api.nfon.com/call-history
tags:
- name: System Integrators
paths:
  /system-integrators/{systemIntegratorId}/tenants:
    get:
      parameters:
      - schema:
          type: string
        required: true
        in: path
        name: systemIntegratorId
      tags:
      - System Integrators
      operationId: get_223
      security:
      - oauth2:
        - tenant.system-integrator
      - oauth2:
        - tenant.operator
      - oauth2:
        - tenant.admin
      responses:
        '200':
          content:
            application/vnd.collection.next+json:
              schema:
                $ref: '#/components/schemas/NfonApiCollectionResponse'
          description: Success
        '403':
          description: Insufficient permissions
  /system-integrators/{systemIntegratorId}:
    get:
      summary: Get system integrator
      parameters:
      - schema:
          type: string
        required: true
        in: path
        description: System integrator ID
        name: systemIntegratorId
      tags:
      - System Integrators
      operationId: get_222
      security:
      - oauth2:
        - tenant.operator
      - oauth2:
        - tenant.admin
      responses:
        '200':
          content:
            application/vnd.collection.next+json:
              schema:
                $ref: '#/components/schemas/NfonApiResponse'
              example:
                links:
                - href: /api/operators/OP001
                  rel: operator
                - href: /api/operators/OP001/rating-profiles/Standard
                  rel: defaultRatingProfile
                - href: /api/time-zones/Europe.Berlin
                  rel: timezone
                data:
                - value: ACME Integrations
                  name: name
                - value: John Doe
                  name: contactName
                - value: john.doe@example.com
                  name: contactEmail
                - value: '+4989123456'
                  name: contactPhoneNumber
                - value: 'true'
                  name: nscAccess
                - value: 'false'
                  name: cdrAccess
                - value: Internal notes
                  name: notes
                - value: newPassword123
                  name: password
                - value: What is your pet's name?
                  name: securityQuestion
                - value: Fluffy
                  name: securityAnswer
                href: /api/system-integrators/example-id
          description: System integrator found
        '404':
          description: Not found
    put:
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/UpdateSystemIntegratorRequest'
      parameters:
      - schema:
          type: string
        required: true
        in: path
        description: System integrator ID
        name: systemIntegratorId
      tags:
      - System Integrators
      summary: Update system integrator
      operationId: put_59
      security:
      - oauth2:
        - tenant.operator
      - oauth2:
        - tenant.admin
      responses:
        '404':
          description: Not found
        '204':
          description: System integrator updated
        '400':
          description: Validation error
  /system-integrators:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSystemIntegratorRequest'
        required: true
      tags:
      - System Integrators
      summary: Create system integrator
      description: Creates a new system integrator
      operationId: createSystemIntegrator
      security:
      - OAuth2:
        - bss.license-manage
      responses:
        '500':
          content:
            application/json:
              examples:
                example:
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    message: Internal server error
                    code: internal_error
                  summary: Internal server error
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              schema:
                format: uuid
                type: string
              description: Unique request identifier
          description: Internal server error
        '409':
          content:
            application/json:
              examples:
                example:
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    message: A resource with this identifier already exists
                    code: conflict
                  summary: Conflict
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              schema:
                format: uuid
                type: string
              description: Unique request identifier
          description: System integrator already exists
        '503':
          content:
            application/json:
              examples:
                example:
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    message: The service is temporarily unavailable. Please try again later.
                    code: upstream_unavailable
                  summary: Service unavailable
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              schema:
                format: uuid
                type: string
              description: Unique request identifier
          description: Service temporarily unavailable
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemIntegratorCreated'
          headers:
            X-Request-Id:
              schema:
                format: uuid
                type: string
              description: Unique request identifier
          description: System integrator created
        '400':
          content:
            application/json:
              examples:
                example:
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    message: Invalid request parameters
                    code: validation_error
                  summary: Validation error
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              schema:
                format: uuid
                type: string
              description: Unique request identifier
          description: Invalid request
components:
  schemas:
    Boolean:
      properties:
        notNull:
          type: boolean
        notPresent:
          type: boolean
        present:
          type: boolean
        presentNotNull:
          type: boolean
        presentNull:
          type: boolean
        value:
          type: boolean
      type: object
      example: false
    CollectionLinks:
      properties:
        first:
          $ref: '#/components/schemas/String'
        prev:
          $ref: '#/components/schemas/String'
        next:
          $ref: '#/components/schemas/String'
        last:
          $ref: '#/components/schemas/String'
      type: object
      description: Pagination links for collection responses
    NfonApiCollectionResponseNonPage:
      properties:
        links:
          $ref: '#/components/schemas/Links'
        href:
          description: Self-link to this collection
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/NfonApiResponse'
          description: All items in the collection
      type: object
      description: Non-paginated collection response envelope
    NfonApiResponse:
      properties:
        links:
          $ref: '#/components/schemas/Links'
        data:
          description: Resource data (name/value pairs or structured object)
          type: object
        href:
          example: /api/sip-servers/100
          type: string
          description: Self-link to this resource
      type: object
      description: Standard API response envelope for a single resource
    Error:
      properties:
        request_id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        code:
          type: string
          example: bad_request
        details:
          $ref: '#/components/schemas/ErrorDetail'
        message:
          type: string
          example: Invalid request
      type: object
      description: Error represents the standard API error response.
    NfonApiCollectionResponsePage:
      properties:
        links:
          $ref: '#/components/schemas/CollectionLinks'
        offset:
          example: 0
          description: Current page offset
          format: int64
          type: integer
        total:
          example: 42
          description: Total number of items in the collection
          format: int64
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/NfonApiResponse'
          description: Items in this page
        size:
          example: 20
          description: Number of items in this page
          format: int32
          type: integer
        href:
          description: Self-link to this collection
          type: string
      type: object
      description: Paginated collection response envelope
    ErrorDetail:
      properties:
        message:
          type: string
          example: Cannot delete license that is currently assigned to a user
        code:
          type: string
          example: license_assigned
      type: object
      description: ErrorDetail represents error details in the delete response.
    SystemIntegratorCreated:
      properties:
        external_identifier:
          type: string
          description: System integrator external identifier.
          example: S0001
      type: object
      description: CreateSystemIntegratorResponse represents the response structure for creating a system integrator. This is named SystemIntegratorCreated in the OpenAPI spec.
    CreateSystemIntegratorRequest:
      properties:
        operator:
          type: string
          description: Operator external identifier.
          example: C1000
        password:
          example: SecurePass123!
          type: string
          minLength: 12
          maxLength: 50
          description: System integrator password (min 12 characters).
        primary_contact:
          $ref: '#/components/schemas/PrimaryContact'
        name:
          type: string
          description: System integrator name.
          maxLength: 100
          example: Partner Solutions GmbH
        security_question:
          example: What is your company name?
          type: string
          minLength: 2
          maxLength: 100
          description: Security question.
        account_id:
          type: string
          description: BSS-provided account identifier (preferred over account_sales_force_id).
          maxLength: 50
          example: a06D000000kIkHr
        account_sales_force_id:
          deprecated: true
          type: string
          example: a06D000000kIkHr
          maxLength: 50
          description: 'BSS-provided account identifier. Use account_id for new integrations. Deprecated: use AccountID instead.'
        security_answer:
          example: Partner Solutions
          type: string
          minLength: 2
          maxLength: 100
          description: Security answer.
        rating_profile:
          type: string
          description: Rating profile name.
          maxLength: 50
          example: standard
      type: object
      required:
      - name
      - operator
      - primary_contact
      - password
      - security_question
      - security_answer
      description: CreateSystemIntegratorRequest represents the request body for creating a system integrator.
    UpdateSystemIntegratorRequestLinks:
      properties:
        defaultRatingProfile:
          $ref: '#/components/schemas/String'
        timezone:
          $ref: '#/components/schemas/String'
        operator:
          $ref: '#/components/schemas/String'
      type: object
    NfonApiCollectionResponse:
      oneOf:
      - $ref: '#/components/schemas/NfonApiCollectionResponsePage'
      - $ref: '#/components/schemas/NfonApiCollectionResponseNonPage'
      type: object
      description: Collection response envelope
    Links:
      description: Related resource links
      type: object
    PrimaryContact:
      description: PrimaryContactParams represents primary contact with address. This is named PrimaryContact in the OpenAPI spec.
      allOf:
      - $ref: '#/components/schemas/Contact'
      - properties:
          address:
            $ref: '#/components/schemas/Address'
        type: object
    Contact:
      properties:
        email:
          type: string
          description: Email address
          maxLength: 75
          example: max.mustermann@example.com
        mobile_number:
          type: string
          description: Mobile number
          maxLength: 32
          example: +49 170 1234567
        phone_number:
          example: +49 89 45300400
          type: string
          minLength: 3
          maxLength: 100
          description: Phone number
        job_title:
          type: string
          description: Job title
          maxLength: 100
          example: IT Administrator
        name:
          type: string
          description: Contact name
          maxLength: 100
          example: Max Mustermann
      type: object
      required:
      - name
      - email
      description: Contact is the struct that holds the contact in a request.
    String:
      properties:
        notNull:
          type: boolean
        notPresent:
          type: boolean
        present:
          type: boolean
        presentNotNull:
          type: boolean
        presentNull:
          type: boolean
        value:
          type: string
      type: object
      description: Link to the last page
    UpdateSystemIntegratorRequestData:
      properties:
        contactName:
          $ref: '#/components/schemas/String'
        contactEmail:
          $ref: '#/components/schemas/String'
        securityAnswer:
          $ref: '#/components/schemas/String'
        password:
          $ref: '#/components/schemas/String'
        contactPhoneNumber:
          $ref: '#/components/schemas/String'
        nscAccess:
          $ref: '#/components/schemas/Boolean'
        cdrAccess:
          $ref: '#/components/schemas/Boolean'
        securityQuestion:
          $ref: '#/components/schemas/String'
        notes:
          $ref: '#/components/schemas/String'
        name:
          $ref: '#/components/schemas/String'
      type: object
    UpdateSystemIntegratorRequest:
      properties:
        links:
          $ref: '#/components/schemas/UpdateSystemIntegratorRequestLinks'
        data:
          $ref: '#/components/schemas/UpdateSystemIntegratorRequestData'
        items:
          items:
            type: object
          type: array
        itemCount:
          format: int32
          type: integer
      type: object
    Address:
      properties:
        country:
          type: string
          description: Country code
          maxLength: 100
          example: DE
        postal_code:
          type: string
          description: Postal code
          maxLength: 10
          example: '81379'
        street:
          type: string
          description: Street address
          maxLength: 100
          example: Machtlfinger Str. 7
        city:
          type: string
          description: City name
          maxLength: 100
          example: München
      type: object
      required:
      - country
      - city
      - street
      - postal_code
      description: Address is the struct that holds the address in a request. nolint:recvcheck // mixed receivers for zerolog/validation compatibility
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JSON Web Token