Keeper Notation
Query format used for getting fields of a secret


Keeper notation is used by Keeper Secrets Manager SDKs and integrations to query fields in Keeper records.


The notation is broken up into three parts.
  • UID of the secret record
  • The field to get from the secret record. There are three types: field, custom_field, and file.
  • The type of field, the label or field of the custom field, or the name of the file attachment.


The predicate allows finer access to the value. Some values might be a single value or an array of values, and each of those values might be a string or a dictionary of values.
Arrays If no predicate is defined only one value will be returned. If the returned value contains an array of values, only the first one will be returned. If a predicate with a number is defined, e.g. phone[0] the value at that index is returned. Indexes start at 0.
If a predicate with no value is defined, e.g. phone[], the array value will be returned.
Sub Fields Some fields are made up of other sub fields. e.g. name: {"first:": "John", "last": "Doe"}
To access sub fields, include the name of the field as am alphanumeric predicate. For example name[last] will find "Doe" in the example above, and name[first] will find "John".
Some values are a combination of the arrays and Sub Fields. For example:
{"number": "555-5555555", "ext": "55"},
{"number": "777-7777777", "ext": "77"},
{"number": "888-8888888", "ext": "", "type": "Home"},
{"number": "999-9999999", "type": "Work"}
To get a specific field, a double predicate is needed. For example, the predicate phone[1][number] will return the phone number of the second value.
Use these examples as a reference for writing Keeper Notation queries. Note that each of these examples use a sample record UID. Replace the UID with the record UID for your own record when utilizing Keeper Notation
Query the password from a login record
returns: RX$u!h!pBzDGhR4Jr6#b (Randomly generated password from record)
Query the first name from a contact record
returns: 'Craig'
Query a credentials file from a record
returns: b"jNxmJkhbZ[...]6jQtE" (contents of credentials.txt)
Query a custom Pin Code field with the label 'code'
returns: 5876 (pin code)
Query a Two-Factor Code field from a login record
returns: 5876891
Query the 2nd of several custom field phone numbers
returns: {"number": "555-555-5555", "type": "home"}
Get the just number of this phone number
returns: "555-555-5555"
Get all phone numbers on the record as an array
{"number": "123-456-7890", "type": "work"},
{"number": "555-555-5555", "type": "home"}
Export as PDF
Copy link
On this page