Card Action API V2¶

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

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 a card status (status & sub status) without updating any card information based on the “status-action” specified in the request. The ‘status-action’ can have any of the following values: “activate”, “deactivate”, “revoke”, and “archive”. If you want to temporarily deactivate a card, you can use the action “deactivate’. When a card is deactivated, the card status will be updated to “Deactivated”. If you want to re-activate a card that has previously been deactivated, you can use the action “activate”. When a card is activated, the card status will be updated to the status of the card prior to deactivation.

If you want to archive a card, you can do that using the “archive” action. When a card is archived, the card status will be updated to “Archived”. If you want to unarchive a card, you can use the action “activate”. When a card is unarchived, the card status will be updated to “Inactive”. To revoke a card from the app user’s device, you can use the action “revoke”. When a card is revoked, the card status will be updated to “Uninstalled”.

Legacy alias

“reactivate” is still accepted as an alias of “activate”, so existing integrations keep working. New integrations should use “activate”.

Card Status Action Table¶

Card Status Action	Description
`DEACTIVATE`	If you want to temporarily deactivate a card, you can use the action “deactivate’. When a card is deactivated, the card status will be updated to “Deactivated”.
`ACTIVATE`	If you want to re-activate a deactivated card, you can use the action “activate”. The previously installed status will persist through activation. If you want to unarchive a card, you can use the action “activate”. All archived cards are uninstalled automatically when archived and if they are activated again, they will not retain the installation status but it will have an inactive status.
`REVOKE`	To revoke a card from the app user’s device, you can use the action “revoke”. When a card is revoked, the card status will be updated to “Uninstalled”. This will remove a card from all user’s devices that have installed it as if they manually uninstalled it.
`ARCHIVE`	If you want to archive a card, you can do that using the “archive” action. When a card is archived, the card status will be updated to “Archived”. If an archived card is activated again it will need to be reinstalled again.

Request Format¶

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

{
   "action": "card-action",
   "card-template-id": "CARD_TEMPLATE_ID",
   "card-id": "CARD_ID",
   "status-action": "activate"  // activate, deactivate, archive or revoke
}

Success Response¶

{
    "status": "success",
    "code": "S2005",
    "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
F113	Cannot perform this action for the requested card
F201	`{CUSTOM-VALUE-1}` is required.
F203	Card template was not found.
F209	Card was not found.
F216	Invalid action. Allowed actions are 'activate', 'deactivate', 'revoke' and 'archive'