Request Batching

Search API accepts multiple separate requests within single call. To send batched requests, provide multiple elements in top-level items array of request JSON. API will respond with single result item per query, in same order queries were provided.

As an example, let's consider two batched requests:

• Total value of all deals closed from the beginning of 2017
• Highest deal value owned by Jane Doe (here it's achieved using descending sorting on decimal_value attribute and limit number of results to one, but could be equivalently achieved via max aggregation)

Fetch deals

POST /v3/deals/search

Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

{
  "items": [
    {
      "data": {
        "query": {
          "filter": {
            "filter": {
              "parameter": {
                "range": {
                  "gte": "2017-01-01"
                }
              },
              "attribute": {
                "name": "close_date"
              }
            }
          }
        },
        "aggregations": [
          {
            "attribute": {
              "name": "decimal_value"
            },
            "aggregation_type": "sum"
          }
        ],
        "hits": false
      }
    },
    {
      "data": {
        "query": {
          "projection": [
            {
              "name": "decimal_value"
            }
          ],
          "filter": {
            "filter": {
              "parameter": {
                "eq": "John Doe"
              },
              "attribute": {
                "name": "owner.name"
              }
            }
          },
          "sort": [
            {
              "attribute": {
                "name": "decimal_value"
              },
              "order": "descending"
            }
          ]
        },
        "per_page": 1
      }
    }
  ]
}

Content-Type: application/json; charset=UTF-8

{
  "items": [
    {
      "successful": true,
      "items": [],
      "meta": {
        "aggregations": {
          "decimal_value": {
            "sum": 4387198.13
          }
        },
        "count": 0,
        "http_status": "200 OK",
        "links": {},
        "total_count": 845,
        "type": "collection"
      }
    },
    {
      "successful": true,
      "items": [
        {
          "data": {
            "decimal_value": 34634634,
            "currency": "USD",
            "id": 245278,
            "version": 94
          },
          "meta": {
            "type": "deal"
          }
        }
      ],
      "meta": {
        "count": 1,
        "http_status": "200 OK",
        "links": {
          "next_page": "someToken=="
        },
        "total_count": 273,
        "type": "collection"
      }
    }
  ]
}

---

HTTP Status

If all queries completed with the same status, this will be HTTP response status of batched query (e.g. if all queries succeeded the API will return HTTP 200 OK and if all queries were malformed, it will return HTTP 400 Bad Request). But if different queries completed with different results, HTTP 207 Multi-status will be returned.

For example, if user mistyped the name of the filter attribute in the first request (close_dat instead of close_date), it would fail, but second request would still complete successfully:

Fetch deals

POST /v3/deals/search

Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

{
  "items": [
    {
      "data": {
        "query": {
          "filter": {
            "filter": {
              "parameter": {
                "range": {
                  "gte": "2017-01-01"
                }
              },
              "attribute": {
                "name": "close_dat"
              }
            }
          }
        },
        "aggregations": [
          {
            "attribute": {
              "name": "decimal_value"
            },
            "aggregation_type": "sum"
          }
        ],
        "hits": false
      }
    },
    {
      "data": {
        "query": {
          "projection": [
            {
              "name": "decimal_value"
            }
          ],
          "filter": {
            "filter": {
              "parameter": {
                "eq": "John Doe"
              },
              "attribute": {
                "name": "owner.name"
              }
            }
          },
          "sort": [
            {
              "attribute": {
                "name": "decimal_value"
              },
              "order": "descending"
            }
          ]
        },
        "per_page": 1
      }
    }
  ]
}

Content-Type: application/json; charset=UTF-8
Status: 207 Multi-status

{
  "items": [
    {
      "successful": false,
      "errors": [
        {
          "error": {
            "field": "filter",
            "code": "schema_validation_failed",
            "message": "Request parsed successfully but does not match the schema",
            "details": "Attribute not found: close_dat"
          },
          "meta": {
            "type": "error"
          }
        }
      ],
      "meta": {
        "type": "errors",
        "logref": "779fe3ff-851f-41de-8cb4-7a9cb8cf2261",
        "links": {
          "more_info": "https://developers.getbase.com/docs/rest/articles/errors"
        },
        "http_status": "422 Unprocessable Entity"
      }
    },
    {
      "successful": true,
      "items": [
        {
          "data": {
            "decimal_value": 34634634,
            "currency": "USD",
            "id": 245278,
            "version": 94
          },
          "meta": {
            "type": "deal"
          }
        }
      ],
      "meta": {
        "count": 1,
        "http_status": "200 OK",
        "links": {
          "next_page": "someToken=="
        },
        "total_count": 273,
        "type": "collection"
      }
    }
  ]
}