Upload a Recording

POST `/v1/recordings`

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

For manual uploads (e.g. via GUI), use the POST /v1/recordings/own endpoint.

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:

CODE

{
  "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:

CODE

{
  "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.