Consent Docs
Open console

Find a person's records

List every consent record held for one person by an identifier your systems use, and link identifiers you learn later.

How-to2 min readFor web, backend and mobile developers

Look a person up when you build an account privacy page, a support tool, or before you answer a rights request. One call lists every record held under an identifier, or linked to it.

Before you start#

  • A secret key with the scope subjects:read. Grant it under Scopes on the key in Install. A call without the scope is refused with 403 SCOPE_REQUIRED.
  • The client from Record consent from your server.

Find the records#

  1. Choose the identifier and its type. Write a phone number the way you recorded it, such as E.164.

  2. Call findSubject. The identifier goes in the request body, and subjectType is required.

    Node.jsJavaScript
    const found = await client.findSubject('+919846011223', 'PHONE');

for (const record of found.records) {
  console.log(record.consentId, record.status, record.matchedBy);
}
    Python
    found = client.find_subject("+919846011223", "PHONE")

for record in found["records"]:
    print(record["consentId"], record["status"], record["matchedBy"])
    cURLShell
    curl -X POST https://console.dpconsent.com/consent/sdk/v1/subjects/find \
  -H "Authorization: Bearer $PIEDAP_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subjectId": "+919846011223", "subjectType": "PHONE" }'

  3. Read records. They are listed oldest first.

The answer, shortened:

JSON
{
  "subjectType": "PHONE",
  "fingerprint": "41d2c7…",
  "records": [
    {
      "consentId": "cns_3f1c9a7e2b8d4c6fa0e5d1b7c9f2a4e8",
      "status": "PARTIAL",
      "lawCode": "DPDP",
      "test": false,
      "erasedOn": null,
      "matchedBy": ["PHONE"]
    }
  ]
}
  • matchedBy lists the identifier types that matched the record. This record was recorded under a user id and found through its linked phone number.
  • erasedOn is set on records that have been erased. They stay in the list, without identifiers.
  • fingerprint is the subject fingerprint of the identifier you sent.
  • An empty records list means nothing is held under that identifier. It is not an error.

The calls on a person reach only records of the key's own kind. A test key sees test records, and a live key sees live records.

To make a person's records findable by a new identifier, such as a phone number added to an account, call linkIdentifiers. It needs the scope subjects:link.

Node.jsJavaScript
const result = await client.linkIdentifiers(
  'usr_8f2K1xQz',
  'USER_ID',
  [{ subjectType: 'PHONE', subjectId: '+919846099887' }],
  { idempotencyKey: 'phone-usr_8f2K1xQz-919846099887' },
);
// { records: 2, added: 2 }
Python
from piedap_consent import Identifier

result = client.link_identifiers(
    "usr_8f2K1xQz",
    "USER_ID",
    [Identifier("PHONE", "+919846099887")],
    idempotency_key="phone-usr_8f2K1xQz-919846099887",
)
# {"records": 2, "added": 2}
cURLShell
curl -X POST https://console.dpconsent.com/consent/sdk/v1/subjects/link \
  -H "Authorization: Bearer $PIEDAP_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: phone-usr_8f2K1xQz-919846099887" \
  -d '{
    "subjectId": "usr_8f2K1xQz",
    "subjectType": "USER_ID",
    "identifiers": [
      { "subjectType": "PHONE", "subjectId": "+919846099887" }
    ]
  }'
  • The call links up to five identifiers to every record of the person that is not erased.
  • records is how many records the person has. added is how many new links were made.
  • An identifier already linked is skipped, so repeating the call adds nothing.
  • Records made later are not linked by this call. Send identifiers with each new write as well.

What every call on a person shares#

  • Each call is written to the project's audit log with the key's name. The identifier itself is never logged.
  • These calls share a budget of their own, 60 a minute for each key by default, on top of the key's ordinary budget.
  • A request over the budget gets 429 with a Retry-After header.

People endpoints lists every field and error.

↑↓ to move, Enter to open