Custody API Guide
How the P2PE Manager assists merchants by facilitating the chain of custody transfers required for PCI compliance.
Every device must have its location and custodian recorded at all times. Some of these custody records are automatically created as a device moves through its lifecycle. For example, when a Key Injection Facility (KIF) creates a device or creates a shipping entry, custody records are automatically created on our system. Our system also allows merchants to record post-activation changes in custody through the GUI or APIs. Post-activation changes include devices that have been moved from one location to another or reassigned from one custodian to another.
URL escaping the Device Type
When making an API call to our Custody endpoints the URL must include the device serial number and device type name. Some of the device type names are not URL friendly; therefore, they have to be passed through a URL escape function before including them in the URL. For example, the device type iPP350/320 is escaped to iPP350%2F320 before it is included in the URL https://cert-apis.p2pemanager.com/api/v1/devices/100294/iPP350%2F320/custody.
Listing a Device's Custody Records
To list a device's custody record you need to call the GET all Custody endpoint on the APIs. The endpoint requires that you include the device serial number and device type name in the URL. So, for the following device the URL would be https://cert-apis.p2pemanager.com/api/v1/devices/123123123/IDtech%20SecuRED/custody
To retrieve the device details:
GET https://cert-apis.p2pemanager.com/api/v1/devices/175108
Authorization: Basic dXNlcjpwYXNzd29yZA==
Response:
{
"id": "175108",
"serialNumber": "123123123",
"alternateKey": null,
"name": null,
"deviceType": {
"id": "23",
"name": "IDtech SecuRED"
},
"deviceState": {
"id": "2",
"name": "Injected"
},
"kif": {
"id": "4",
"name": "Kriptithe Technologies"
},
"location": {
"id": "4",
"name": "Spencer Tech"
},
"partner": {
"id": "6580",
"name": "ASM Software"
},
"client": {
"id": "4684",
"name": "The Tired Window"
},
"injectKey": {
"id": "1",
"name": "ANSI TEST KEY (3)",
"index": 3
},
"deviceBuild": {
"id" : 130,
"name" : "SREDKey 2 - PTS 5.X",
"buildNumber" : "IDTECH-007"
},
"initializedDate": null,
"activationDate": null,
"auditNextDate": "2021-01-19T12:07:13.324Z",
"auditNotificationDate": null,
"errorCounter": null,
"errorLastDate": null,
"initializedBy": null,
"activatedBy": null,
"createdBy": {
"id": "56",
"userName": "kifuser_1"
},
"modifiedBy": {
"id": "56",
"userName": "kifuser_1"
},
"created": "2017-12-15T14:19:11.000Z",
"modified": "2017-12-15T14:19:11.000Z",
"version": 0,
"notes": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
}
Next, call the list custody entries endpoint:
GET https://cert-apis.p2pemanager.com/api/v1/devices/123123123/IDtech%20SecuRED/custody
Authorization: Basic dXNlcjpwYXNzd29yZA==
Response:
{
"total": 2,
"data": [
{
"id": 423361,
"device": {
"id": 175108,
"serialNumber": "123123123"
},
"location": {
"id": 12645
},
"transferMethod": {
"id": 2,
"name": "Manual"
},
"status": {
"id": 2,
"name": "Received"
},
"custodian": {
"id": 11653
},
"completeDate": "2020-01-19T11:15:51.000Z",
"notes": "Altering custody due to change of personnel at site.",
"createdBy": 1577,
"modifiedBy": 1577,
"created": "2021-01-20T11:24:32.000Z",
"modified": "2021-01-20T11:24:32.000Z",
"version": 0
},
{
"id": 206605,
"device": {
"id": 175108,
"serialNumber": "123123123"
},
"location": {
"id": 12645
},
"transferMethod": {
"id": 1,
"name": "Initial"
},
"status": {
"id": 2,
"name": "Received"
},
"custodian": {
"id": 11653
},
"completeDate": "2021-01-11T12:00:00.000Z",
"notes": null,
"createdBy": 11621,
"modifiedBy": 1577,
"created": "2020-02-13T10:50:24.000Z",
"modified": "2021-01-20T11:22:38.000Z",
"version": 1
}
]
}
Recording a Custody Change
To create a custody record for a device you may include the new custodian or location change. Both can be changed in the same API call. The custody status is automatically set to "Received" if the completeDate is included in the API call. If the completeDate is omitted from the API call the status is set to "Not Complete". In this case the new custodian has to record their receipt of the device through the P2PE Manager.
POST https://cert-apis.p2pemanager.com/api/v1/devices/100294/iPP350%2F320/custody
{
"location": {
"id": 12645
},
"custodian": {
"id": 11653
},
"completeDate": "2020-01-20T11:15:51.080Z",
"notes": "Altering custody due to change of personnel at site."
}
Response:
{
"id": 423365
}
Detailed View of Custody Record
To view the custody record in more detail call the GET single Custody endpoint:
GET https://cert-apis.p2pemanager.com/api/v1/devices/123123123/IDtech%20SecuRED/custody/423365
Authorization: Basic dXNlcjpwYXNzd29yZA==
Response:
{
"id": 423365,
"device": {
"id": 175108,
"serialNumber": "123123123"
},
"location": {
"id": 12645
},
"transferMethod": {
"id": 2,
"name": "Manual"
},
"status": {
"id": 1,
"name": "Received"
},
"custodian": {
"id": 11653,
"userName": "jsmith"
},
"completeDate": "2021-01-20T11:25:19.000Z",
"notes": "Altering custody due to change of personnel at site.",
"createdBy": {
"id": 11621,
"userName": "another"
},
"modifiedBy": {
"id": 11621,
"userName": "another"
},
"created": "2021-01-20T11:25:19.000Z",
"modified": "2021-01-20T11:25:19.000Z",
"version": 0
}
Updated almost 2 years ago