Locate PII data

post

/api/pvlt/1.0/data/analysis/locate

Locates the positions of PII data in text strings and classifies the findings.

If you only need an indication of whether your strings contain PII, use the contains operation.

See the Find PII guide for more information on using this operation.

The role performing this operation must have the CapAnalysisLocate capability.

See identity and access management for more information about how capabilities are used to control access to operations and policies are used to control access to data.

info

This feature is enabled on Vault SaaS only. If you're interested in running it with a self-hosted deployment, please contact us.

Request

Query parameters

• adhoc_reason - string

  An ad-hoc reason for accessing the Vault data. Required when reason is set to Other.

• reason - string

  Details of the reason for requesting the property. The default is set when no access reason is provided and PVAULT_SERVICE_FORCE_ACCESS_REASON is false.

  Allowed values: AppFunctionality, Analytics, Notifications, Marketing, ThirdPartyMarketing, FraudPreventionSecurityAndCompliance, AccountManagement, Maintenance, DataSubjectRequest, Other
• custom_audit - string

  Custom audit information to be included in the audit log.

• reload_cache - boolean

  Reloads the cache before the action.

Request body

The locate request.

application/json

object required*

Additional properties: falseProperties:

• language - string

  Language of the text.

  Default: enAllowed values: de, en, es, it, pt, fr, ja, ko, hi, ar, zh, zh-TWExample: "en"
• text - array of strings required*

  A list of text strings to locate and identify PII in.

  Example

  [
    "My credit card number 1111-0000-1111-0000 has a minimum payment of $24.53."
  ]

Example

{
  "language": "en",
  "text": [
    "My credit card number 1111-0000-1111-0000 has a minimum payment of $24.53."
  ]
}

Possible responses

200

The request is successful.

application/json

array of objects required*

A list of PII entities identified.

Each object:

PII entity identification result.

Additional properties: falseProperties:

• pii - boolean

  Whether the text contains PII.

  Default: trueExample: true
• detections - array of objects

  A list of PII entities identified.

  Each object:

  Identified PII entity type and location.

  Additional properties: falseProperties:

  • type - string

    PII entity type. See Analysis identified PII types for details of the types detected abd codes returned.

    Example: "CREDIT_DEBIT_NUMBER"
  • score - number

    Accuracy of the PII match.

    Example: 0.9999213
  • begin_offset - integer

    Text start offset for the match.

    Format: int32Example: 22
  • end_offset - integer

    Text end offset for the match.

    Format: int32Example: 41

Example

[
  "{\"text\":\"My credit card number 1111-0000-1111-0000 has a minimum payment of $24.53.\",\"entities\":[{\"type\":\"CREDIT_DEBIT_NUMBER\",\"score\":0.99997807,\"begin_offset\":22,\"end_offset\":41}]}"
]

Example

[
  "{\"text\":\"My credit card number 1111-0000-1111-0000 has a minimum payment of $24.53.\",\"entities\":[{\"type\":\"CREDIT_DEBIT_NUMBER\",\"score\":0.99997807,\"begin_offset\":22,\"end_offset\":41}]}"
]

400

The request is invalid.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."
• error_url - string

  The URL to the error documentation.

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

{
  "error_code": "PV1001",
  "message": "The access reason is missing.",
  "context": {
    "reason": null
  }
}

401

Authentication credentials are incorrect or missing.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."
• error_url - string

  The URL to the error documentation.

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

{
  "error_code": "PV1005",
  "message": "The request is unauthorized.",
  "context": {}
}

403

The caller doesn't have the required access rights.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."
• error_url - string

  The URL to the error documentation.

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

{
  "error_code": "PV1007",
  "message": "The operation is forbidden due to missing capabilities.",
  "context": {
    "username": "WebServer"
  }
}

404

The requested resource is not found.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."
• error_url - string

  The URL to the error documentation.

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

{
  "error_code": "PV1004",
  "message": "The collection is not found.",
  "context": {}
}

405

The operation is not allowed.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."
• error_url - string

  The URL to the error documentation.

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

{
  "error_code": "PV1026",
  "message": "The operation is not allowed in in-memory mode.",
  "context": {}
}

409

A conflict occurs.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."
• error_url - string

  The URL to the error documentation.

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

{
  "error_code": "PV3218",
  "message": "Concurrent conflicting updates to the same object.",
  "context": {}
}

410

Access to a resource that is no longer available occurs.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."
• error_url - string

  The URL to the error documentation.

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

{
  "error_code": "PV1033",
  "message": "The resource is gone.",
  "context": {}
}

500

An error occurs on the server.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."
• error_url - string

  The URL to the error documentation.

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

{
  "error_code": "PV1000",
  "message": "Something went wrong",
  "context": {}
}

503

The service is unavailable.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."
• error_url - string

  The URL to the error documentation.

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

{
  "error_code": "PV1009",
  "message": "The operation timed out on the server.",
  "context": {}
}

Try the API

Authorization

API key:

Query parameters

Adhoc_reason:

Reason:

Custom_audit:

Reload_cache:

Request body

Content-Type:

Navigate to the docs of your local Vault installation to try the API directly from there.

Code examples

Example