Obfuscating response data

Cloud API supports the ability to obfuscate data that is included in a response. Response data can be either nullified or masked.

When response data is nullified, its value is returned as null.
When response data is masked, a portion of its value is returned with placeholder characters, such as a tax ID being returned as "xxx-xx-1781".

The primary type of response data that is obfuscated is Personally Identifiable Information (PII). Insurers must comply with any data protection and privacy regulations of the jurisdictions in which they operate. For example, companies operating in the European Union must abide by the General Data Protection Regulation (GDPR) within that jurisdiction. These regulations often specify that Personally Identifiable Information (PII) must be obfuscated.

Nullifying response data

You can nullify the response data by configuring the mapper for the relevant property. This is done in a mapping extension file. For more information on mapping extension files, see Overview of schema configuration files.

Masking response data

You can mask response data by writing a Gosu method and modifying the mapper for the relevant resource property to use that method.

For details on implementing Gosu code, see the Configuration Guide.
For more information on mapping extension files, see Overview of schema configuration files.

Changing the masking pattern

To change the masking pattern applied to a resource property, you can either revise the existing masking Gosu method or write a new one.

Unmasking PII

Conversely, you can unmask PII that has been masked in the base configuration. This can be necessary when you need to expose the PII to a specific internal role, such as administrator. In such circumstances, Guidewire recommends that you create a new schema extension for the masked property. For example, if you wish to unmask the taxId property, you would create a taxIdUnmasked_Ext schema property that is mapped directly to the TaxID entity field. In such a case, Guidewire recommends that you also allowlist the extended property to make it visible only to authorized roles. For details on creating resource extensions, see Overview of schema configuration. For details on allowlisting fields, see Endpoint access.

Important: Nothing in the Cloud API infrastructure prevents configuration that could expose PII in a sensitive way. For example, if you specify taxId as a filterable parameter or sortable, it can be included as part of the URL in a request and is more likely to appear in application logs.

Unmasking the base configuration taxID field

Contact resources have a taxID field which stores the tax ID of the contact. In the Cloud API base configuration, this field is masked in responses so that only the last four digits appear. For example, the following is the response for a GET that retrieves a contact.

{
    "data": {
        "attributes": {
            "displayName": "Ray Newton",
            "taxId": "***-**-6789"
        }
    }
}

For some callers, such as internal or external users, the masking of tax ID may be appropriate as it protects personally identifiable information. For other callers, such as services, this masking may cause a problem as the callers may reference contacts internally using the tax ID.

There are two ways that the taxId field can be unmasked:

You can configure the field so that it is always unmasked, as described in the previous topic.
You can grant the caller the restunmasktaxid system permission. Any caller who has a role with this permission will get responses with unmasked tax IDs. For information on how to configure this, see Endpoint access.

Note that the restunmasktaxid system permission changes the behavior of the base configuration taxId field only. It has no impact on any other masked data.