View Card API V2

POST https://secure-{REGION}.id123.io/api/v2/ action: view-card

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 detailed card information that already exists in the institution’s account. If you do not pass the correct ‘card-id’ or ‘card-template-id’ for the card that you are trying to retrieve, you will receive an error. All request parameters are mandatory to get the right card. A “list-cards” API returns limited information about cards and users must use the “view-card” API to get detailed information.

Request Format

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

{
   "action": "view-card",
   "card-template-id": "CARD_TEMPLATE_ID",
   "card-id": "CARD_ID"
}

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.

{
    "action": "view-card",
    "status": "success",
    "code": "S2004",
    "message": "SUCCESS MESSAGE",
    "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": "INSTITUTION ISSUED",
        "card-title": "CARD TITLE",
        "created-at": "yyyy-mm-ddThh:mm:ss+00:00", //UTC,
        "last-updated": "UPDATED AT TIME",
        "card-expiration": "yyyy-mm-ddThh:mm:ss+00:00", //UTC
        "access-control":{
           "acs-identifier":"ACCESS_CONTROL_SYSTEM_USER_IDENTIFIER", // Unique Identifier under ACS
           "acs-groups":"ACCESS_CONTROL_SYSTEM_PERMISSION_GROUPS" // comma-separated list of access groups
        },
        "card-data": {
            "barcode": [
                {
                    "key": "barcode",
                    "value": "",
                    "label": "barcode"
                }
            ],
            "image": [
                {
                    "key": "id-photo",
                    "value": "PHOTO URL",
                    "label": "ID PHOTO"
                }
            ],
            "name-fields": [
                {
                    "key": "name",
                    "value": "VALUE",
                    "label": "Name"
                }
            ],
            "front-fields": [
                {
                    "key": "front-1",
                    "label": "FIELD LABEL",
                    "type": "FIELD TYPE",
                    "value": "FIELD VALUE"
                }
            ],
            "secondary-fields": [
                {
                    "key": "secondary-1",
                    "label": "FIELD LABEL",
                    "type": "FIELD TYPE",
                    "value": "FIELD VALUE"
                }
            ],
            "back-fields": [
                {
                    "key": "back-1",
                    "label": "FIELD LABEL",
                    "type": "FIELD TYPE",
                    "value": "FIELD VALUE"
                },
                {
                    "key": "back-2",
                    "label": "FIELD LABEL",
                    "type": "FIELD TYPE",
                    "value": "FIELD VALUE"
                },
                {
                    "key": "back-3",
                    "label": "FIELD LABEL",
                    "type": "FIELD TYPE",
                    "value": "FIELD VALUE"
                },
                {
                    "key": "back-4",
                    "label": "FIELD LABEL",
                    "type": "FIELD TYPE",
                    "value": "FIELD VALUE"
                }
            ]
        }
    }
}

Failure Response

{
    "status": "failure",
    "code": "ERROR CODE",
    "message": "ERROR MESSAGE",
    "card-id": "CARD_ID",
    "card-template-id": "CARD_TEMPLATE_ID"
}

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
F201	{CUSTOM-VALUE-1} is required.
F203	Card template was not found.
F209	Card was not found.