Create Card API V2¶

POST https://secure-{REGION}.id123.io/api/v2/ action: create-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 will generate a new card for a given card template. When you call this API, you have to call it with a unique “card-id” field and it will generate a new card data record. The “card-id” must be unique per Card Template. If you try to call this API again with the same “card-id” field, it will return an error message and fail to generate a new card record. There is an optional parameter ‘upsert-record’, if it passed as true and the card already exists then it will update the existing record. To call this API again successfully without ‘upsert-record’, you will need to use a different “card-id”. If you want to retrieve the data from this “card-id”, use View Card. If you want to update the data in this “card-id”, use Update Card.

Note

If you don’t want to include a photo when creating a card, omit the image node from the request entirely. Don’t send it as an empty or placeholder value; the API validates the contents of the image node whenever it’s present, so an empty or malformed value will cause the request to fail. Only include the image node when you’re passing a valid image resource.

Request Format¶

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

{
   "action": "create-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": [// 3 front fields
      {
        "key": "front-1",
        "value": "VALUE"
      },
      {
        "key": "front-2",
        "value": "VALUE"
      }
    ],
    "secondary-fields": [// 4 secondary fields
      {
        "key": "secondary-1",
        "value": "VALUE"
      },
      {
        "key": "secondary-2",
        "value": "VALUE"
      }
    ],
    "back-fields": [ // 4 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.

`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 created.
`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": "S2001",
   "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.
F202	Card ID already exists.
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
F207	Your template is in draft mode. Please approve your template.
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}`.