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 licenses 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:
- x-displayName: Licenses
description: Unified license management operations
name: licenses
paths:
/tenants/{tenant}/users/{userid}/licenses:
get:
summary: Get licenses assigned to the authenticated user
parameters:
- schema:
type: string
required: true
in: path
description: ''
name: tenant
- schema:
type: string
required: true
in: path
description: ''
name: userid
tags:
- licenses
description: Returns all licenses assigned to the specified user. The userid must match the authenticated user's identity from the bearer token.
operationId: getUserLicenses
security:
- OAuth2:
- tenant.admin
- tenant.operator
- tenant.system-integrator
- tenant.manager
- tenant.user
responses:
'404':
content:
application/json:
examples:
example:
value:
request_id: 550e8400-e29b-41d4-a716-446655440000
message: The requested resource was not found
code: not_found
summary: Not found
schema:
$ref: '#/components/schemas/Error'
headers:
X-Request-Id:
schema:
format: uuid
type: string
description: Unique request identifier
description: Tenant or user not found
'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 parameters
'401':
content:
application/json:
examples:
missingToken:
value:
request_id: 550e8400-e29b-41d4-a716-446655440000
message: JWT missing from the Authorization header.
code: authorization
summary: Missing token
invalidToken:
value:
request_id: 550e8400-e29b-41d4-a716-446655440000
message: Invalid JWT in the Authorization header.
code: authorization
summary: Invalid token
expiredToken:
value:
request_id: 550e8400-e29b-41d4-a716-446655440000
message: There was an issue validating your authorization token.
code: authorization
summary: Expired token
accessingAnotherTenant:
value:
request_id: 550e8400-e29b-41d4-a716-446655440000
message: user is not allowed to perform actions in this access scope
code: authorization
summary: Accessing another Tenant
schema:
$ref: '#/components/schemas/Error'
headers:
X-Request-Id:
schema:
format: uuid
type: string
description: Unique request identifier
description: Unauthorized
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/LicenseDetails'
headers:
X-Request-Id:
schema:
format: uuid
type: string
description: Unique request identifier
description: Licenses assigned to the user
'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
'403':
content:
application/json:
examples:
example:
value:
request_id: 550e8400-e29b-41d4-a716-446655440000
message: User does not have permission to perform this operation
code: forbidden
summary: Forbidden
schema:
$ref: '#/components/schemas/Error'
headers:
X-Request-Id:
schema:
format: uuid
type: string
description: Unique request identifier
description: Forbidden - userid does not match authenticated user
'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
/license-types:
get:
summary: Get all available license types
parameters:
- schema:
type: boolean
required: false
in: query
description: ''
name: metadata
tags:
- licenses
operationId: getLicenseTypes
description: Returns metadata for all available license types including their properties and constraints
responses:
'200':
content:
application/json:
examples:
metadata:
value:
- assignment_requires_extension: true
assignment_requires_user: true
type: MOBILITY_PER_USER
is_package: false
name: Mobility Per User
description: Mobile access for individual users with extension assignment
- assignment_requires_extension: false
assignment_requires_user: false
type: CONFERENCE_UNLIMITED_PER_CONTRACT
is_package: false
name: Conference Unlimited
description: Unlimited conferencing access for the entire contract
- assignment_requires_extension: true
assignment_requires_user: false
type: FAX_PER_EXTENSION
is_package: false
name: Fax Per Extension
description: Fax capability assigned to a specific extension
summary: Metadata format (with metadata=true)
simple:
value:
- BASIC_CTI_UNLIMITED_PER_CONTRACT
- CLIENT_MIA_PER_USER
- CONFERENCE_PER_SERVICE
- CONFERENCE_UNLIMITED_PER_CONTRACT
- FAX_UNLIMITED_PER_CONTRACT
- QUEUE_UNLIMITED_PER_CONTRACT
- TIMECONTROL_UNLIMITED_PER_CONTRACT
- MOBILITY_PER_USER
- UNITE_CTI_PER_USER
- EXTENSION
- GROUP_UNLIMITED_PER_CONTRACT
- IVR_UNLIMITED_PER_CONTRACT
- MEETING_PER_CONTRACT
- MOBILITY_UNLIMITED_PER_CONTRACT
- NEORECORDING_BASIC_PER_EXTENSION
- NEORECORDING_ADVANCED_PER_EXTENSION
- GENESYS_BYOC_PER_CONTRACT
- FAX_PER_EXTENSION
- FAX_UNLIMITED_PER_USER
- PACKAGE_CLOUD_PBX_2025_S
- PACKAGE_CLOUD_PBX_2025_M
- PACKAGE_CLOUD_PBX_2025_L
- PACKAGE_CLOUD_PBX_2025_XL
summary: Simple format (default)
schema:
$ref: '#/components/schemas/LicenseTypeMetadata'
headers:
X-Request-Id:
schema:
format: uuid
type: string
description: Unique request identifier
description: List of license types
'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
'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 parameters
'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
/tenants/{tenant}/licenses:
post:
tags:
- licenses
requestBody:
content:
application/json:
examples:
nested_package:
value:
- children:
- type: FAX_PER_EXTENSION
- type: EXTENSION
type: PACKAGE_CLOUD_PBX_2025_M
- type: FAX_PER_EXTENSION
summary: Create package with children (nested)
simple_licenses:
value:
- type: MOBILITY_PER_USER
- license_id: 7a23e4f1-840d-4917-c32g-32f0ff71c57c
type: FAX_PER_EXTENSION
summary: Simple standalone licenses
schema:
$ref: '#/components/schemas/LicenseCreationRequest'
required: true
parameters:
- schema:
type: string
required: true
in: path
description: ''
name: tenant
- schema:
type: boolean
required: false
in: query
description: ''
name: flatten
summary: Create licenses for a tenant
responses:
'404':
content:
application/json:
examples:
example:
value:
request_id: 550e8400-e29b-41d4-a716-446655440000
message: The requested resource was not found
code: not_found
summary: Not found
schema:
$ref: '#/components/schemas/Error'
headers:
X-Request-Id:
schema:
format: uuid
type: string
description: Unique request identifier
description: Not found
'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
'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
'401':
content:
application/json:
examples:
missingToken:
value:
request_id: 550e8400-e29b-41d4-a716-446655440000
message: JWT missing from the Authorization header.
code: authorization
summary: Missing token
invalidToken:
value:
request_id: 550e8400-e29b-41d4-a716-446655440000
message: Invalid JWT in the Authorization header.
code: authorization
summary: Invalid token
expiredToken:
value:
request_id: 550e8400-e29b-41d4-a716-446655440000
message: There was an issue validating your authorization token.
code: authorization
summary: Expired token
accessingAnotherTenant:
value:
request_id: 550e8400-e29b-41d4-a716-446655440000
message: user is not allowed to perform actions in this access scope
code: authorization
summary: Accessing another Tenant
schema:
$ref: '#/components/schemas/Error'
headers:
X-Request-Id:
schema:
format: uuid
type: string
description: Unique request identifier
description: Unauthorized
'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
'409':
content:
application/json:
examples:
duplicate_license_id:
value:
request_id: 550e8400-e29b-41d4-a716-446655440000
message: License with this ID already exists
code: conflict
summary: Duplicate license ID
tenant_wide_license_exists:
value:
request_id: 550e8400-e29b-41d4-a716-446655440000
message: License can only exist once per tenant
code: conflict
summary: Tenant-wide license already exists
schema:
$ref: '#/components/schemas/Error'
headers:
X-Request-Id:
schema:
format: uuid
type: string
description: Unique request identifier
description: Conflict - License already exists
'403':
content:
application/json:
examples:
example:
value:
request_id: 550e8400-e29b-41d4-a716-446655440000
message: User does not have permission to perform this operation
code: forbidden
summary: Forbidden
schema:
$ref: '#/components/schemas/Error'
headers:
X-Request-Id:
schema:
format: uuid
type: string
description: Unique request identifier
description: Forbidden
'201':
content:
application/json:
examples:
flat_format:
value:
licenses:
- license_id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
type: PACKAGE_CLOUD_PBX_2025_M
- license_id: c2d3e4f5-a6b7-5c8d-9e0f-1a2b3c4d5e6f
child_of: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
type: FAX_PER_EXTENSION
- license_id: f6e5d4c3-b2a1-4b7a-9c8d-5e4f3a2b1c0d
child_of: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
type: EXTENSION
created: 3
summary: Flat format (flatten=true)
nested_format_default:
value:
licenses:
- license_id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
children:
- license_id: c2d3e4f5-a6b7-5c8d-9e0f-1a2b3c4d5e6f
type: FAX_PER_EXTENSION
- license_id: f6e5d4c3-b2a1-4b7a-9c8d-5e4f3a2b1c0d
type: EXTENSION
type: PACKAGE_CLOUD_PBX_2025_M
created: 3
summary: Nested format (flatten=false)
schema:
$ref: '#/components/schemas/LicenseCreationResponse'
headers:
X-Request-Id:
schema:
format: uuid
type: string
description: Unique request identifier
description: Licenses created successfully
operationId: createTenantLicenses
security:
- OAuth2:
- bss.license-manage
description: Creates one or more licenses for the specified tenant
delete:
summary: Delete licenses for a tenant
parameters:
- schema:
type: string
required: true
in: path
description: ''
name: tenant
- schema:
type: string
required: true
in: query
description: ''
name: license_id
tags:
- licenses
description: Deletes one or more licenses for the specified tenant
operationId: deleteTenantLicenses
security:
- OAuth2:
- bss.license-manage
responses:
'207':
content:
application/json:
examples:
partial:
value:
total: 3
failed: 1
succeeded: 2
results:
- license_id: 377586d5-001c-4bcf-9155-4f507559240b
status: success
- license_id: 488697e6-112d-5ccf-a266-5f608b82361c
status: success
- license_id: 2a456b78-def9-4321-abcd-ef1234567890
status: error
error:
message: Cannot delete license that is currently assigned to a user. Unassign the license first.
code: license_assigned
summary: Some failed
schema:
$ref: '#/components/schemas/LicenseDeletionResponse'
headers:
X-Request-Id:
schema:
format: uuid
type: string
description: Unique request identifier
description: Multi-Status - Some deletions succeeded some failed
'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
'200':
content:
application/json:
examples:
success:
value:
total: 2
failed: 0
succeeded: 2
results:
- license_id: 377586d5-001c-4bcf-9155-4f507559240b
status: success
- license_id: 488697e6-112d-5ccf-a266-5f608b82361c
status: success
summary: All deleted
schema:
$ref: '#/components/schemas/LicenseDeletionResponse'
headers:
X-Request-Id:
schema:
format: uuid
type: string
description: Unique request identifier
description: All licenses deleted successfully
'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
'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
get:
summary: Retrieve licenses for a tenant
parameters:
- schema:
type: string
required: true
in: path
description: ''
name: tenant
- schema:
type: string
required: false
in: query
description: ''
name: user_id
- schema:
type: string
required: false
in: query
description: ''
name: license_id
- schema:
type: string
required: false
in: query
description: ''
name: type
- schema:
type: string
required: false
in: query
description: ''
name: extension
- schema:
type: boolean
required: false
in: query
description: ''
name: flatten
tags:
- licenses
description: 'Returns detailed license information for a tenant, including packages with their children.
Can be filtered by user_id, license_id, type, and/or extension. Filters can be combined.
**Filtering:**
- `license_id`, `type`, and `extension` support comma-separated values for multiple filters
- `user_id` accepts a single UUID only
**Response modes:**
- `flatten=false` (default): Nested structure - packages have children in a ''children'' array
- `flatten=true`: Flat structure - all licenses at top level with ''child_of'' references'
operationId: getTenantLicenses
security:
- OAuth2:
- tenant.admin
- tenant.operator
- tenant.system-integrator
- tenant.manager
- bss.license-manage
responses:
'200':
content:
application/json:
examples:
nested_with_package:
value:
- license_id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
type: PACKAGE_CLOUD_PBX_2025_M
children:
- extension: '409'
user_id: d2897036-9eb0-4ff3-9c4f-ef387de24a7c
license_id: c2d3e4f5-a6b7-5c8d-9e0f-1a2b3c4d5e6f
type: FAX_PER_EXTENSION
- license_id: f6e5d4c3-b2a1-4b7a-9c8d-5e4f3a2b1c0d
type: EXTENSION
bss_note: Munich office order (Sep 2025)
- extension: '410'
user_id: a4440613-af08-648d-bf3f-9f9gga98ed65
license_id: 377586d5-001c-4bcf-9155-4f507559240b
type: MOBILITY_PER_USER
summary: Nested format with package (flatten=false)
flat_with_package:
value:
- license_id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
type: PACKAGE_CLOUD_PBX_2025_M
bss_note: Munich office order (Sep 2025)
- child_of: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
type: FAX_PER_EXTENSION
extension: '409'
user_id: d2897036-9eb0-4ff3-9c4f-ef387de24a7c
license_id: c2d3e4f5-a6b7-5c8d-9e0f-1a2b3c4d5e6f
- license_id: f6e5d4c3-b2a1-4b7a-9c8d-5e4f3a2b1c0d
child_of: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
type: EXTENSION
- extension: '410'
user_id: a4440613-af08-648d-bf3f-9f9gga98ed65
license_id: 377586d5-001c-4bcf-9155-4f507559240b
type: MOBILITY_PER_USER
summary: Flat format with package (flatten=true)
schema:
$ref: '#/components/schemas/LicenseDetails'
headers:
X-Request-Id:
schema:
format: uuid
type: string
description: Unique request identifier
description: List of licenses
'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
'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
'404':
content:
application/json:
examples:
example:
value:
request_id: 550e8400-e29b-41d4-a716-446655440000
message: The requested resource was not found
code: not_found
summary: Not found
schema:
$ref: '#/components/schemas/Error'
headers:
X-Request-Id:
schema:
format: uuid
type: string
description: Unique request identifier
description: Tenant not found
/tenants/{tenant}/licenses/assign:
post:
tags:
- licenses
requestBody:
content:
application/json:
examples:
standard-licenses:
value:
- extension: '409'
user_id: e1119380-f895-415a-9c67-ad8b71675cf0
type: MOBILITY_PER_USER
- user_id: a4440613-af08-648d-bf3f-9f9gga98ed65
type: CLIENT_MIA_PER_USER
- extension: '410'
type: FAX_PER_EXTENSION
summary: Standard license assignment
package-assignment:
value:
- license_id: 53763b37-ac19-4209-b3dc-50ca41d98913
user_id: e1119380-f895-415a-9c67-ad8b71675cf0
type: PACKAGE_CLOUD_PBX_2025_M
summary: Package license assignment
schema:
$ref: '#/components/schemas/LicenseOperations'
required: true
parameters:
- schema:
type: string
required: true
in: path
description: ''
name: tenant
summary: Assign licenses to users or extensions
responses:
'207':
content:
application/json:
examples:
partial-failure:
value:
total: 3
failed: 1
succeeded: 2
results:
- status: success
type: MOBILITY_PER_USER
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nfon/refs/heads/main/openapi/nfon-licenses-api-openapi.yml