Search conditions | Edulead API

The search endpoints take their filters in one query parameter, conditions: a JSON array of conditions, URL-encoded. Every condition must hold.

[
  {"field": "siteId", "operator": "equals", "value": "efcb8b3f-5994-4649-b3c0-802dd10ac489"},
  {"field": "ingestedAt", "operator": "between", "value": ["2026-10-01T00:00:00Z", "2026-10-08T00:00:00Z"]}
]

A condition is an object with exactly three keys: field, operator and value.
At most 30 conditions, and the whole parameter at most 4,096 characters.
A string value holding commas is several values: "TX,CA" matches Texas or California for equals, and excludes both for not_equals.
A field the root does not have, an operator the field does not allow, or a value of the wrong shape is refused with INVALID_ARGUMENT, naming the condition (conditions[1].value).

Operators

Operator	Matches when	Value
`equals`	the field is the value	one string, number or boolean; a comma-separated string matches any of its parts
`not_equals`	the field is not the value	one string, number or boolean; a comma-separated string excludes every part
`contains`	the field’s text contains the value	one string; a comma-separated string matches any of its parts
`does_not_contain`	the field’s text does not contain the value	one string; a comma-separated string excludes every part
`starts_with`	the field’s text starts with the value	one string
`ends_with`	the field’s text ends with the value	one string
`contains_word`	the field’s text contains the value as a whole word	one string
`match_phrase`	the field’s text contains the value as a phrase, its words in order	one string
`in`	the field is one of the values	an array of at most 500 strings or numbers, or a comma-separated string
`not_in`	the field is none of the values	an array of at most 500 strings or numbers, or a comma-separated string
`gt`	the field is greater than the value	one number, or one date for a date field
`gte`	the field is the value or greater	one number, or one date for a date field
`lt`	the field is less than the value	one number, or one date for a date field
`lte`	the field is the value or less	one number, or one date for a date field
`between`	the field is within the two bounds	an array of exactly two numbers or dates, or one string `"low,high"`
`between_string`	the field is within the two bounds	one string `"low,high"`
`exists`	the field has a value	ignored
`not_exists`	the field has no value	ignored
`array_contains`	the field, a list, holds the value	one string

Value kinds

Each field takes values of one kind.

Kind	What the value looks like
text	a string, matched on its words
keyword	a string matched exactly, such as an id, a code or a state
number	a JSON number, or a string in plain numeric form (`"5000"`, `"-1.5"`): no thousands separators, currency signs or empty strings
date	a date or date-time in ISO 8601 (`"2026-10-01"`, `"2026-10-01T00:00:00Z"`), or epoch milliseconds as a number
bool	`true` or `false`, as a boolean or as a string
opaque	a string in the form the endpoint’s description gives (a beacon id, a territory id, a list of shapes)

Visits

GET /v4/visits/search. Exactly one siteId condition is required: a search is scoped to one of the team’s sites. Names on one row are aliases of the same field.

Field	Operators	Value
`geo.subdivisions.isoCode`	`equals`	keyword
`ingestedAt`	`equals`, `gt`, `gte`, `lt`, `lte`, `between`, `between_string`	date
`siteId`	`equals`	keyword

Institutions

GET /v4/institutions/search. beaconIds (in, beacon ids) with radiusMiles (equals, a number) selects the institutions of the team’s beacons, or those within the miles of them. Names on one row are aliases of the same field.

Field	Operators	Value
`access`, `schoolAccess`	`equals`	text
`address`	`contains`	text
`agencyRevTotal`, `districtRevTotal`, `fsclRevTotal`, `revenueTotal`	`gt`, `lt`, `between`	number
`beaconIds`	`in`	opaque
`charterLea`	`equals`, `not_equals`	text
`city`	`equals`, `contains`	text
`countyId`	`equals`	text
`dsIdNces`, `ncesId`	`equals`	opaque
`fax`	`equals`, `not_equals`, `contains`, `does_not_contain`, `exists`	text
`fulltext`	`contains`	opaque
`grade`	`equals`, `not_equals`	opaque
`grade1`	`equals`	bool
`grade10`	`equals`	bool
`grade11`	`equals`	bool
`grade12`	`equals`	bool
`grade13`	`equals`	bool
`grade2`	`equals`	bool
`grade3`	`equals`	bool
`grade4`	`equals`	bool
`grade5`	`equals`	bool
`grade6`	`equals`	bool
`grade7`	`equals`	bool
`grade8`	`equals`	bool
`grade9`	`equals`	bool
`gradeAE`	`equals`	bool
`gradeKG`	`equals`	bool
`gradePK`	`equals`	bool
`highestGrade`	`equals`, `gte`	number
`id`	`equals`, `in`, `not_in`	opaque
`idParentInstitution`	`equals`	text
`list`	`equals`, `not_equals`	opaque
`locState`, `state`	`equals`, `not_equals`	keyword
`lowestGrade`	`equals`, `lte`	number
`model`	`equals`	text
`name`	`equals`, `contains`, `exists`	text
`parentDistrictNcesId`	`equals`	text
`parentDistrictRevenue`	`gt`, `lt`, `between`	number
`phone`	`equals`, `not_equals`, `contains`, `does_not_contain`, `exists`	text
`radiusMiles`	`equals`	number
`radiusSearch`, `shapes`	`equals`	opaque
`religiousAffiliation`, `schoolReligiousAffiliation`	`equals`	text
`schoolSubtype`	`equals`, `not_equals`	one of `REGULAR`, `CHARTER`
`staffTotal`, `stfTotal`	`gt`, `lt`, `between`	number
`studentTeacherRatio`	`equals`, `not_equals`, `gt`, `gte`, `lt`, `lte`, `between`	number
`studentsTotal`	`gt`, `lt`, `between`	number
`subtype`	`equals`, `not_equals`	text
`subtypeKeyword`	`equals`, `not_equals`	keyword
`teachersTotal`	`equals`, `not_equals`, `gt`, `gte`, `lt`, `lte`, `between`	number
`territoryId`	`equals`, `in`	opaque
`titleOne`	`equals`, `not_equals`	bool
`totalDistricts`, `totalSchools`	`gt`, `lt`, `between`	number
`type`	`equals`, `not_equals`	text
`website`	`contains`, `exists`	text
`zip`	`equals`, `not_equals`, `does_not_contain`, `starts_with`, `ends_with`	text

