Custody API Guide

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 Devices moves through their lifecycle. For example when the KIF creates the device or creates a shipping entry Costody records are automatically created on our system. Our system also allows merchants record post activation changes in custody through the GUI or APIs.

Our Custody APIs allows the merchant record when a Device has been moved from one location to another or when it has been assigned from one custodian to another.

📘

URL escaping the Device Type

When making an API call to our custody endpoints the URL has to 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 Records 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 this device we can 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
}

Did this page help you?