Product Integration APIs

This page describes the REST APIs used to integrate Imagicle Call Recording with third-party systems. There are two independent APIs, each with its own base URL, authentication, and OpenAPI 3.0 specification:

• Recording Service API — query, retrieve, download and upload completed call recordings.

• Live Recording Service API — start, stop, pause and resume the recording of a call that is currently in progress.

Recording Service API

This API exposes a set of functions to interact with completed call recordings on a UCX Suite server. The table below lists all available endpoints:

The full technical contract for this API — endpoints, schemas, and examples — is defined in the attached OpenAPI 3.0 specification, which is the authoritative reference: Recordings.openapi.yaml

Base URL & Authentication

• Base URL:

  http(s)://{host}/fw/Apps/Recorder/WebAPI/Recordings
  

  • The {host} variable represents the UCX Suite server hostname or IP address (defaults to localhost when running on the UCX Suite server itself).

  • If you are leveraging an on-prem UCX Suite, the scheme accepts both http and https transactions by default, and you can optionally ban http by following this KB article.

  • If you are leveraging an UCX Cloud Suite, the scheme accepts https transactions only.

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

  Example header:

  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 (Unknown), 1 (Incoming), 2 (Outgoing).

• 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.

Error Handling

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. The table below lists all available endpoints:

The API server endpoint is:

http(s)://{host}/fw/Apps/Recorder/WebAPI/LiveRecordings

• The {host} variable represents the UCX Suite server hostname or IP address (defaults to localhost when running on the UCX Suite server itself).

• If you are leveraging an on-prem UCX Suite, the scheme accepts both http and https transactions by default, and you can optionally ban http by following this KB article.

• If you are leveraging an UCX Cloud Suite, the scheme accepts https transactions only.

The full technical contract for this API — endpoints, schemas, and examples — is defined in the attached OpenAPI 3.0 specification, which is the authoritative reference: LiveRecordings.openapi.yaml

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.

Last updated: August 27, 2026