Identities

About

This article describes Customer Data Hub best practices related to Identities.

Article audience
Data Provider	✓
Data User	✓

Identity creation

On the Trusted Twin platform, Identities are used to identify Twins. You can create Identities through the create_twin_identity endpoint.

On the Customer Data Hub, Identities must be hashes created using the Identity hashing convention described in this article.

Data Provider Best Practices

Best practices for Data Provider organizations when creating Identities:

• When creating Identities, you need to ensure that the Identities are visible to the given Data User organizations. The "visibility" field value can be set when creating Identities create_twin_identity or modified with the update_twin_identity operation. If you want the Identity value to be visible in the entire Trusted Twin system, set the value of the "visibility" field to "true".

Identity hashing

The Twin Identity on the Customer Data Hub is a hash. The hashing of Identities is an application of PETs (Privacy Enhancing Technologies). It enhances the privacy of customer’s data through operating on hashes that can’t be reversed to find the original input string.

The hash is generated following the same convention described below by both the Data Provider organization and the Data User organization. In order to get the Twin UUID in the response to the endpoint, the hashes generated by the Data Provider organization and the Data User organization must match.

Hash elements

The hash is composed of the following elements:

Element	Description	Example
TT_HASHED_ID_PREFIX	Obligatory prefix denoting a hashed identity on the Trusted Twin platform. The prefix should be always HID#.	HID#
id_type	Type of customer identifier used (for example, email or mobile phone number). Please note that the value should be exactly as in the table below, as even small modifications will result in generation of a different hash.	email
id_data	Customer identifier to be hashed.	name@example.com

ID types and data

Below you can find id_type values and id_data examples for selected identifiers.

Identifier	id_type value	id_data value example	Comments
email address	email	name@example.com
phone number	phone	+48777888999	The format follows the Notation for national and international telephone numbers(opens new window) recommendation by International Telecommunication Union (ITU)(opens new window). In our example, the identifier is composed of a + (plus) sign indicating the international dialing prefix, country code (48), and the mobile phone number (777888999).
VAT identification number	VATIN	PL1234567819
PESEL number	PESEL	STE44051401458	The identifier is composed of capitalized 3 first letters of customer's surname (in the example it is Stępień). The letters must be letters of the ISO basic Latin alphabet(opens new window) (in the example the letter ę was replaced with E).
IBAN	IBAN	PL83101010230000261395100000
Organization Info Twin UUID	info_twin	cbae6e15-77a0-41ed-954d-26578cf5a4dc	UUID of the Twin

Hashing function

Examples

Below you can find examples of hashes generated using example values.

Identifier	Prefix	id_type	id_data example	Generated hash
email address	HID#	email	name@example.com	HID#lYyzHf_CWXSeuIM1OcDnsjtbQ8jz
phone number	HID#	phone	+48777888999	HID#l2TS5rfZzl7aHlts60hXrX-hR9ap
VAT identification number	HID#	VATIN	PL1234567819	HID#CNRxcb_h0aFqJRQ3rFzvKx_bNRH0
PESEL number	HID#	PESEL	STE44051401458	HID#qw0driY9ACSWpsi26pXmvm5D7JNQ
IBAN	HID#	IBAN	PL83101010230000261395100000	HID#9GKh3eQnqHHyjlfoF8geAKB5y2yA
organization_info_twin	HID#	info_twin	cbae6e15-77a0-41ed-954d-26578cf5a4dc	HID#k0k7sKq5qbdA5UOTVSb5jA0aYo8M

Identity resolution

The resolve_twin_identity operation is used by Data User organizations to resolve a Twin Identity in order to obtain the UUID of a Twin. The Twin represents a given customer and the unique identifier of the Twin provides access to this customer’s data (as defined by the Data Provider organization for this Data User organization) for the Data User organization.

The request to this endpoint takes the following parameters:

Parameter	Type	In	Description
{identity} required	string	path	Hash created using the “generate_hashed_id” function. For more details, please see the Identity hashing section.
context optional	string, value is {account}, personal, or system, DEFAULT=personal	query string	Additional context to narrow the list of Identities to be included in the search. The requestor from the Data User organization should use either the {account} value or system: - {account}: Account UUID. Identities owner by the specified account and visible to the requesting user. - system: Identities in the entire Trusted Twin ecosystem visible to the requesting user.
details optional	boolean, DEFAULT=False	query string	Denotes whether the details of each Twin should be returned.

Data User Best Practices

Best practices for Data User organizations when making requests to the endpoint:

• The "identity" parameter is required. This is the hashed ID generated with the “generate_hashed_id” function (for more details, please refer to the Identity hashing section).
• The "context" parameter allows for narrowing the list of Identities to be included in the search. The requestor from a Data User organization should include either the unique identifier of the Data Provider account to narrow the search to the Data Provider’s organization account or define the value as system - this will include in the search all Identities in the Trusted Twin system visible to the requesting user.
• If the "details" parameter with the value True is included in the query string of the request, not only the unique identifier if the Twin UUID will be returned, but the details of the Twins. The response to the request with the "details" parameter set to True will always include the account UUID of the account that owns the Twin (value of the"owner" property). If the Data Provider organization included additional information in the "description" property of the Twin, this will be also visible to the requesting user.

Data Provider Best Practices

Best practices for Data Provider organizations:

• If the Data User organization should only request to resolve Identities in the context of your account, you need to provide them with the UUID of your account. This way, they will be able to add the unique identifier as value of the "context" parameter. You can find the unique identifier of your account by calling the who_am_i endpoint.
• The "description" field of a Twin provides you with the possibility to include additional publicly visible information about the Twin. This way, the Data User organization will be able to view additional information when resolving the Twin’s Identity with the "details" parameter set to True. Please note that the description of a Twin is publicly available, so no customer data or information that you don’t want to be publicly visible should be added to this field.

Further resources

For more information about Identities, please see the Identities section.
For more information about the create_twin_identity operation, please consult the create_twin_identity article in the Reference section. For more information about the resolve_twin_identity operation, please consult the resolve_twin_identity article in the Reference section.