Archiving file attachments
Before you can attach voice files, e.g. recordings, meetings, etc., you must send the files to the /files endpoint before you reference them in the /voice request.
For each attachment, make a PUT request to the /files endpoint, with the fileKey included as a URL path parameter:
curl -X PUT "voice.api.globalrelay.com/v2/files/default/voice-recording.mp3" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-H "Content-Type: <VALID_CONTENT_TYPE>" \
-T "<PATH_TO_FILE>"If you use the same fileKey for multiple requests, the API returns a 200 success response, and the original file is replaced with the new version specified in the latest request.
You must include “/default” in the URL path before the file name. The path from “default” onward, e.g. “default/voice-recording.mp3”, will be the fileKey value you reference in the /files endpoint.
Handling different file types
The file should be sent as binary data in the body of the PUT request, and you should include a Content-Type header with a standard MIME type describing the format of the contents.
If the file type is unknown, you can use the generic “application/octet-stream” type; however, the file type will not be obvious to users in the Archive and they may not be able to open the file.
A Content-Length header is not required; however, if you send an incorrect value, only the amount of data specified in the header will be captured, which could result in incomplete data being archived. As per RFC 9110, the Content-Length should be the uncompressed, decrypted file size as a decimal, non-negative integer number of octets.
The /files endpoint supports files up to 1.0GB in size. If you send a file larger than this, the API returns a 400 error.
Referencing attached files
Once you receive a 200 success response from the /files endpoint for all files referenced in the call, make a request to the /voice endpoint referencing the files with the “recordingFile” eventType.
Additionally, you can share the participants of the meeting or call. The initiator or owner of the call is specified in the callOverview. For more information, see Voice archiving fundamentals.
The fileKey in this request MUST match the fileKey uploaded via the PUT /files endpoint.
If you provide a fileKey which is not found in your Archive, the POST /voice request will return a 400 error response and the associated data will not be archived.
For example, a recording file was attached to a meeting started by Kate, the meeting owner, with Ann, Sarah, Mary, and Andrea as participants.
"callOverview": {
"callId": "1234565775",
"callType": "Zoom",
"owner": {
"phone": "555-657-9980",
"name": "Kate Rydell",
"email" : "kate.rydell@agimperial.com"
"company": "AG Imperial",
"detail": "Owner"
},
"deviceName": "office phone",
"direction": "inbound",
"stopReason": "owner_hangup",
},
"voiceRecords": [
{
"startTime": "1737050060753",
"stopTime": "1737050150341",
"recordingFile": {
"filename": "meeting-recording-20250115.opus",
"fileKey": "/default/meeting-recording-20250115.opus",
"description": "Recording of conversation"
},
"participants": [
{
"name": "Ann Nguyen",
"phone": "555-767-5645",
"company": "AG Imperial",
"email": "ann.nguyen@agimperial.com",
"detail": "Participant",
"joinTimeMS": 0,
"leaveTimeMS": 30
},
{
"name": "Sarah Krish",
"phone": "555-123-7890",
"company": "Ag Imperial",
"email": "sarah.krish@agimperial.com",
"detail": "Participant",
"joinTimeMS": 12,
"leaveTimeMS": 30000
"leaveTimeMS": 30000
},
{
"name": "Mary Thorsen",
"phone": "555-455-3490",
"company": "Digiset Capital",
"email": "mary.thorsen@digisetcapital.com",
"detail": "Participant",
"joinTimeMS": 60001
},
{
"name": "Andrea Lacey",
"phone": "555-321-5467",
"company": "Lautner Wealth",
"email": "alacey@lautnerwealth.com",
"detail": "Participant",
"joinTimeMS": 12,
"leaveTimeMS": 30000
},
{
]
}
],In this example, a single file was uploaded; however, you can include multiple files in the same request, e.g. a voice file and its associated transcript file.
Referencing external file locations
You can also include links to externally located files, which are not in Global Relay Archive, by referencing the URL in the fileHref field along with the mandatory fileKey and filename fields in the voiceRecord object.
"voiceRecords": [
{
"startTime": 1729845357877,
"stopTime": 1729845467877,
"recordingFile": {
"filename": "meeting-recording.mp3",
"fileKey": "meeting-recording.mp3",
"fileHref" : "https://www.digisetcapital.com/files/meeting-recording.mp3"
"description": "Meeting recording"
},When users view voice data in your Archive, the filename will be the text displayed on the link to the URL you supply in fileHref. The fileKey is not displayed, but must be populated with some value in the API request.