API v1
v1
View as Markdown

Search a vault

GET /api/v1/vaults/{vault}/search

Search the records of one of your vaults, or of all of them, for every word you type.

A record is found when it holds every word, in any order, in its name, in any value written on it, or in the name of somebody linked to it: who took part in a life event, or who a contact has a relationship with. Case and accents are ignored, and a typing mistake is tolerated.

Results come in groups, the way the product lists them: people, each entity type, then life events. Within a group, a record whose name holds the words comes before one where they are only in its values, and that one before a record found only through somebody linked to it.

A value of a field marked sensitive is searched only with a key holding the sensitive-fields scope. Any other key never finds a record through such a value.

Search needs the search engine of the instance. While it cannot be reached, the endpoint answers 503 and nothing else is affected.

This endpoint also answers QUERY, with the same parameters sent in the request body. How QUERY works.

Parameters

Sent as JSON. Anything not listed here is ignored.

vault string Required

The vault to search, named either by the readable name it reports as slug or by its id. Both answer.

query string Required

The words to find, at least two characters and at most 255.

scope string Optional default: vault

vault to search the vault named in the path, account to search every vault of the account.

group string Optional

One group only, by the key a previous answer gave it, to page through it.

page integer Optional default: 1

The page of the group asked for.

per_page integer Optional default: 25

How many results per group, at most 100.

Returns

The groups of records found. A vault belonging to somebody else answers 404, a query under two characters 422, and an unreachable search engine 503.

data array

The groups holding at least one result, in the order the product shows them.

data[] object

One group.

data[].group string

The key of the group: people, life-events, or entity-type- followed by the entity type.

data[].label string

The name of the group, in the language of the account.

data[].total integer

How many records the group holds in all.

data[].next_page integer

The page to ask for next, with group, or null on the last page.

data[].results array

The records of the group on this page, best match first.

data[].results[] object

One record.

data[].results[].type string

contact, entity or life_event.

data[].results[].id uuid

The id the record answers to on its own endpoints.

data[].results[].name string

The name the record is listed under.

data[].results[].vault object

The vault the record lives in.

data[].results[].vault.id uuid

The id of the vault.

data[].results[].vault.name string

The name of the vault.

data[].results[].archived boolean

Whether the record is archived.

data[].results[].date string

For a life event, the day it happened, else null.

data[].results[].matched object

Where the words were found: the label of the value and its text, or null when the name holds them. The text of a sensitive value is always null.

data[].results[].matched.label string

The label of the value, or of the link, the words were found in.

data[].results[].matched.excerpt string

The text of that value, or null for a sensitive value or a link.

meta object

What was asked.

meta.query string

The words searched.

meta.scope string

vault or account.

Rate limit

Sixty requests per minute, per token. Every answer carries the budget left in X-RateLimit-Remaining.

GET
curl https://my.monicahq.com/api/v1/vaults/dunder-mifflin/search?query=farms \
-H "Authorization: Bearer $MONICA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"query": "farms"
}'
const response = await fetch('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/search?query=farms', {
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
query: 'farms',
}),
})
const data = await response.json()
$response = Http::withToken($token)->get('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/search?query=farms', [
'query' => 'farms',
]);
Response 200
{
"data": [
{
"group": "people",
"label": "People",
"total": 1,
"next_page": null,
"results": [
{
"type": "contact",
"id": "9f1c3a2e-7b4d-4c1a-8e2f-5d6b7a8c9e01",
"name": "Dwight Schrute",
"vault": {
"id": "2c7e9b14-1f3a-4d5e-9a8b-6c4d3e2f1a07",
"name": "Dunder Mifflin"
},
"archived": false,
"date": null,
"matched": {
"label": "Employer",
"excerpt": "Schrute Farms"
}
}
]
}
],
"meta": {
"query": "farms",
"scope": "vault"
}
}

Keys act as you, with exactly the access you have. Make one per integration so you can revoke it alone.