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 the API – Get Card Data. If you want to update the data in this “card-id” use the API – Update Card Data.
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
Content-Length: 993
{
"action": "create-card",
"upsert-record":"true/false", // optional
"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": [
// An image can be passed as a photo URL.
{
"key": "id-photo",
"value": "PHOTO URL"
},
// Alternatively, an image can be passed as base64 encoded data.
{
"key": "id-photo",
"value": "BASE64_IMAGE_DATA", // Sample : data:image/png;base64,iVBORw0KGgoAAAA.....JRU5ErkJggg==
"type": "base64-encoded-image"
}
],
"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"
}
]
}
}
Success Response¶
{
"status": "success",
"code": "S2001",
"message": "SUCCESS MESSAGE",
"card-id": "CARD_ID",
"card-template-id": "CARD_TEMPLATE_ID"
}