_linkedin_partner_id = "503794"; window._linkedin_data_partner_ids = window._linkedin_data_partner_ids || []; window._linkedin_data_partner_ids.push(_linkedin_partner_id);

Knowledge Base

ID123 JSON API V2 Introduction


ID123 is a digital ID card application and management system for schools, businesses, membership organizations, and other institutions. Card data can be uploaded via CSV or using an API. Card data can also be added to ID123 from a third party system through a Sync integration or LDAP connection. This document explains how to use an API to upload and manage card data. 

Institutions can add, edit, and delete data from the ID Management System (IDMS) programmatically by integrating ID123 APIs. They can also send notifications to App users. The current published APIs will enable institutions to:

  1. Create Card (Crates a card with an “inactive” card status)
  2. Update Card (Update card information)
  3. View Card (Retrieve card information and status)
  4. Card Action (Update a card status based on action specified)
  5. Delete Card (Delete a card data record from your account)
  6. Send Push Notifications (Send push notifications to app users)
  7. Invite Card User  (Send an invitation to user provided email based on card id and template Id)
  8. List Templates ( List limited template information based on API Key)
  9. View Template ( List detailed template information for the provided template ID)
  10. List Cards ( List limited card information based on API Key and Template Id)

API Authentication:

Authentication is the process of verifying the identity of a requester to ensure that they are who claim to be. Once the identity is confirmed, the system grants access to the requester for the resources for which a request has been made.

ID123 APIs use private key authentication to authenticate all requests. You can generate your private API Key in your account if you are on a paid plan that supports it.

X-API-KEY Header:
To authenticate API calls with the API key, set an HTTP header variable X-API-KEY with API_KEY as value.

POST /api/v2/ HTTP/1.1
Host: secure-{REGION}.id123.io

Where to find an API Key: https://app.id123.io/platform/account/api-settings.php


Where to find a Card ID: https://app.id123.io/platform/wallet/card-view-data.php or you can get a list of Card IDs using the List Cards. 

Card Details

Where to find a Card Template ID: https://app.id123.io/platform/wallet/card-templates.php. You can also get a list of Card Template IDs using the List Templates API. 

Template Details

Revision History and Notes

 Jan 1, 2021 – v2 released. 


CardAny mention of “Card” refers to a digital ID card created for an ID123 app. Each Card issued to a person requires at least a “Name” value and a “Card ID” value. Optional values include barcode, expiration date, signature, and any cardholder data. 
Card DataAny mention of “Card Data” refers to the data displayed on the digital ID card.
Card TemplateAny mention of “Card Template” refers to a template that is created for a certain card type and contains generic card data applicable to all cards.
Card IDAny mention of “Card ID” refers to a unique ID used to identify each card in the system. This is not displayed on the card.
ID Management System or IDMSAny mention of “ID Management System” or “IDMS” refers to the cloud-based platform offered by ID123 and used by institutions to create, issue, and manage mobile ID cards remotely.
APIAny mention of “API” refers to the web service interface used to send data from your server to ID123 servers in order to automate an action, add data or change data in a card or card template. 
InstitutionAny mention of “Institution” refers to any school, university, business or membership organization using the ID Management System.
AdminAny mention of “Admin” refers to the person(s) administering the institution’s account in the ID Management System.
App UserAny mention of “App User” refers to the end user of the ID123 mobile app.
Card BuilderAny mention of “Card Builder” refers to the online tool in the ID Management System used by Admins to design and customize digital ID cards.
Unique IdentifierAny mention of “Unique Identifier” refers to a unique identifier of the cardholder (required) used to verify and authenticate user identity before creating a card. Values can be either email address or ID number. This won’t be displayed on the card.
Security Question 1Any mention of “Security question 1” refers to a security question used to verify app user identity before creating a card (required). Institutions can use any data they would like as security questions (e.g. date of birth, phone number). This won’t be displayed on the card.
Security Question 2Any mention of “Security question 2” refers to the second security question used to verify app user identity before creating a card (optional).
Barcode ValueAny mention of “Barcode Value” refers to the value displayed inside and below the barcode.
Card Template ID
Any mention of “Card Template ID” refers to a unique identifier for each card template (required).
Card ExpirationAny mention of “Card Expiration” refers to the date and time when the card should expire. It should be in ‘yyyy-mm-ddThh:mm:ss+00:00 (UTC)’ format to support a timestamp based on a timezone.
Card Invitation Email Any mention of “Card Invitation Email” refers to an email sent to cardholders as part of the card issuance process. Each email contains a link to install a unique digital ID card. 
Front FieldAny mention of “Front Field” refers to a card field located on the first page of the digital ID card. Each front field (except for “Name”) has a field label and a field value. Name value is required to create a card.
Secondary FieldAny mention of “Secondary Field” refers to a card field located on the second page of the digital ID card. Each secondary field has a field label and a field value. Secondary fields are optional.
Back FieldAny mention of “Back Field” refers to a card field located on the third page or back of the digital ID card. Each back field has a field label and a field value. Back fields are optional.

