Update Card API V2¶

POST https://secure-{REGION}.id123.io/api/v2/ action: update-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 update card information. You need to provide update data as a key-value pair to update a card’s information. Expired cards can also be renewed using this API. Here, api-key, card-template-id and card-id are used to identify the card data to update. You can only update one card at a time. You are only required to pass the card-data key value pairs being updated. Passing a key value pair with an empty value will update the value to empty. Card status cannot be updated using this API. If you attempt to update a record that does not exist, an error will be thrown unless ‘upsert-record’ is set to true. If upsert record is set to true then a new card record will be added if the card-id does not exist.

Requests Format¶

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

{
   "action": "update-card",
   "upsert-record": false, // optional, true or false
   "card-template-id": "CARD_TEMPLATE_ID",
   "card-id": "CARD_ID",
   "unique-identifier": "UNIQUE IDENTIFIER",
   "security-question-1": "SECURITY QUESTION 1",
   "security-question-2": "SECURITY QUESTION 2",
   "card-expiration": "yyyy-mm-ddThh:mm:ss+00:00", //UTC
   "recipient-email": "RECIPIENT EMAIL",
   "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": "VALUE"
      }
    ],
    "image": [
      // Send one entry per key. Choose ONE input type for id-photo (see Images below).
      // Option 1: base64-encoded image data (up to 2 MB)
      {
        "key": "id-photo",
        "value": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
        "meta": { "input-type": "base64" }
      }
      // Option 2: a public HTTPS URL that ID123 downloads
      // { "key": "id-photo", "value": "https://example.com/photos/10442.jpg", "meta": { "input-type": "url" } }
      // Option 3: the file name of a photo already uploaded in a ZIP in the IDMS
      // { "key": "id-photo", "value": "10442.jpg", "meta": { "input-type": "filename" } }
    ],
    "name-fields": [
      {
        "key": "name",
        "value": "NAME"
      }
    ],
    "front-fields": [
      {
        "key": "front-1",
        "value": "VALUE"
      },
      {
        "key": "front-2",
        "value": "VALUE"
      }
    ],
    "secondary-fields": [
      {
        "key": "secondary-1",
        "value": "VALUE"
      },
      {
        "key": "secondary-2",
        "value": "VALUE"
      }
    ],
    "back-fields": [
      {
        "key": "back-1",
        "value": "VALUE"
      },
      {
        "key": "back-2",
        "value": "VALUE"
      }
    ]
  }
}

Images¶

The image array sets the cardholder’s ID photo (id-photo) and, where the template shows one, a card logo (logo). Send at most one entry per key. To leave a photo unchanged, leave the entry out.

`meta.input-type`	`value`	Use when
`base64`	A data URI, e.g. `data:image/png;base64,...`	You have the image file and send JSON. Keep images under 2 MB.
`url`	A public HTTPS URL	The image is already hosted. ID123 downloads it after the card is updated.
`filename`	The file name, e.g. `10442.jpg`	You uploaded photos in a ZIP in the IDMS first (How to Upload ID Photos in Bulk via Zip File).

Supported formats are JPEG, PNG and WebP. The logo key accepts a URL only. Images sent by URL are processed after the response, and any problems appear in the IDMS import log.

The older form "type": "base64-encoded-image" still works. New integrations should use meta.input-type.

Success Response¶

{
   "status": "success",
   "code": "S2002",
   "message": "SUCCESS MESSAGE.",
   "card-id": "CARD_ID",
   "card-template-id": "CARD_TEMPLATE_ID"
}

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.
F204	Invalid value for `{CUSTOM-VALUE-1}` field. Please enter a valid `{CUSTOM-VALUE-2}` value.
F205	`{CUSTOM-VALUE-1}` value exceeds limit.
F206	Customer having same Security Question 1(or 2) value already exists
F209	Card was not found.
F210	ID photo URL length should not exceed character limit
F214	Unique identifier already exists.
F215	Invalid `{CUSTOM-VALUE-1}` format. Please provide the date in yyyy-mm-dd or mm/dd/yyyy format.
F217	Missing or invalid barcode value.
F221	Something went wrong during card generation.
F254	Missing or invalid image key.
F255	Missing or invalid image value.
F256	Missing or invalid image input-type.
F263	`{CUSTOM-VALUE-1}` exceeds the maximum length of `{CUSTOM-VALUE-2}`.