List Cards API V2

POST https://secure-{REGION}.id123.io/api/v2/ action: list-cards

New to the API?

Start with the API V2 Introduction for authentication, terminology (IDMS, Card Template, API Key), and a full endpoint list.

Introduction

This API is used to retrieve all cards information (limited info) for the specified template id that exists within an institution’s account. The API request includes pagination options for cards. A ‘limit’ and ‘offset’ can be passed along with the api-key to retrieve a set of card data from the system. These fields are optional. If nothing passed in the request then the first 10 cards will be returned in the response.

limit defaults to 10 and can be up to 500. To get the next page, add the limit to offset.

Request Format

POST /api/v2/ HTTP/1.1
Host: secure-{REGION}.id123.io
X-API-KEY: API_KEY
Content-Type: application/json

{
   "action": "list-cards",
   "card-template-id": "CARD_TEMPLATE_ID",
   "limit": 100, // optional, default 10, max 500
   "offset": 0   // optional, default 0
}

Success Response

In the response, image[].value is a URL that ID123 generates for the cardholder’s photo. It is not the URL or file that was originally sent.

{
   "status": "success",
   "code": "S2010",
   "message": "Template cards were retrieved successfully.",
   "data": [
       {
            "card-template-id": "CARD_TEMPLATE_ID",
            "card-id": "CARD_ID",
            "card-status": "CARD STATUS",
            "card-sub-status": "CARD SUB STATUS",
            "institution": "INSTITUTION NAME",
            "issuance-type": "ISSUANCE TYPE",
            "card-title": "CARD TITLE",
            "created-at": "2019-12-09T06:43:19+00:00",
            "last-updated": "2020-10-20T03:37:43+00:00",
            "card-expiration": "EXPIRATION TIMESTAMP",
            "barcode": [
                {
                    "key": "barcode",
                    "value": "BARCODE_VALUE",
                    "label": "Barcode Value"
                }
            ],
            "image": [
                {
                    "key": "id-photo",
                    "value": "PHOTO URL",
                    "label": "ID PHOTO"
                }
            ],
            "name-fields": [
                {
                    "key": "name",
                    "value": "FIELD VALUE",
                    "label": "FIELD LABEL"
                }
            ],
            "front-fields": [
                {
                    "key": "front-1",
                    "label": "FIELD LABEL",
                    "type": "FIELD TYPE",
                    "value": "FIELD VALUE"
                }
            ]
        }
   ]
}

Failure Response

{
    "status": "failure",
    "code": "ERROR CODE",
    "message": "ERROR MESSAGE"
}

Errors

This action can return the errors below, as well as the Common API Errors. Placeholders such as {CUSTOM-VALUE-1} are explained in Status Codes.

Status Code	Status Message
F203	Card template was not found.