Understanding the Results

count: Integer

The number of results from the query. For requests other than searches, the count will always be 1.

count output example:

{
  "count":1000,
  ...
  ...
  ...
  ...
}

total_results: Integer | Undefined

The number of available results from the query; used for pagination. For requests other than searches, the total_results value will not be included.

total_results output example:

{
  ...
  "total_results":54153,
  ...
  ...
  ...
}

offset: Integer | Undefined

The offset of the results from the query; used for pagination. For requests other than searches, the offset will not be included.

offset output example:

{
  ...
  ...
  "offset":0,
  ...
  ...
}

results: Array | Object | Null

The results from the query. The results are defined by each endpoint.

results output example:

{
  ...
  ...
  ...
  "results": [
    {...}
  ],
  ...
}

errors: Object | Null

The errors returned from the query. When there are no errors, the error value will be set to null.

The column will be the column that contains the error. If the error is not related to a specific column, the column will be set to base.

errors output example:

{
  ...
  ...
  ...
  ...
  "errors":null
}

{
  "column": ["is not valid"],
  "another_column": ["is missing"]
}

{
  "base": ["error on the model"]
}

---

Ordering the Results

To order the results, the results need be passed through an order array. The order array takes the results and orders them based on the column attributes.

Descending Order

In the example below, the results are ordered by first name in descending order (Z to A).

Order array example:

GET /v2/people?q={
  "order": [{
    "column": "first_name",
    "direction": "desc"
  }]
}

Order array output:

{
  "count": 1000,
  "total_results": 15000,
  "offset": 0,
  "results": [
    {
      "first_name": "Zoe",
      "last_name": "Smith"
    },
    ...
    {
      "first_name": "Alex",
      "last_name": "Jones"
    }
  ]
}

Ascending Order

In the example below, the results are ordered by last name and first name, in ascending order (A to Z).

Order array example:

GET /v2/people?q={
  "order": [{
    "column": "last_name",
    "direction": "asc"
  },
  {
    "column": "first_name",
    "direction": "asc"
  }]
}

Order array output:

{
  "count": 1000,
  "total_results": 15000,
  "offset": 0,
  "results": [
    {
      "first_name": "Jane",
      "last_name": "Albertson"
    },
    ...
    {
      "first_name": "Alex",
      "last_name": "Smith"
    },
    {
      "first_name": "John",
      "last_name": "Smith"
    },
    ...
  ]
}

---

Filtering the Results

To filter the results, the results need to be passed through a filter option. The filtered results will be the intersection of the results based on the filter option. This is equivalent to the AND operator in SQL, where two conditions are joined together.

The filter option will contain an operand, operator, and value.

• operand: String

  The column used in the query.

• operator: String

  The operator used to filter the results. The following operators are supported:

Operator	Description
=	Equal
!=	Not equal
>	Greater than
<	Less than
>=	Greater than or equal to
<=	Less than or equal to
in	Column contains one of the values
not in	Column does not contain one of the values

• value: String | Number | Boolean | Array | Null

  The value the results will be filtered by based on the operand and operator. The value can be written as a string, number, boolean, array, or null.

Single Filter

In the example below, the results are filtered by the operand first_name, the operator =, and the value Mark. The query will output individuals with the first name Mark.

Filter parameters example:

GET /v2/people?q=
{
  "filters": [
    {
      "operand": "first_name",
      "operator": "=",
      "value": "Mark"
    }
  ]
}

Filter output example:

{
  "count": 2,
  "total_results": 2,
  "offset": 0,
  "results": [
    {
      "first_name": "Mark",
      "id": 123,
      "last_name": "Smith"
    },
    {
      "first_name": "Mark",
      "id": 352,
      "last_name": "Johnson"
    }
  ]
}

Multiple Filters

Multiple filters can be used to the filter results.

In the example below, the request includes two filters. The results are filtered by the operand first_name and last_name, the operator =, and the value Mark and Smith. The query will output individuals with the first name Mark and last name Smith.

Filter parameters example (multiple filters):

GET /v2/people?q=
{
  "filters": [
    {
      "operand": "first_name",
      "operator": "=",
      "value": "Mark"
    },
    {
      "operand": "last_name",
      "operator": "=",
      "value": "Smith"
    },

  ]
}

Filter output example (multiple filters):

{
  "count": 1,
  "total_results": 1,
  "offset": 0,
  "results": [
    {
      "first_name": "Mark",
      "id": 123,
      "last_name": "Smith"
    }
  ]
}

In and Not In Operators

If the API user needs to use the in and not in operators to filter the results, the value must be entered as an array.

Request example (in and not in operators):

GET /v2/people?q=
{
  "filters": [
    {
      "operand": "id",
      "operator": "in",
      "value": [1, 2, 3]
    }
  ]
}

GET /v2/people?q=
{
  "filters": [
    {
      "operand": "first_name",
      "operator": "not in",
      "value": ['James', 'John']
    }
  ]
}

---