Table of Contents
Renew Card API V2 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
Copy to Clipboard
Success Response
Copy to Clipboard
Failure Response
| Code | Message |
|---|---|
| F246 | The selected target template has a different issuance type than the source template. |
| F248 | A card with the same Unique Identifier or Card ID already exists in the target template. |
| F249 | The specified target template does not exist for this account. |
| F250 | Missing or invalid renewal details. Ensure either new-template-id or expiration-timestamp is provided. |
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.