What is the Dot Syntax?

There are times when the information that is needed is different from the information used in the query. However, the information that is needed is contained within the related model. To access and filter the information within the related model, the API user needs to use the dot syntax.

In the example below, the people endpoint does not directly include an individual's phone number. Instead, the phone numbers are stored in a separate model attached to the individual, named phone_numbers. If the API user needs to search for the individual attached to phone number 555-123-4567, they would need create a new filter on the phone_numbers.number field.

Filter example:

Python
GET /api/v2/people?q=
{
  "filters": [
    {
      "operand": "phone_numbers.number",
      "operator": "=",
      "value": "5551234567"
    }
  ]
}

Filter output:

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

Chaining

The dot syntax can be chained, allowing the API user to access the models that are not directly connected to the endpoint. In the example below, the API users wants to find the individual with the work phone number 555-123-4567.

Chained model example:

Python
GET /api/v2/people?q=
{
  "filters": [
    {
      "operand": "phone_numbers.number",
      "operator": "=",
      "value": "5551234567"
    },
    {
      "operand": "phone_numbers.phone_number_type.name",
      "operator": "=",
      "value": "Work"
    }
  ]
}

Chained model output:

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