Product Integration API

In this KB section, Imagicle provides a description of the Imagicle Voice Analytics “Recordings.v1” APIs. This document describes the available endpoints, their methods, request and response formats, authentication details, and the underlying data models.

Base URL (Server):
https://eu.api.imagicle.com/voice-analytics

Please download relevant YAML file for detailed specifications: Recordings.v1.json

Authentication

There are two security schemes used by these APIs:

• OAuth2 Client Credentials
  – Used by endpoints intended for service-to-service (automatic) operations (e.g. uploading recordings via POST /v1/recordings).
  – Flow: Client credentials with a token URL (see tenant configuration API documentation).
  – Scope: "voice-analytics/recordings.write"

• Bearer Authentication
  – Used for endpoints accessed by an authenticated end user (for example, manual recording uploads or retrieving details).
  – The client must include a valid bearer token in the HTTP Authorization header.

Data Schemas

Recording

A Recording object includes:

• id: (string) Unique recording identifier.

• ownerId: (string) User or owner identifier.

• direction: (string) "IN", "OUT", or "UNKNOWN".

• from and to: Objects with fullName and phoneNumber (both strings).

• date: (string) ISO 8601 timestamp (e.g. "2021-04-25T10:24:40Z").

• analysisResult: Object with:

  • score: (number, -1 to 1) Analysis confidence score.

  • sentiment: (string) E.g. "POSITIVE", "NEGATIVE", "NEUTRAL", "ERROR", or "UNKNOWN".

  • status: (integer) Status code (0–5) indicating the progress/state.

• channels: (number) Either 1 (mono) or 2 (stereo).

• duration: (number) Duration in seconds.

• tags: Array of Tag objects.

• video: Object with status (and optionally errorDetail), where status can be "OK", "NONE", or "ERROR".

• hasNotes: (boolean) Indicates if notes are associated.

RecordingDetails

Similar to Recording but may omit some properties (e.g. tags and notes) and is used in detailed views.

Error

An error response is modeled with:

• errorCode: (number) Error code.

• errorDescription: (string) Description of the error.

Speaker

A speaker in a transcription:

• speakerId: (string)

• speakerLabel: (string) e.g. a full name.

Sentence

Represents a transcribed sentence:

• speakerId: (string)

• startTime: (number) Start time in seconds.

• endTime: (number) End time in seconds.

• text: (string) Transcribed text.

Tag

A tag object used to label recordings:

• id: (string, UUID)

• value: (string) Tag name.

Note

Represents a note attached to a recording:

• noteId: (string, UUID)

• authorUserId: (string, UUID)

• noteText: (string) Note content.

• createdAt: (string, date-time)

• lastModified: (string, date-time)

Additional Information

• Data Validation:
  Several endpoints use regular expressions and numeric constraints (e.g., valid ISO dates, phone number formats, allowed numeric ranges) to validate incoming parameters.

• File Upload Process:
  The upload endpoints follow a two-step process:

  1. Request Upload: POST to obtain a presigned S3 URL.

  2. Perform Upload: Use the provided URL to perform a PUT operation. It is critical to include the proper headers (e.g. content-md5, x-amz-meta-*) exactly as returned in the initial POST response.

• Rate Limits & Quota:
  Some endpoints (e.g. recording uploads) may return errors if the user is unlicensed or if transcription quotas are exceeded.

• Error Handling:
  Error responses provide an errorCode and errorDescription to assist in troubleshooting.