How do I Search for Users?

You can use the user search API to search for users by TrueVault system fields (username, status, created date, and id) or by custom fields you store in user attributes. To search by your custom attributes, you need to first setup the user schema to tell TrueVault which fields to index.

Searching by System Fields

As soon as you create your first user you can search for that user by the TrueVault system fields: username, status, created date, and id. Let’s say you want to search for all users whose username contains ‘@truevault.com’ that were created between January and March of 2017. You would build a search option that looks like this:

{
"full_document": true,
    "filter": {
        "$tv.username": {
            "type":"wildcard",
            "value":"*@truevault.com"
        },
        "$tv.created_at": {
            "type":"range",
            "value": {
                "gte": "2017-01-01",
                "lt": "2017-03-31"
            }
        }
    }
}

Then send that search option to the user search endpoint like this:

curl -XPOST -u 'API_KEY:' https://api.truevault.com/v1/users/search -d \ 
'search_option=ewogICJmdWxsX2RvY3VtZW50IjogdHJ1ZSwKICAiZmlsdGVyIjp7CiAgICAgIiR0di51c2VybmFt
ZSI6ewogICAgICAgICAidHlwZSI6IndpbGRjYXJkIiwKICAgICAgICAgInZhbHVlIjoiKkB0cnVl
dmF1bHQuY29tIgogICAgIH0sCiAgICAiJHR2LmNyZWF0ZWRfYXQiOnsKICAgICAgInR5cGUiOiJy
YW5nZSIsCiAgICAgICJ2YWx1ZSI6IHsKICAgICAgICAiZ3RlIjogIjIwMTctMDEtMDEiLAogICAg
ICAgICJsdCI6ICIyMDE3LTEwLTMxIgogICAgICB9CiAgICB9CiAgfQp9'

Searching by Custom Attributes

You can set custom attributes on your users and later use the same user search endpoint to search those fields. First you’ll need to tell TrueVault to index those fields by updating the user schema. Let’s say our users have attributes like this:

{
    "first_name": "Joe",
    "last_name": "Smith",
    "dob": "1980-01-30",
    "internal_id": 838103
}

If we want to search by any of those fields, we would update our user schema (it’s empty by default) to look like this:

{
   "name": "userschema",
   "fields": [
    {
        "name": "first_name",
        "index": true,
        "type": "string"
    },
    {
        "name": "last_name",
        "index": true,
        "type": "string"
    },
    {
        "name": "dob",
        "index": true,
        "type": "date"
    },
    {
        "name": "internal_id",
        "index": true,
        "type": "integer"
    }
   ]
}

Our user schema update call would look like this:

 curl -XPUT -u 'API_KEY:' https://api.truevault.com/v1/accounts/<YOUR ACCOUNT ID>/user_schema \
-d 'schema=ewogICAibmFtZSI6ICJ1c2Vyc2NoZW1hIiwKICAgImZpZWxkcyI6IFsKICAgICAgICB7CiAgICAg
ICAgICJuYW1lIjogImZpcnN0X25hbWUiLAogICAgICAgICAiaW5kZXgiOiB0cnVlLAogICAgICAg
ICAidHlwZSI6ICJzdHJpbmciCiAgICAgICAgfSwKICAgICAgICB7CiAgICAgICAgICJuYW1lIjog
Imxhc3RfbmFtZSIsCiAgICAgICAgICJpbmRleCI6IHRydWUsCiAgICAgICAgICJ0eXBlIjogInN0
cmluZyIKICAgICAgICB9LAogICAgICAgIHsKICAgICAgICAgIm5hbWUiOiAiZG9iIiwKICAgICAg
ICAgImluZGV4IjogdHJ1ZSwKICAgICAgICAgInR5cGUiOiAiZGF0ZSIKICAgICAgICB9LAogICAg
ICAgIHsKICAgICAgICAgICAibmFtZSI6ICJpbnRlcm5hbF9pZCIsCiAgICAgICAgICAgImluZGV4
IjogdHJ1ZSwKICAgICAgICAgICAidHlwZSI6ICJpbnRlZ2VyIgogICAgICAgIH0KICAgXQp9'

Next we can issue a search based on these custom attributes, in conjunction with system fields. Let’s extend our search from above to filter by first name starts with ‘J’. The search option will look like this:

{
    "full_document": true,
    "filter":{
        "$tv.username": {
            "type":"wildcard",
            "value":"*@truevault.com"
        },
        "$tv.created_at": {
            "type":"range",
            "value": {
                "gte": "2017-01-01",
                "lt": "2017-03-31"
            }
        },
        "first_name": {
            "type":"wildcard",
            "value":"J*"
        }
    }
}

Then our user search would look like this:

curl -XPOST -u 'API_KEY:' https://api.truevault.com/v1/users/search -d 'search_option=ewogICJmdWxsX2RvY3VtZW50IjogdHJ1ZSwKICAiZmlsdGVyIjp7CiAgICAgIiR0di51c2VybmFt
ZSI6ewogICAgICAgICAidHlwZSI6IndpbGRjYXJkIiwKICAgICAgICAgInZhbHVlIjoiKkB0cnVl
dmF1bHQuY29tIgogICAgIH0sCiAgICAiJHR2LmNyZWF0ZWRfYXQiOnsKICAgICAgInR5cGUiOiJy
YW5nZSIsCiAgICAgICJ2YWx1ZSI6IHsKICAgICAgICAiZ3RlIjogIjIwMTctMDEtMDEiLAogICAg
ICAgICJsdCI6ICIyMDE3LTAzLTMxIgogICAgICB9CiAgICB9LAogICAgImZpcnN0X25hbWUiOiB7
CiAgICAgICAgInR5cGUiOiJ3aWxkY2FyZCIsCiAgICAgICAgInZhbHVlIjoiSioiCiAgICB9CiAg
fQp9'

That’s all it takes to create flexible profile-based searching using TrueVault Users. Check out our posts on user registration and user login for more information on managing users in TrueVault.