Batch Requests
Last updated: 2024-01-20Contributors
Edit this page
One of the commonly used REST practices is the support of batch operations to retrieve multiple homogeneous resources by their key using a single request. The RingCentral API supports batch requests for a number of endpoints and objects, including messages, call records, blocked numbers, presence, and more. They are implemented via the methods GET, DELETE and PUT with all their features. Batch operations are not transaction-atomic. Each resource in a batch is processed separately from the others, making it possible to receive different success/failure results for different resources wrapped in a multipart response object. The HTTP status code 207 Multi-Status is returned in every multipart response object and indicates a batch request.
207 Multi-status is not returned for error accessing the endpoint
The 207 Multi-Status code is not returned in response body in case of error accessing the endpoint. For example, if the requested endpoint does not exist at all, 404 Not Found status code is returned. If there is a server error, 5xx status code is returned.
In batch DELETE operations (if all resources are deleted successfully) the server returns the 204 No content instead of multi status (since all parts would be identical in this case). In case of at least one failure the server returns the 207 Multi-Status.
Apart from the top-level special status code in case of success, a multipart response object contains status codes in each part, representing a particular requested resource. This status specifies an individual result for each requested resource out of the batch. Let's consider the examples of batch request below.
Batch request for GET method
Multipart/Mixed
Request
GET /restapi/v1.0/account/~/extension/~/message-store/2447722008,2416832008 HTTP/1.1
Accept: application/json
Reponse
HTTP/1.1 207 Multi-Status
Content-Type: multipart/mixed; boundary=Boundary_20_32057915_1351669531796
--Boundary_20_32057915_1351669531796
Content-Type: application/json
{
"response" : [ {
"href" : "https://platform.ringcentral.com/account/154364008/extension/154364008/message-store/2447722008",
"status" : 200,
"responseDescription" : "OK"
}, {
"href" : "https://platform.ringcentral.com/restapi/v1.0/account/154364008/extension/154364008/message-store/2416832008",
"status" : 200,
"responseDescription" : "OK"
} ]
}
--Boundary_20_32057915_1351669531796
Content-Type: application/json
{
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/154364008/extension/154364008/message-store/2447722008",
"id" : 2447722008,
"to" : [ {
"phoneNumber" : "18559100010"
} ],
"from" : {
"phoneNumber" : "18559100010"
},
"type" : "SMS",
"creationTime" : "2012-10-29T15:36:04.000Z",
"readStatus" : "Unread",
"priority" : "Normal",
"attachments" : [ {
"id" : 1,
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/154364008/extension/154364008/message-store/2447722008/content/1",
"contentType" : "text/plain"
} ],
"direction" : "Inbound",
"availability" : "Alive",
"subject" : "verificationMessage",
"messageStatus" : "Received",
"conversationId" : 5717224681082742945,
"lastModifiedTime" : "2012-10-29T15:36:04.000Z"
}
--Boundary_20_32057915_1351669531796
Content-Type: application/json
{
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/154364008/extension/154364008/message-store/2416832008",
"id" : 2416832008,
"to" : [ {
"phoneNumber" : "18559100010"
} ],
"from" : {
"phoneNumber" : "16509101086"
},
"type" : "SMS",
"creationTime" : "2012-10-29T13:09:54.000Z",
"readStatus" : "Unread",
"priority" : "Normal",
"attachments" : [ {
"id" : 1,
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/154364008/extension/154364008/message-store/2416832008/content/1",
"contentType" : "text/plain"
} ],
"direction" : "Inbound",
"availability" : "Alive",
"subject" : "Inbound SMS",
"messageStatus" : "Received",
"conversationId" : 141549019326272744,
"lastModifiedTime" : "2012-10-29T13:09:54.000Z"
}
--Boundary_20_32057915_1351669531796--
Multipart+Json
Request
GET /account/306059004/extension/306061004/message-store/972869004,111 HTTP/1.1
Accept: application/vnd.ringcentral.multipart+json
Response
HTTP 207 Multi-Status
Content-Type: application/vnd.ringcentral.multipart+json
[
{
"resourceId": "972869004",
"status": 200,
"body": {
"uri": "https://platform.ringcentral.com/restapi/v1.0/account/306059004/extension/306061004/message-store/972869004",
"id": 972869004,
"to": [
{
"phoneNumber": "+17607822229",
"location": "Warner Springs, CA"
}
],
"from": {
"phoneNumber": "+15013030165",
"name": "Message #1",
"location": "Benton, AR"
},
"type": "SMS",
"creationTime": "2018-12-24T07:39:12.000Z",
"readStatus": "Unread",
"priority": "Normal",
"attachments": [
{
"id": 972869004,
"uri": "https://platform.ringcentral.com/restapi/v1.0/account/306059004/extension/306061004/message-store/972869004/content/972869004",
"type": "Text",
"contentType": "text/plain"
}
],
"direction": "Outbound",
"availability": "Alive",
"subject": "SMS: direction=Inbox delivery=DELIVERED unread=true",
"messageStatus": "Queued",
"conversationId": 8234962969801172000,
"conversation": {
"id": "8234962969801171948",
"uri": "https://platform.ringcentral.com/restapi/v1.0/conversation/8234962969801171948"
},
"lastModifiedTime": "2018-12-24T10:39:11.666Z"
}
},
{
"resourceId": "111",
"status": 404,
"body": {
"errorCode": "CMN-102",
"message": "Resource for parameter [messageId] is not found",
"errors": [
{
"errorCode": "CMN-102",
"message": "Resource for parameter [messageId] is not found",
"parameterName": "messageId"
}
],
"parameterName": "messageId"
}
}
]
Batch request for PUT method
Multipart/Mixed
The client has to specify: - multipart/mixed content type and boundary; - modified fields for every single item which needs to be updated, separated by multipart boundaries.
Request
PUT /restapi/v1.0/account/~/extension/~/message-store/401654758008,401642088008 HTTP/1.1
Content-Type: multipart/mixed; boundary=Boundary_1_15567762_1355833573664
--Boundary_1_15567762_1355833573664
Content-Type: application/json
{"readStatus": "Read"}
--Boundary_1_15567762_1355833573664
Content-Type: application/json
{"readStatus": "Read"}
--Boundary_1_15567762_1355833573664--
Response
HTTP/1.1 207 Multi-Status
Content-Type: multipart/mixed; boundary=Boundary_1_15567762_1355833573664
--Boundary_1_15567762_1355833573664
Content-Type: application/json
{
"response" : [ {
"href" : "https://platform.ringcentral.com/account/400129284008/extension/400129284008/message-store/401654758008",
"status" : 200,
"responseDescription" : "OK"
}, {
"href" : "https://platform.ringcentral.com/account/400129284008/extension/400129284008/message-store/401642088008",
"status" : 200,
"responseDescription" : "OK"
} ]
}
--Boundary_1_15567762_1355833573664
Content-Type: application/json
{
"uri" : "https://platform.ringcentral.com/account/400129284008/extension/400129284008/message-store/401654758008",
"id" : 401654758008,
"to" : [ {
"phoneNumber" : "18559100010"
} ],
"type" : "Fax",
"creationTime" : "2013-07-11T12:05:43.000Z",
"readStatus" : "Read",
"priority" : "Normal",
"attachments" : [ {
"id" : 1,
"uri" : "https://platform.ringcentral.com/account/400129284008/extension/400129284008/message-store/401654758008/content/1",
"contentType" : "image/tiff"
} ],
"direction" : "Outbound",
"availability" : "Alive",
"messageStatus" : "SendingFailed",
"faxResolution" : "Low",
"faxPageCount" : 0,
"lastModifiedTime" : "2013-07-11T12:26:24.000Z"
}
--Boundary_1_15567762_1355833573664
Content-Type: application/json
{
"uri" : "https://platform.ringcentral.com/account/400129284008/extension/400129284008/message-store/401642088008",
"id" : 401642088008,
"to" : [ {
"phoneNumber" : "77653287256446"
} ],
"type" : "Fax",
"creationTime" : "2013-07-11T08:45:57.000Z",
"readStatus" : "Read",
"priority" : "Normal",
"attachments" : [ {
"id" : 1,
"uri" : "https://platform.ringcentral.com/account/400129284008/extension/400129284008/message-store/401642088008/content/1",
"contentType" : "image/tiff"
} ],
"direction" : "Outbound",
"availability" : "Alive",
"messageStatus" : "SendingFailed",
"faxResolution" : "Low",
"faxPageCount" : 0,
"lastModifiedTime" : "2013-07-11T12:26:52.000Z"
}
--Boundary_1_15567762_1355833573664--
Multipart+Json
Request #1 (IDs in path)
PUT /account/306065004/extension/306067004/message-store/972903004,972901004 HTTP/1.1
Content-Type: application/vnd.ringcentral.multipart+json
[
{
"body": {
"readStatus": "Read"
}
},
{
"body": {
"readStatus": "Read"
}
}
]
Request #2 (IDs in body)
PUT /account/306065004/extension/306067004/message-store/* HTTP/1.1
Content-Type: application/vnd.ringcentral.multipart+json
[
{
"resourceId": "972903004",
"body": {
"readStatus": "Read"
}
},
{
"resourceId": "972901004",
"body": {
"readStatus": "Read"
}
}
]
Response
HTTP 207 Multi-Status
Content-Type: application/vnd.ringcentral.multipart+json
[
{
"resourceId": "972903004",
"status": 200,
"body": {
"uri": "https://platform.ringcentral.com/restapi/v1.0/account/306065004/extension/306067004/message-store/972903004",
"id": 972903004,
"to": [
{
"extensionNumber": "103",
"extensionId": "306068004"
}
],
"from": {
"extensionNumber": "102",
"extensionId": "306067004",
"name": "Generated IM message"
},
"type": "Pager",
"creationTime": "2018-12-24T10:39:24.000Z",
"readStatus": "Read",
"priority": "Normal",
"attachments": [
{
"id": 972903004,
"uri": "https://platform.ringcentral.com/restapi/v1.0/account/306065004/extension/306067004/message-store/972903004/content/972903004",
"type": "Text",
"contentType": "text/plain"
}
],
"direction": "Outbound",
"availability": "Alive",
"subject": "IM: direction=Outbox unread=false",
"messageStatus": "Sent",
"conversationId": 6951365551500,
"conversation": {
"id": "6951365551500",
"uri": "https://platform.ringcentral.com/restapi/v1.0/conversation/6951365551500"
},
"lastModifiedTime": "2018-12-24T10:39:31.873Z",
"pgToDepartment": false
}
},
{
"resourceId": "972901004",
"status": 200,
"body": {
"uri": "https://platform.ringcentral.com/restapi/v1.0/account/306065004/extension/306067004/message-store/972901004",
"id": 972901004,
"to": [
{
"extensionNumber": "103",
"extensionId": "306068004"
}
],
"from": {
"extensionNumber": "102",
"extensionId": "306067004",
"name": "Generated IM message"
},
"type": "Pager",
"creationTime": "2018-12-24T10:39:24.000Z",
"readStatus": "Read",
"priority": "Normal",
"attachments": [
{
"id": 972901004,
"uri": "https://platform.ringcentral.com/restapi/v1.0/account/306065004/extension/306067004/message-store/972901004/content/972901004",
"type": "Text",
"contentType": "text/plain"
}
],
"direction": "Outbound",
"availability": "Alive",
"subject": "IM: direction=Outbox unread=true",
"messageStatus": "Sent",
"conversationId": 6951365551500,
"conversation": {
"id": "6951365551500",
"uri": "https://platform.ringcentral.com/restapi/v1.0/conversation/6951365551500"
},
"lastModifiedTime": "2018-12-24T10:39:31.879Z",
"pgToDepartment": false
}
}
]