Introduction

The purpose of this document is to introduce C# developers on how to utilize the PII Vault API, with code examples. This document should be consistent with what is seen in the PIIVault sample client program, which is an open source program to help developers walk through how the API is used.

All requests in the API return a JSON response with some specific fields that make all API responses consistent regardless of what end point is called.

Accompanying Classes

Several C# classes were written in this project to assist in more mundane tasks of calling the API. This document will explain each part so if a developer decides to write their own classes or methods, they fully understand what to expect.

ApiResponse.cs

Standard C# class to represent all responses that the API returns, regardless if the request is a success or not. Contains success Boolean and error information if the API has returned with any error.

ApiError.cs

Key and message class to give off specific information on an error returned back from the API.

ApiResponseT.cs

Child class that inherits from ApiResponse class, but with generics to contain data or information that can be specific to the end point used.

HttpService.cs

HTTP call service class the call each end point in the API. Uses the standard System.Net.Http library in .NET to make it’s calls. Uses standard HTTP methods as the method also tells the API which specific action to perform.

Also uses JSON deserializer classes found in the System.Text.Json found in .NET to wrap the JSON returned from the API into C# objects.

Models Folder

Simple C# classes designed to be used to send and receive data from the API.

Requests – General

The following classes represent the data sent to and from our API as JSON

Class	Property	Type
ProfileModel
	SourceSystemKey	String
	FirstName	String
	MiddleName	String
	LastName	String
	DateOfBirth	DateTime
	Gender	String
	Emails	ProfileEmailModel
	Phones	ProfilePhoneModel
	Addresses	ProfileAddressModel
	Keys	ProfileKeyModel
ProfileEmailModel
	PhoneType	String
	PhoneOwner	String
	PhoneNumber	String
ProfileAddressModel
	AddressType	String
	StreetAddress1	String
	StreetAddress2	String
	City	String
	State	String
	Zip	String
	Country	String
ProfileKeyModel
	KeyType	String
	KeyOwner	String
	KeyValue	String
PseudonymRequestModel
	SeedValue	Integer
	SourceSystemKey	String

Request: Profile(s)

This class is used to request specific actions for one or more profiles

Class	Property	Type
ProfileRequest
	Index	Int
	SourceSystemKey	string
	PolyId	Guid

Responses – General

The classes below represent data returned from our API as JSON

Class	Property	Type
ProfileListResponseModel
	ProfileResponseModel	List
ProfileResponseModel
	Index	Integer
	SourceSystemKey	String
	PolyId	Guid
ProfilePseudonymModel
	ReturnCode	Integer
	SourceSystemKey	String
	DateOfBirth	DateTime
	Gender	String
	FirstName	String
	MiddleName	String
	LastName	String
	EmailAddress	String
	Address	String
	Phone	String
	KeyType	String
	KeyValue	String
	Street1	String
	Street2	String
	City	String
	State	String
	Zipcode	String
	Message	String

Generating API Tokens for Authorization

Tokens to use the API are required before any actual call to anonymize any data. This is done via the API end point at: https://api.piivault.com/api/auth/login

The request body sent to this end point should look like:

{ “AccountId”: “[Account ID]”, “ApiKey”: “[API Key]” }

The request of this token within our source code can be found as such:

var httpService = new HttpService();

var model = new LoginModel{

AccountId = Guid.Parse(accountId),

ApiKey = key

};

