Data Whitelisting

Whitelist the data you want to see to help reduce the sensitive information that hits your servers.

Cognito’s data whitelisting uses the JSON API inclusion pattern to choose the data you would like to see in your response. The primary purpose of this mechanism is to allow you to cherry pick the data you would like to use in your application and not receive anything else.

The whitelist is defined using an include query parameter like so:

/identity_searches/?include=identity_records.phones,identity_records.names

If no include query parameter is provided, all data will be shown. If the includequery parameter is provided then only the whitelisted data will be shown.

Below are the supported attributes for whitelisting. This is currently only supported on the /identity_searches endpoint.

• identity_records
• identity_records.names
• identity_records.phones
• identity_records.addresses
• identity_records.ssns
• identity_records.births
• identity_records.deaths

Examples

In this example we will create an identity search and opt-in to only seeing the names returned in the identity records.

The whitelisting feature still lets you see the existence of the non-whitelisted data points, however the actual data associated with them is not displayed.

In this example, you will see that the user does have an SSN on file, however it is not displayed because the identity_records.ssns value has not been whitelisted.

POST https://sandbox.cognitohq.com/identity_searches?include=identity_records.names HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Cognito-Version: 2016-09-01

{
  "data": {
    "type": "identity_search",
    "attributes": {
      "phone": {
        "number": "+16508007985"
      }
    },
    "relationships": {
      "profile": {
        "data": {
          "type": "profile",
          "id": "prf_3s527AoQo6Dw62"
        }
      }
    }
  }
}

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
Location: /identity_searches/idnsch_9cLibuU8CGL5Tw
Content-Location: /identity_searches/idnsch_9cLibuU8CGL5Tw

{
  "data": {
    "type": "identity_search",
    "id": "idnsch_9cLibuU8CGL5Tw",
    "attributes": {
      "created_at": "2016-04-01T13:59:59Z",
      "phone": {
        "number": "+16508007985"
      }
    },
    "relationships": {
      "profile": {
        "data": {
          "type": "profile",
          "id": "prf_3s527AoQo6Dw62"
        }
      },
      "identity_records": {
        "data": [
          {
            "type": "identity_record",
            "id": "idnrcd_4jAKBtpgUYqotf"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "identity_record",
      "id": "idnrcd_4jAKBtpgUYqotf",
      "attributes": {},
      "relationships": {
        "addresses": {
          "data": [
            {
              "type": "us_address",
              "id": "usaddr_6McNRg4HYpisQ4"
            }
          ]
        },
        "names": {
          "data": [
            {
              "type": "name",
              "id": "nam_5wwLicAvxWDyGm"
            }
          ]
        },
        "ssns": {
          "data": [
            {
              "type": "ssn",
              "id": "ssn_a29MVUXXtn1hHU"
            }
          ]
        },
        "phones": {
          "data": [
            {
              "type": "phone",
              "id": "phn_8NhXuWAD1rvYzo"
            }
          ]
        },
        "births": {
          "data": [
            {
              "type": "birth",
              "id": "bth_9SfmTjQWh6DD6n"
            }
          ]
        },
        "deaths": {
          "data": [
            {
              "type": "death",
              "id": "dth_dXzK8dDoqAR96N"
            }
          ]
        }
      }
    },
    {
      "type": "name",
      "id": "nam_5wwLicAvxWDyGm",
      "attributes": {
        "first": "John",
        "middle": "Jacob",
        "last": "Smith"
      }
    }
  ]
}