Working with API

PRIVO Protect API supports two type of search:

  • search by plain value
  • search by hashed value

Supported attribute type

By now there are two type of attributes supported by PRIVO Protect service. It's email and phone

Plain value

It's used when partner has plain text value of attribute and can disclose it via search query.

To make a lookup request:

  • authenticate as a partner (API_KEY or client_credentials)
  • choose attribute type
  • specify service_identifier (corresponds to partner name)
  • specify jurisdiction. Depending on partner jurisdiction some date may or may not be returned. We'll cover it in a separate chapter.
  • provide plain text value

Success lookup sample JSON Response :

POST [Endpoint]/api/v1.0/s2s/lookup/by-plain-value/[ServiceIdentifier]/[JurisdictionIdentifier]
Host: https://registry-svc-int.privo.com
Content-Type: application/json
Authorization: Bearer eyJraWQiOiJyc2..Q.eyJzdWIiOiJwcml2b2xv
  {
    "att_type": "email",
    "value": "test@email.com"
  }
]'

HTTP/1.1 200 OK
[
  {
    "att_type": "email",
    "value": "test@email.com",
    "status": "found",
    "is_under_21": true
  }
]

Not found response: 

HTTP/1.1 200 OK
[
  {
    "att_type": "email",
    "value": "7802b09d0c9a....aa0e8ab982e",
    "status": "not_found"
  }
]

Hash value

It's used when partner don't want to share with PRIVO plain text of user data. IN that case partner must generate SHA-512 hash of text value and pass to PRIVO API

To make a lookup request:

  • authenticate as a partner (API_KEY or client_credentials)
  • choose attribute type
  • specify service_identifier (corresponds to partner name)
  • specify jurisdiction. Depending on partner jurisdiction some date may or may not be returned. We'll cover it in a separate chapter.
  • provide plain text value

Success lookup sample JSON Response :

POST [Endpoint]/api/v1.0/s2s/lookup/by-hash/[ServiceIdentifier]/[JurisdictionIdentifier]
Host: https://registry-svc-int.privo.com
Content-Type: application/json
Authorization: Bearer eyJraWQiOiJyc2..Q.eyJzdWIiOiJwcml2b2xv
  {
    "att_type": "phone",
    "value": "a125be108860...bce39bb58b1b42e775201336"
  }
]'

Example responses:

HTTP/1.1 200 OK
[
  {
    "att_type": "phone",
    "value": "a125be108860...bce39bb58b1b42e775201336",
    "status": "found",
    "is_under_21": true
  }
]

Not found response:

HTTP/1.1 200 OK
[
  {
    "att_type": "email",
    "value": "7802b09d0c9a....aa0e8ab982e",
    "status": "not_found"
  }
]

Bad data response:

HTTP/1.1 200 OK
[
{
"att_type": "phone",
"value": "bad_plain_text.data",
"status": "bad_data"
}
]

Responses

As seen - response is always 200 OK and contains array of found attributes. If attribute found original value will be returned to match it with provided from the client.

Possible statuses:

  • found - attribute found
  • not_found - attribute not found
  • bad_data - special status for situations when search by hashed was invoked by plain text string was provided as a search criteria.

Attribute metadata

Depending on partner configuration API may return additional data related to a found attribute: Those are:

  • birthdate
  • birthdate_precision (yyyymmdd)
  • expire_at
  • is_18_or_over
  • is_21_or_over
  • is_25_or_over
  • is_55_or_over
  • is_60_or_over
  • is_65_or_over
  • is_under_13
  • is_under_14
  • is_under_15
  • is_under_16
  • is_under_17
  • is_under_18
  • is_under_21