Product Integration APIs

Recording Service API

This section describes the REST API that can be used to integrate Call Recording and third party systems. Available APIs are the following:

• Start Recording

• Stop Recording

• Get Recordings List

• Get Recording

• Download Recording

• Get Active Recordings

• POST Recording

For proper APIs usage, please refer to the following YAML file: Recordings_2025.Winter.1.yaml

Imagicle Cloud customer can leverage all above APIs, because they are accessible from Internet.

This KB section includes a comprehensive technical documentation for the Recordings API. This documentation details the available endpoints, required security, supported data models, error handling, and special query filtering conventions used throughout the API. The API is defined using the OpenAPI 3.0.0 specification and is intended for interacting with completed call recordings on a UCX Suite server.

Base URL & Authentication

• Base URL:

  CODE

  https://{host}/fw/Apps/Recorder/WebAPI/Recordings

  • The {host} variable represents the UCX Suite server hostname or IP address.

• Authentication:
  All endpoints require HTTP Basic Authentication. You must include an Authorization header with your username and password encoded in Base64.

  Example header:

  CODE

  Authorization: Basic {base64(username:password)}

Data Models and Schemas

Common Schemas

RecordingBase:
Contains common properties for recordings:

• id: Unique identifier (UUID).

• referenceNumber: A friendly, unique reference.

• startTime: Start time (ISO-8601 format).

• duration: Duration (ISO-8601 duration format).

• direction: Call direction (integer enum: 0, 1, 2).

• localPartyNumber: Local party telephone number.

• remotePartyNumber: Remote party telephone number.

Recording:
Extends RecordingBase by adding:

• ownerUsername: Username of the user who recorded the call.

RecordingDetail:
Extends RecordingBase with additional information:

• pbxCallId: (Deprecated) Use pbxInfo instead.

• pbxInfo: Detailed PBX information (see below).

• owner: User object representing the recording owner.

• preservingUser: User who preserved the recording (if any).

• note: An object containing:

  • owner: The last user to edit the note.

  • text: The note text.

• size: Recording file size in bytes.

• hash: Object containing the SHA-256 hash of the recording.

User Schema

Defines user details:

• username

• firstName

• lastName

• phoneNumber

• group

• department

UploadRecordingMetadata Schema

Describes the metadata required when uploading a recording:

• Required:

  • startDateTime

  • duration

  • direction

  • localParty (object with username and phoneNumber)

• Optional:

  • remoteParty (object with phoneNumber)

  • notes

  • preserved (boolean)

  • pbxCallId (deprecated)

  • pbxInfo

PBX Information (PbxInfo)

A polymorphic schema that supports multiple PBX types using a discriminator on the type property. The supported sub-schemas include:

• GenericPbxInfo:

  • type: Must be generic.

  • localCallId

  • remoteCallId

• MediaForkingPbxInfo:

  • type: Must be media-forking.

  • localCallId

  • remoteCallId

  • sessionId

• SipRecPbxInfo:

  • type: Must be siprec.

  • localSessionId

  • remoteSessionId

• WebexPbxInfo:

  • type: Must be webex.

  • callId

  • externalTrackingId

• MsTeamsPbxInfo:

  • type: Must be ms-teams.

  • callId

  • callChainId

Query Filtering with RHS-Colon Syntax

Several query parameters support a special filtering syntax known as RHS-Colon for both datetime and string values. This syntax allows the use of operators directly in the parameter value. Two formats are defined:

RHS-Colon:datetime

Operators:

• equals (or omitted): e.g.,param=equals:2018-11-01T00:00:00Z or simply param=2018-11-01T00:00:00Z

• before: e.g., param=before:2018-10-10T13:05:34Z (upper limit excluded)

• after: e.g., param=after:2018-11-05T09:12:24Z (lower limit excluded)

• between: e.g., param=between:2018-11-01T00:00:00Z;2018-11-02T00:00:00Z (lower limit included, upper excluded)

RHS-Colon:string

Operators:

• equals (or omitted): e.g.,param=equals:some value or param=something

• contains: e.g., param=contains:val

Escaping:
If the searched string contains a semicolon (;) or a backslash (\), these characters must be escaped by prepending a backslash.

Detailed examples and notes for both formats are provided in the API documentation under the dedicated tag.

Common HTTP status codes and responses include:

• 400 Bad Request:
  Used when required fields are missing or parameters are invalid. The response typically contains a reason code and a descriptive message.

• 401 Unauthorized & 403 Forbidden:
  Returned when authentication fails or the authenticated user lacks permission.

• 404 Not Found:
  Indicates that the requested resource (e.g., a recording with a given ID) does not exist.

• 500 Internal Server Error & 504 Gateway Timeout:
  Indicate server-side errors.

• 409 Conflict:
  Specific to the POST endpoint when the recording's start date is out of the retention period.

• 501 Not Implemented:
  May be returned if the Imagicle Call Recording license is invalid.

Live Recording Service API

The Live Recordings Service API enables clients to control live recordings on the UCX Suite server. This includes:

• Retrieving a list of active recordings (with optional filtering by device, directory number, username, or numeric user ID).

• Starting a recording on a connected call.

• Stopping a recording either by specifying a device/directory number or by using a recording identifier.

• Pausing and resuming ongoing recordings (either by recording ID or by directory number).

• Retrieving active recordings specifically for the authenticated user.

The API server endpoint is:

http://{host}/fw/Apps/Recorder/WebAPI/LiveRecordings

where {host} is configurable (defaulting to localhost).

Authentication

All endpoints are secured using a Basic HTTP authentication scheme defined as UserSecurity. Clients must provide valid credentials with each request. Failure to authenticate correctly results in error responses such as 401 (Unauthorized) or 403 (Forbidden).

Data Models

Recording

Represents a live recording with the following properties:

id:

• Type: string (UUID)

• Description: The unique identifier of the recording.

• Example: 6b98303a-b295-473a-adae-19b78aca468d

duration:

• Type: string (ISO 8601 duration)

• Description: Current duration of the recording.

• Example: PT1M13S

startedAt:

• Type: string (ISO 8601 date)

• Description: The starting time of the recording.

• Example: "2018-07-02T15:07:00.0000000"

localParty:

• Type: object (LocalParty)

• Description: Details about the local party (recording owner).

remoteParty:

• Type: object (RemoteParty)

• Description: Details about the remote party.

isPaused:

• Type: boolean

• Description: Indicates whether the recording is paused.

LocalParty

Provides details about the local party (recording owner):

username:

• Type: string

• Description: IAS Username.

• Example: user1

RemoteParty

Provides details about the remote party:

firstName:

• Type: string

• Description: Contact first name.

• Example: John

lastName:

• Type: string

• Description: Contact last name.

• Example: Doe

phoneNumber:

• Type: string

• Description: Remote party phone number.

• Example: +1555123456

Error Handling

Across the Live Recordings Service API, the following HTTP status codes are used:

• 400 Bad Request:
  Indicates missing or invalid parameters (e.g., missing device name or directory number, invalid GUID format, etc.).

• 401 Unauthorized:
  Indicates that the client failed to provide valid authentication credentials.

• 403 Forbidden:
  Indicates that the authenticated user is not authorized to perform the requested operation.

• 409 Conflict:
  Indicates that the request could not be processed because of the current state of the call or recording (e.g., no active recording exists, or the call is already being recorded).

• 429 Too Many Requests:
  Indicates that a duplicate or conflicting request was received (e.g., attempting to pause an already paused recording).

• 500 Internal Server Error:
  Indicates an unexpected error on the server side.

• 501/503:
  Specific to certain conditions such as misconfigurations or channel limitations.