Upload a Recording

POST /v1/recordings

Summary:
Used by services to automatically upload an audio recording to the Voice Analytics service.

Security:

• OAuth2 Client Credentials required with scope "voice-analytics/recordings.write".

Request Body:
JSON object with the following fields:

• user: Object with a required property email (string).

• fileName: (string) Name of the file including its extension.

• contentMd5: (string) Base64-encoded MD5 hash of the file (note: not in hexadecimal).

• callData: Object containing:

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

  • localParty: Object with optional properties firstName, lastName, and number.

  • remoteParty: Object with similar properties as localParty.

  • duration: (integer) Duration in seconds (min: 1).

  • callType: (string) One of INTERNAL, EXTERNAL, or UNKNOWN.

  • recordingDate: (string) ISO 8601 date-time (UTC).

  • speakers: (integer, optional) Number of speakers (2 to 10).

  • language: (string, optional) Language code; if omitted, auto-detected.

Example:

{
  "user": { "email": "user@domain.com" },
  "fileName": "file_Name.mp3",
  "contentMd5": "Dz0RIM96f8B1QA0wkhfXyg==",
  "callData": {
    "direction": "IN",
    "localParty": { "firstName": "John", "lastName": "Smith", "number": "+2 123 514" },
    "remoteParty": { "firstName": "Jane", "lastName": "Smith", "number": "+39 456 789" },
    "duration": 360512,
    "callType": "INTERNAL",
    "speakers": 2,
    "language": "it-IT",
    "recordingDate": "2019-08-24T14:15:22Z"
  }
}

Response:

200 OK or 201 Created:
Returns a JSON object including:

• presignedUrl: URL for a PUT request (S3 presigned URL) to upload the file.

• state: String to be used in the subsequent PUT request header (x-amz-meta-state).

• recordingId: A unique identifier for the recording.

Example response:

{
  "presignedUrl": "https://bucket-url/....",
  "state": "state_value",
  "recordingId": "20200403000000-6da2f5b0-03c6-482d-a28e-7c26df5643b6"
}

Error messages:

• 400 Bad Request – For invalid payload (e.g. wrong email format).

• 401 Unauthorized

• 403 Forbidden – e.g. if the user is unlicensed or transcription quota is exceeded.

• 404 Not Found – if the user cannot be found.

• 422 Unprocessable Entity – e.g. if the file exceeds size limits.

• 500 Internal Server Error

File Upload Note:
After obtaining the presigned URL, the client must perform a PUT request to that URL. The PUT request must include:

• A header x-amz-meta-state with the value returned from the POST.

• A header content-md5 with the same base64-encoded MD5 hash.

Last updated: August 07, 2025