GET /identifiers/_search

Search for an identifier.

Name	Type	Description
pretty	boolean, optional, default: false	readable output formatting
count	integer, optional, min: 1, max: 20, default: 20	number of returned results
offset	integer, optional, max: 1000, default: 0	number of initial results that should be skipped
query	string, required	search query

Queries

Search language

A “mini-language” is used to perform searches for receipts and identifiers. A query consists of one or more fields, separated by spaces. A field contains a path, and a match value, range value or the symbol: *, separated by a colon. The available paths are defined by the type of record that is being searched for, and can be found below in section on “Search fields”. Paths follow the structure of the record being searched and may contain dots to separate parts of the path. Simple match queries would look as follows:

path.to.number:2

text_path:SearchTerm

path.to.date:2024-10-12

which could be combined into one query using spaces:

path.to.number:2 path:SearchTerm path.to.date:2024-10-12

Range queries use square brackets and braces to indicate closed and open ranges respectively. These can be combined for half-open intervals. The word TO must appear between the two extremes of the range. The brackets and braces are used as follows:

At the start of a range

• [    greater than or equal to (>=)

• {    greater than (>)

At the end of a range

• ]    less than or equal to (<=)

• }    less than (<)

Range queries for numbers and dates can be expresses like this:

path.to.number:[2 TO 6]

path.to.number:{-0.5 TO 0.5]

path.to.date:[2024-10-12 TO 2024-10-16}

when searching text fields, search terms containing spaces can be used by surrounding the search term in quotes, this query all records where the field contains the entire phrase:

text_path:"a multi word phrase"

it is also possible to search for multiple words for one field, where the field must then contain one or more of the words:

text_path:(this that)

for some fields it is possible to search for words that are like the specified word, which might be useful to search for records while ignoring pluralisation or alternative spelling or word endings:

text_path:things~

it is also possible to require, using + or exclude a certain word, using - in a text field:

text_path:(-exclude)

text_path:(+require)

text_path:(+require -exclude)

and excluding or requiring certain search terms can also happen at the field level:

+path.to.number:2

-text_path:SearchTerm

It is possible to check for the existence of a field by using the special value *:

path.to.field:*

as well as check that a field does not exist:

-path.to.field:*

should you need to search for the * symbol, it can be quoted:

path.to.field:"*"

When queries are submitted as a querystring argument to the API, they must be URL encoded.

Example identifier searches

Query	Description
properties.name.first:smith	first name must contain “smith”
properties.name.first:smith~	first name must contain a term similar to “smith”
properties.name.first:"john smith"	first name must contain “john smith”
properties.name.first:(john smith)	first name must contain “john” or “smith”
properties.name.first:(+john -smith)	first name must contain “john” and cannot contain “smith”
properties.birthdate:[1965-01-01 TO 1965-06-12}	birthdate must be >= 1965-01-01 and < 1965-06-12
properties.birthdate:[* TO 1965-06-12] properties.name.first:john	birthdate must be <= 1965-06-12 and first name must contain “john”

Search fields

The following fields are available when searching an identifier:

Field	Search type
identifier	prefix match
identfier.exact	exact match
properties.name.title	exact match
properties.name.first	prefix match
properties.name.first.exact	exact match
properties.name.middle	prefix match
properties.name.middle.exact	exact match
properties.name.last	prefix match
properties.name.last.exact	exact match
properties.email	prefix match
properties.email.exact	exact match
properties.postcode	prefix match
properties.postcode.exact	exact match
properties.address	prefix match
properties.address.exact	exact match
properties.city	prefix match
properties.city.exact	exact match
properties.gender	exact match
properties.house_number	prefix match
properties.house_number.exact	exact match
properties.phone	prefix match
properties.phone.exact	exact match
properties.birthdate	date match

Prefix match fields support partial matching from the beginning of words. I.e. a search for “chris” on a prefix match would also match identifiers in which the field contains “christian”. For exact match fields a search for “chris” would not match an identifier with a field that contained “christian”; only identifiers with fields containing exactly the string “chris” would be returned.

Examples

Search for an existing identifier

Example request:

GET /identifiers/_search?query=properties.email.exact%3Ajohn.smith%40example.com HTTP/1.1
Host: api.ereceipts.co.uk
Accept: application/json

Example response:

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Transfer-Encoding: chunked

{
  "hits": 1,
  "identifiers": [
    {
      "created_timestamp": "2016-09-14T13:57:38+00:00",
      "identifier": "123456789",
      "properties": {
        "address": [],
        "birthdate": null,
        "city": "London",
        "email": "john.smith@example.com",
        "gender": "male",
        "name": {
          "first": "John",
          "last": "Smith",
          "middle": "mr.",
          "title": null
        },
        "opt-out": [],
        "postcode": null
      },
      "source_updated_timestamp": "2016-09-14T13:57:38+00:00",
      "summary": {},
      "updated_timestamp": "2016-09-14T13:57:38+00:00"
    }
  ],
  "time": 10
}

Search for a non-existing identifier

Example request:

GET /identifiers/_search?query=properties.email.exact%3Aj.smith%40example.com HTTP/1.1
Host: api.ereceipts.co.uk
Accept: application/json

Example response:

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Transfer-Encoding: chunked

{
  "hits": 0,
  "identifiers": [],
  "time": 9
}