API Endpoints & Request/Response Formats

RegionDomainAPI Endpoint
United Statessecure-us.id123.iohttps://secure-us.id123.io/api/v2/
Latin Americasecure-la.id123.iohttps://secure-la.id123.io/api/v2/
United Kingdomsecure-uk.id123.iohttps://secure-uk.id123.io/api/v2/
Middle Eastsecure-me.id123.iohttps://secure-me.id123.io/api/v2/

 Status Codes

Status CodeStatus Message
Common API Errors
F100Invalid request. Send a valid raw JSON via Post
F101Authentication Failed
F102This account has no API rights
F103You have exceeded the throughput on your plan
F104This account has no rights to use this action
F105JSON Parse error
F106API is not activated
F107IP was not whitelisted. API call was rejected
F108Set throughput exceeded for this API action. API call was rejected
F109Missing or invalid ACTION key-value pair
F111API key not provided
F112Invalid API key
F113Cannot perform this action for the requested card
Public API Errors
F201FIELD_NAME is required
F202Card ID already exists
F203Card template was not found
F204Invalid value for FIELD_NAME field
F205FIELD_NAME value exceeds limit
F209Card was not found
F210ID photo URL length should not exceed character limit
F214Unique Identifier already exists
F215Invalid FIELD_NAME format. Please provide date in yyyy-mm-dd or mm/dd/yyyy format
F216Invalid action. Allowed actions are ‘activate’, ‘deactivate’, ‘revoke’, and ‘archive’
F217Missing or invalid barcode value
F221Something went wrong during card generation
F222Unable to complete the deletion process
F231Notification Message length cannot exceed 100 characters
F232Notification Full message length cannot exceed 1000 characters
F241Failed to send card user invitation(s)
F242Recipient email is not associated with the card
Public API Success
S2001Card was generated successfully
S2002Card was updated successfully
S2003Card was deleted successfully
S2004Card was retrieved successfully
S2005Card status was updated successfully
S2006Notification(s) sent successfully
S2007Card templates were retrieved successfully.
S2008Card user invitation(s) sent successfully.
S2009Card template was retrieved successfully.
S2010Template cards were retrieved successfully.

Card Statuses

Card Status CodeDescription
INACTIVEA card has not been installed on the app user’s device yet. Once the card is added by the app user, the status will change to “Installed”. If you have already sent a card invitation email but the card remains “inactive”, try sending it again as a reminder.
INSTALLEDA card has been installed on the app user’s device. We have removed DEACTIVATED from status as installed can also be deactivated. Installed cards can be active or inactive.
ARCHIVEDA card has been archived and can no longer be used by the system. If the card was installed at the time of archiving, the card would be automatically revoked from the app user’s device. Cards can be restored from the archive at any time and will become “Inactive”. Only archived cards can be deleted. Once the card is deleted, data cannot be recovered.
UNINSTALLEDA card has been uninstalled from the app user’s device. App users can reinstall their card at any time unless the administrator deactivated or archived it.

Card Sub Statuses

Card Sub Status CodeDescription
INACTIVEA card is inactive. This would be the default sub-status for inactive cards.
ACTIVEA card has been installed and activated on the device
DEACTIVATEDA card has been temporarily deactivated by the account administrator and is no longer displayed on the app user’s device. The card can be activated again only by the administrator.
EXPIREDA card has expired. 

Issuance Types

Issuance Type CodeDescription
SELF_ISSUEDApp users provision data in the app to self-issue ID cards for themselves. Self-Issued cards are fully controlled by users but can also be edited, deactivated, or revoked by institution administrators.
INSTITUTION_ISSUEDInstitution administrators control the issuance of ID cards. Users are asked to verify their identity before generating their ID card in the app.

Status Actions

activateActivate action will activate the deactivated card and restore the archived card.
deactivateDeactivate the card.
revokeRevoke an installed card from the app user’s device.
archiveArchive the card.




Go to Top