ID123 JSON API V2 Introduction

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
X-API-KEY: API_KEY

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. 

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. 

Revision History and Notes

 Jan 1, 2021 – v2 released. 

Definitions

Term	Definition
Card	Any 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 Data	Any mention of “Card Data” refers to the data displayed on the digital ID card.
Card Template	Any 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 ID	Any 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 IDMS	Any 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.
API	Any 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.
Institution	Any mention of “Institution” refers to any school, university, business or membership organization using the ID Management System.
Admin	Any mention of “Admin” refers to the person(s) administering the institution’s account in the ID Management System.
App User	Any mention of “App User” refers to the end user of the ID123 mobile app.
Card Builder	Any 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 Identifier	Any 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 1	Any 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 2	Any mention of “Security question 2” refers to the second security question used to verify app user identity before creating a card (optional).
Barcode Value	Any 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 Expiration	Any 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 Field	Any 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 Field	Any 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 Field	Any 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

Region	Domain	API Endpoint
United States	secure-us.id123.io	https://secure-us.id123.io/api/v2/
Australia/Oceania	secure-au.id123.io	https://secure-au.id123.io/api/v2/
Canada	secure-ca.id123.io	https://secure-ca.id123.io/api/v2/
Latin America	secure-la.id123.io	https://secure-la.id123.io/api/v2/
Africa	secure-af.id123.io	https://secure-af.id123.io/api/v2/
Europe	secure-eu.id123.io	https://secure-eu.id123.io/api/v2/
United Kingdom	secure-uk.id123.io	https://secure-uk.id123.io/api/v2/
Asia	secure-as.id123.io	https://secure-as.id123.io/api/v2/
Middle East	secure-me.id123.io	https://secure-me.id123.io/api/v2/
India	secure-in.id123.io	https://secure-in.id123.io/api/v2/

 Status Codes

Status Code	Status Message
Common API Errors
F100	Invalid request. Send a valid raw JSON via Post
F101	Authentication Failed
F102	This account has no API rights
F103	You have exceeded the throughput on your plan
F104	This account has no rights to use this action
F105	JSON Parse error
F106	API is not activated
F107	IP was not whitelisted. API call was rejected
F108	Set throughput exceeded for this API action. API call was rejected
F109	Missing or invalid ACTION key-value pair
F111	API key not provided
F112	Invalid API key
F113	Cannot perform this action for the requested card
Public API Errors
F201	FIELD_NAME is required
F202	Card ID already exists
F203	Card template was not found
F204	Invalid value for FIELD_NAME field
F205	FIELD_NAME value exceeds limit
F209	Card was not found
F210	ID photo URL length should not exceed character limit
F214	Unique Identifier already exists
F215	Invalid FIELD_NAME format. Please provide date in yyyy-mm-dd or mm/dd/yyyy format
F216	Invalid action. Allowed actions are ‘activate’, ‘deactivate’, ‘revoke’, and ‘archive’
F217	Missing or invalid barcode value
F221	Something went wrong during card generation
F222	Unable to complete the deletion process
F231	Notification Message length cannot exceed 100 characters
F232	Notification Full message length cannot exceed 1000 characters
F241	Failed to send card user invitation(s)
F242	Recipient email is not associated with the card
Public API Success
S2001	Card was generated successfully
S2002	Card was updated successfully
S2003	Card was deleted successfully
S2004	Card was retrieved successfully
S2005	Card status was updated successfully
S2006	Notification(s) sent successfully
S2007	Card templates were retrieved successfully.
S2008	Card user invitation(s) sent successfully.
S2009	Card template was retrieved successfully.
S2010	Template cards were retrieved successfully.

Card Statuses

Card Status Code	Description
INACTIVE	A 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.
INSTALLED	A 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.
ARCHIVED	A 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.
UNINSTALLED	A 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 Code	Description
INACTIVE	A card is inactive. This would be the default sub-status for inactive cards.
ACTIVE	A card has been installed and activated on the device
DEACTIVATED	A 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.
EXPIRED	A card has expired.

Issuance Types

Issuance Type Code	Description
SELF_ISSUED	App 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_ISSUED	Institution administrators control the issuance of ID cards. Users are asked to verify their identity before generating their ID card in the app.

Status Actions

Actions	Description
activate	Activate action will activate the deactivated card and restore the archived card.
deactivate	Deactivate the card.
revoke	Revoke an installed card from the app user’s device.
archive	Archive the card.

.

.

.