Collections

Many actions you can take in the API involve collections of resources. These collections contain multiple resources of the same type, such as a collection of services on a customer account.

What's different about collections?

When the result of a request involves just one resource, such as when you're viewing a specific address by its ID, we don't need to worry about how to distinguish one resource from another. We can just directly list all the address's fields in our response:

{
  "ok": true,
  "address_id": 1001,
  "customer_id": 0,
  "first_name": "",
  "middle_initial": "",
  "last_name": "",
  "company_name": "Your Company Name",
  "line_1": "123 Your Street",
  "line_2": "",
  "city": "Your City",
  "state_or_province": "AL",
  "postal_code": "10001",
  "postal_code_extension": "",
  "country_code": 235,
  "links": [
    {
      "rel": "self",
      "href": "http://restapi.rev.io/v1/addresses/1001"
    }
  ]
}

But when we send you a collection of results, we need some way to separate Address #1's city from Address #2's. We do this by returning each address inside a records collection:

{
  "ok": true,
  "has_more": false,
  "record_count": 2,
  "records": [
    {
      "address_id": 1001,
      "customer_id": 0,
      "first_name": "",
      "middle_initial": "",
      "last_name": "",
      "company_name": "Your Company Name",
      "line_1": "123 Your Street",
      "line_2": "",
      "city": "Your City",
      "state_or_province": "AL",
      "postal_code": "10001",
      "postal_code_extension": "",
      "country_code": 235
    },
    {
      "address_id": 1002,
      "customer_id": 0,
      "first_name": "",
      "middle_initial": "",
      "last_name": "",
      "company_name": "Rev.io TEST ACCOUNT",
      "line_1": "3340 Peachtree Rd NE",
      "line_2": "STE 2850",
      "city": "Atlanta",
      "state_or_province": "GA",
      "postal_code": "30326",
      "postal_code_extension": "1027",
      "country_code": 235
    }
  ]
}

Examples of collections

A collection of service types returned from a search, named "records":

{
  "ok": true,
  "has_more": false,
  "record_count": 3,
  "records": [
    {
      "service_type_id": 2,
      "active": true,
      "description": "Data Service"
    },
    {
      "service_type_id": 4,
      "active": true,
      "description": "Account Level Charges"
    },
    {
      "service_type_id": 9,
      "active": true,
      "description": "Managed Services"
    }
  ]
}

A report prompt collection, named "prompts", belonging to a report in a larger collection:

{
  "ok": true,
  "has_more": true,
  "record_count": 10,
  "records": [
    {
      "report_id": 1054,
      "prompts": [
        {
          "prompt_id": 2895,
          "column": "@agent_id_select",
          "value": "0",
          "operator": "SP_TYPE"
        },
        {
          "prompt_id": 2896,
          "column": "@statement_date",
          "value": "",
          "operator": ""
        }
      ]
      ...
    },
    {
      "report_id": 1923,
      ...
    }
    ...
  ]
}