var response = await httpService.PostAsync<TokenModel>(“https://api.piivault.com/api/auth/login “, model);

if (response.Success) {

Token = response.Data.Token;

}

else

{

Token = null;

}

This “Token” variable will then be passed into the header of all other subsequent requests. If the call is a success, this token will need to be added to the security headers like so:

var _httpClient = new System.Net.Http.HttpClient();

_httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(“Bearer”, Token);

Using the API After Authorization

Primary points of interest when using this API involve sending the data to anonymize.

Bulk Loading Data to Anonymize

End Point: https://api.piivault.com/api/profiles/GetPolyIdBulk

This is a primary entry point to begin having your data anonymized. It accepts and array of different profiles, there is some set points of data that the API is expecting. A sample request body looks like this:

{

“Profiles”: [

{

“Index”: 0,

“SourceSystemKey”: “string”,

“FirstName”: “string”,

“MiddleName”: “string”,

“LastName”: “string”,

“DateOfBirth”: “YYYY-MM-DD”,

“Gender”: “string”,

“IsForgotten”: 0,

“Emails”: [{“EmailAddress”: “string”}],

“Phones”: [{“PhoneType”: “string”,”PhoneOwner”: “string”,”PhoneNumber”: “string”}],

“Addresses”: [{“AddressType”: “string”,”StreetAddress1″: “string”,”StreetAddress2″: “string”,”City”: “string”,”State”: “string”,”Zip”: “string”}],

“Keys”: [{“KeyType”: “string”,”KeyOwner”: “string”,”KeyValue”: “string”}

]

}

]

}

This data is to be sent to the API for anonymization. The API returns the data with the matching index and a System Source Key and a Poly ID. To do this in the C# environment, consider the following code block:

ProfileModelBulk profileList = new ProfileModelBulk();

int index = 0;

foreach (DataRow row in _dataTable.Rows) // Iterate from DataTable Rows that had this information

{

var profile = new ProfileModel();

profile.Index = index++;

profile.Addresses = new List<ProfileAddressModel>();

profile.Phones = new List<ProfilePhoneModel>();

profile.Emails = new List<ProfileEmailModel>();

profile.Keys = new List<ProfileKeyModel>();

profile.SourceSystemKey = row[“Profile Id”].ToString();

profile.FirstName = row[“First Name”].ToString();

….. // Manually add in the other data points

profileList.Profiles.Add( profile);

}

var response = await _httpService.PutAsync<ProfileListResponseModel>(“/api/profiles/GetPolyIdBulk”, profileList);

Get Poly ID

The GetPolyId endpoint is the same as GetPolyIdBulk except that it is for a single profile.

End Point: https://api.piivault.com/api/profiles/GetPolyId

Similar to Get Poly Bulk ID but is designed to only accept one profile. Just send a single instance of “ProfileModel” class and it will work exactly the same.

Examples:

var response = await _httpService.PutAsync<Guid>(“/api/profiles/GetPolyId”, profileModel);

DeleteProfile

Endpoint: https://api.piivault.com/api/profiles/DeleteProfile

Sends a request to completely delete one or more profiles. Accepts either a PolyId or a SourceSystemKey.

Request JSON:

{
“Index”: 0,
“SourceSystemKey”: “string”,
“PolyId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”
}

Example:

var response = await _httpService.ForgetAsync<bool>(“/api/profiles/DeleteProfile”, json);

Forget Profile

Endpoint: https://api.piivault.com/api/profiles/ForgetProfile

Sends a request to “forget” a profile. Accepts one or more profile request models, if a match is found, will mark the profile as “forgotten.” Simple returns a basic API response instance.

Example JSON:

{
“Index”: 0,
“SourceSystemKey”: “string”,
“PolyId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”
}

Example:

var response = await _httpService.ForgetAsync<bool>(“/api/profiles/ForgetProfile”, json);

Purge Profile Information

End Point: https://api.piivault.com/api/profiles/PurgeAccountProfiles

Purges all data from the currently logged in profile attached to the token, no data needed to pass through.

Example:

var response = await _httpService.PutAsync<bool>(“/api/profiles/PurgeAccountProfiles”, true);

Matching

End Point: https://api.piivault.com/api/match

This point takes both a GET and a POST request. It is designed for POST to be performed first in order to perform the needed matching. Afterwards, GET will return the matched results.

Examples:

var response = await _httpService.PostAsync(“/api/match”, accountIds); // request match process

var response = await _httpService.GetAsync<List<MatchTableModel>>(“/api/match”);  // request match results

Poly-Pseudonyms

End Point: https://api.piivault.com/api/ GetProfilePseudonym

This point takes a PUT request.

Example: var response = await _httpService.PutAsync<ProfilePseudonymModel>(“/api/profiles/GetProfilePseudonym”, model);

Conclusion

To get a full grasp of all of the possible end points with this API, you may consult the following URL: https://api.piivault.com/index.html. This should allow a developer to get started using this API and service to help with anonymizing sensitive data.