People

GET /v4/people/search and GET /v4/people/headcounts. Institution conditions hold on one and the same institution of a person, role conditions on one and the same role; a role exclusion holds on every role. beaconIds with radiusMiles work as on institutions. Names on one row are aliases of the same field.

Field	Operators	Value
`access`, `institution.access`	`equals`, `not_equals`	text
`accountId`	`equals`	keyword
`accountNrStudents`	`equals`, `not_equals`, `gt`, `gte`, `lt`, `lte`, `between`	number
`beaconIds`	`in`	opaque
`countyId`, `institution.countyId`	`equals`, `not_equals`	keyword
`districtRevTotal`, `institution.districtRevTotal`	`equals`, `not_equals`, `gt`, `gte`, `lt`, `lte`, `between`	number
`email`	`equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `contains_word`, `exists`, `not_exists`	text
`emailFormat`	`equals`, `not_equals`	text
`emailSource`	`equals`, `not_equals`	text
`emailType`	`equals`, `not_equals`	text
`emailVerificationStatus`	`equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `contains_word`, `not_in`, `exists`, `not_exists`	text
`firstName`	`equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `contains_word`, `exists`, `not_exists`	text
`fulltext`	`contains`	opaque
`grade`, `institution.grade`	`equals`, `not_equals`	opaque
`id`	`equals`, `in`	opaque
`institution.id`, `institutionId`	`equals`	keyword
`institution.model`, `model`	`equals`, `not_equals`	keyword
`institution.name`, `institutionName`	`equals`, `contains`	text
`institution.ncesId`, `institutions.nces_id`, `ncesId`	`equals`, `not_equals`	opaque
`institution.radiusSearch`, `institution.shapes`, `radiusSearch`, `shapes`	`equals`	opaque
`institution.religiousAffiliation`, `religiousAffiliation`	`equals`	keyword
`institution.schoolGrade`, `schoolGrade`	`equals`, `not_equals`	opaque
`institution.state`, `state`	`equals`, `not_equals`	keyword
`institution.stfTotal`, `stfTotal`	`equals`, `not_equals`, `gt`, `gte`, `lt`, `lte`, `between`	number
`institution.studentTchrRatio`	`equals`, `not_equals`, `gt`, `gte`, `lt`, `lte`, `between`	number
`institution.studentsTotal`, `studentsTotal`	`equals`, `not_equals`, `gt`, `gte`, `lt`, `lte`, `between`	number
`institution.subtype`, `subtype`	`equals`, `not_equals`	keyword
`institution.territoryId`, `territoryId`	`equals`, `in`	opaque
`institution.titleOne`, `titleOne`	`equals`, `not_equals`	bool
`institution.type`, `institutionType`, `type`	`equals`, `not_equals`	opaque
`institution.zip`, `zip`	`equals`, `not_equals`, `starts_with`, `ends_with`	keyword
`labels`	`in`, `not_in`	keyword
`lastName`	`equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `contains_word`, `exists`, `not_exists`	text
`lastSeen`	`equals`, `not_equals`	opaque
`name`	`equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `contains_word`, `exists`, `not_exists`	text
`phone`	`equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `contains_word`, `exists`, `not_exists`	text
`phoneUniqueness`	`equals`, `not_equals`	text
`priority`	`equals`, `not_equals`, `gt`, `gte`, `lt`, `lte`, `between`	number
`radiusMiles`	`equals`	number
`role.area`, `titleArea`	`equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `contains_word`, `exists`, `not_exists`	text
`role.confidence`	`equals`, `not_equals`, `gt`, `gte`, `lt`, `lte`, `between`	number
`role.decisionLevel`	`equals`, `not_equals`, `in`	keyword
`role.functionalGroup`	`equals`, `not_equals`, `in`	keyword
`role.marketThemes`	`equals`, `not_equals`, `in`, `not_in`	keyword
`role.modifier`, `titleModifier`	`equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `contains_word`, `exists`, `not_exists`	text
`role.role`, `titleRole`	`equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `contains_word`, `exists`, `not_exists`	text
`role.status`	`equals`, `not_equals`, `in`, `not_in`	keyword
`sourceAndAge`	`in`, `not_in`	opaque
`tag`	`equals`, `not_equals`	opaque
`title`	`equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `contains_word`, `exists`, `not_exists`	text
`titleRank`	`equals`, `not_equals`, `gt`, `gte`, `lt`, `lte`, `between`	number