Renew Card API V2

POST https://secure-{REGION}.id123.io/api/v2/ action: renew-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 renew a card that already exists in the institution’s account by either updating the card’s expiration date in its current template or migrating the card to a new template, with an optional update to its expiration date.

Headers

Header	Value	Required	Description
X-API-KEY	string	Yes	Your authentication API key (passed via header, not in request body)

Request Format

Content-Type: application/json

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

{
  "action": "renew-card",
  "card-id": "CARD_ID",
  "current-template-id": "CARD_TEMPLATE_ID",
  "data": {
    "new-template-id": "CARD_TEMPLATE_ID(new)",
    "expiration-timestamp": "2028-07-16T23:50:30.045+05:30",
    "overwrite-if-exists": true
  }
}

Success Response

{
  "status": "success",
  "code": "S2011",
  "message": "Card was renewed successfully.",
  "card-id": "CARD_ID",
  "current-template-id": "TEMPLATE_ID",
  "new-template-id": "TEMPLATE_ID(new)"
}

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.
F209	Card was not found.
F246	The selected target template has a different issuance type than the source template. Please ensure both templates share the same issuance type before proceeding.
F248	A card with the same Unique Identifier or Card ID already exists in the target template. Please verify that there are no duplicates in the new template.
F249	The specified target template does not exist for this account. Please double-check the template ID and try again.
F250	Missing or invalid renewal details. Please ensure that either a new template ID or an expiration timestamp is provided in the request.
F253	Renewal cannot proceed because the Unique Identifier in the new template is already linked to another card.

Behavior Matrix

Use Case	New-template-id	Expiration-timestamp	Outcome
Update expiration date only	Not provided	Provided	Card remains in the current template; only the expiration date is updated.
Move to new template only	Provided	Not provided	Card is migrated to a new template. Expiration date remains unchanged unless previously set.
Move + update expiration	Provided	Provided	Card is moved to the new template, and the expiration date is updated.
Invalid request	Not provided	Not provided	Returns validation error: No actionable operation provided.

Additional Notes

• ISO 8601 format must be used for expiration timestamps to ensure timezone compatibility and date parsing accuracy.
• Either new-template-id or expiration-timestamp must be provided for the API to perform any action.
• When moving a card, all relevant data associated with it (UID, metadata, statuses, etc.) will be carried over to the new template, unless the same card ID or Unique Identifier already exists under the remote template.