API Reference

The IDC API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Below is the list of available actions and properties. Each Payload must have the minimum data structure. All additional API properties must be added to the API object.

The API object property api_queries_remaining indicates the number of queries remaining in your account. To save space, in the examples below, the response API object will show “API OBJECT” as they all have the same structure.

Our Free and Open-Source Client Library:
https://github.com/idpackcloud/idc-php

BASE URL

https://api.idpack.cloud

PAYLOAD EXAMPLE

{
	"user_secret_key": "YOUR USER SECRET KEY",
	"project_secret_key": "YOUR PROJECT SECRET KEY",
	"api": {
		"api_authorization": "basic",
		"api_action": "THE ACTION",
		"api_primary_key": {
			"YOUR PRIMARY KEY": "YOUR RECORD ID"
		},
		"api_output_format": "json",
		"api_version": "2.2.2"
	}
}

Authentication

The IDC API uses Basic Auth and API keys to authenticate requests. You can view and manage your API keys in the IDC Dashboard.

Your API keys carry many privileges, so keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc. Each user has a different Secret Key, and you cannot share this key with anyone. IDC will never ask for your Secret Key by email, chat, or phone.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

You need a Username, Password, User Secret Key, and Project Secret Key to connect to the IDC API.

API CONNECTION

require_once 'idc.class.php';
$idc = new IDpack(
	'username', 
	'password', 
	'user_secret_key', 
	'project_secret_key'
);

get_record

GET a data structure (JSON or XML) from a Project Record. A Base64 Photo ID and/or Badge Preview can be included in the data structure.

Properties

Properties Value Optional
api_authorization basic
api_action get_record
api_primary_key [“YOUR PRIMARY KEY”, “ID NUMBER”]
api_output_format json or xml
api_photo_id 1

api_photo_id_format webp, jpeg, or png

api_badge_preview 1

api_badge_preview_format webp, jpeg, png, or pdf

api_badge_preview_number Specify the Badge Preview #: 0, 1, or 2, default 0

api_get_key 1

api_version 2.2.2 
"api_Photo_ID": 1,
		"api_photo_id_format": "webp",

Add these two lines to the API object to get the Photo ID in Base64 with the response data structure.

"api_Badge_Preview": 1,
		"api_badge_preview_format": "webp",

Add these two lines to the API object to get the Badge Preview in Base64 with the response data structure.

"api_badge_preview_number": 2

The property api_badge_preview_number allows you to select Duplex (0), Front (1), or Back (2) of the badge. Add this line to the API object to get the Badge Preview – Back.

"api_get_key": 1

The property api_get_key (default: 0). Set to 1 will add the idc_key from the record and idc_project in the response.

PHP public function get_record

$response = $idc->get_record(['idc_id_number' => '10000']);
echo $response;

POST https://api.idpack.cloud/producer

{
	"user_secret_key": "YOUR USER SECRET KEY",
	"project_secret_key": "YOUR PROJECT SECRET KEY",
	"api": {
		"api_authorization": "basic",
		"api_action": "get_record",
		"api_primary_key": {
			"idc_id_number": "10000"
		},
		"api_output_format": "json",
		"api_version": "2.2.2"
	}
}

RESPONSE

{
	"status": "success",
	"message": null,
	"code": 200,
	"data": {
		"record": {
			"idc_id_number": "10000",
			MORE FIELDS …
		}
	},
	"api": {
		API OBJECT
	}
}

get_all_records

GET a data structure (JSON or XML) of all Records from a Project. We do not allow including the Base64 Photo ID and/or Badge Preview in this view. The output would be too large.

The property records_count indicates the number of records returned by the API. You can then loop the objects to get all records.

Properties

Properties Value Optional
api_authorization basic
api_action get_all_records
api_output_format json, xml
api_get_keys 1

api_version 2.2.2 
"api_get_keys": 1

The property api_get_keys (default: 0). Set to 1 will add the idc_key from the record(s) and idc_project in the response.

POST https://api.idpack.cloud/producer
{
	"user_secret_key": "YOUR USER SECRET KEY",
	"project_secret_key": "YOUR PROJECT SECRET KEY",
	"api": {
		"api_authorization": "basic",
		"api_action": "get_all_records",
		"api_output_format": "json",
		"api_version": "2.2.2"
	}
}
RESPONSE
{
	"status": "success",
	"message": null,
	"code": 200,
	"data": {
		"records_count": 223,
		"records": {
			"record_1": {
				"idc_id_number": "10000",
				MORE FIELDS …
			},
			"record_2": {
				"idc_id_number": "10001",
				MORE FIELDS …
			},
			MORE RECORDS …
		}
	},
	"api": {
		API OBJECT
	}
}

get_photo_id

GET a 240×300 pixels (portrait) or 300×300 pixels (square) Photo ID (WebP, PNG, or JPEG) in a Base64 format from a Project Record.

Photo ID Aspect Ratio
Rectangle Photo ID follows the 4:5 Aspect Ratio. You are likely most familiar with seeing printed photographs with a 4:5 ratio. This ratio includes standard print sizes of 4×5″, 8×10″, 16×20″, and 11×14″.

Square or Rounded Photo ID follows the 1:1 Aspect Ratio. A 1:1 ratio means that an image’s width and height are equal, creating a square. This ratio is standard for print photographs, websites, mobile screens, and social media platforms.

What is Base64?
Common to all binary-to-text encoding schemes, Base64 is designed to carry data stored in binary formats across channels that only reliably support text content. As a result, Base64 is particularly prevalent on the World Wide Web, where one of its uses is the ability to embed image files or other binary assets inside textual assets such as PDF files.

< img src="data:image/webp;base64,UklGRqAAHIAAA…" width="240" height="300" >

HTML Base64 example

The property photo_id_count indicates the number of Photo IDs returned by the API. You can then loop the objects to get all the Photo IDs.

The api_output_format Base64 will output the Photo ID without any data structure. This way, you can insert a Photo ID directly into a user interface (UI) without manipulating a JSON or XML. If no Photo ID is present, it will output false.

data:image/webp;Base64,UklGRqwWAABXRUJQVlA4WAoAAAAgAAAA7wAAKwEA…

Response (Base64)

Properties

Properties Value Optional
api_authorization basic  
api_action get_photo_id  
api_primary_key [“YOUR PRIMARY KEY”, “ID NUMBER”]  
api_output_format json, xml, or base64  
api_photo_id_format webp, jpeg, or png  
api_version 2.2.2  
POST https://api.idpack.cloud/producer
{
	"user_secret_key": "YOUR USER SECRET KEY",
	"project_secret_key": "YOUR PROJECT SECRET KEY",
	"api": {
		"api_authorization": "basic",
		"api_action": "get_photo_id",
		"api_primary_key": {
			"idc_id_number": "10000"
		},
		"api_output_format": "json",
		"api_photo_id_format": "webp",
		"api_version": "2.2.2"
	}
}
RESPONSE
{
	"status": "success",
	"message": null,
	"code": 200,
	"data": {
		"photo_id_count": 1,
		"photo_id_1": {
			"imagedata": "data:image\/webp;Base64,UklGRqAAHIAAA...",
			"width": 240,
			"height": 300,
			"imageformat": "webp",
			"status": "success",
			"message": null,
			"code": 200
		}
	},
	"api": {
		API OBJECT
	}
}

get_badge_preview

GET a 1013×639 pixels (Landscape) or 639×1013 pixels (Portrait) Badge Preview (WebP, PNG, JPEG, or PDF) in a Base64 format from a Project Record.

CR80 Dimension
The CR80 format is the standard card size and is the most used worldwide. The dimensions are 3.375″ x 2.125″ (85.6 mm x 54 mm) with a corner radius of .09″ (2.29 mm).

WebP, PNG, JPEG Output Format
IDC API will send a Base64 image with the exact dimension of CR80 cards at 300 dpi for the maximum quality impression. For badge printing, we recommend using the PNG format. It has no compression (like a jpeg) and will get a better print result. For Screen preview, the best format is WebP, which has the best compression/image quality.

What is WebP?
WebP is an image file format that Google has developed as a replacement for JPEG, PNG, and GIF file formats. Google announced the WebP format in September 2010 and released the first version of its supporting library in April 2018. As of November 2021, 96% of web browsers support WebP.

PDF Output Format
The PDF Output Format is the true power of IDpack Cloud. With the PDF in a Base64, you will get your Badge Preview in vectorial (like Adobe Illustrator or SVG) for the best printing quality. Bitmap images are made up of fixed pixels, whereas vector images are made up of a group of shapes. Increasing the size of a vector image keeps the shape intact. So, by printing to a 300, 600, or 1200 dpi printer, you will always get the best results.

< embed src="data:application/pdf;base64,JVBERi0xLjcK…" type="application/pdf" >

HTML PDF Base64 example

The property badge_preview_count indicates the number of Badge Previews returned by the API. You can then loop the objects to get all the Badge Previews.

The api_output_format Base64 will output the Badge Preview without any data structure. You can insert a Badge Preview directly into a user interface (UI) without manipulating a JSON or XML. If there is no Badge Preview present, it will output false.

The api_output_format Base64 can only send one image; by default, IDC API will send the first one (1).

The property api_badge_preview_number allows you to select Duplex (0), Front (1) or Back (2) of the badge.

"api_badge_preview_number": 2

To get the api_output_format – Badge Preview – Back, add this line to the API object

data:application/pdf;base64,JVBERi0xLjcIC9MYXN0TW…

Response (Base64)

Properties

Properties Value Optional
api_authorization basic
api_action get_badge_preview
api_primary_key [“YOUR PRIMARY KEY”, “ID NUMBER”]
api_output_format json, xml, or base64
api_badge_preview_format webp, jpeg, png, or pdf
api_badge_preview_number Specify the Badge Preview #: 0, 1, or 2, default 0, and 1 for base64

api_version 2.2.2
POST https://api.idpack.cloud/producer
{
	"user_secret_key": "YOUR USER SECRET KEY",
	"project_secret_key": "YOUR PROJECT SECRET KEY",
	"api": {
		"api_authorization": "basic",
		"api_action": "get_badge_preview",
		"api_primary_key": {
			"idc_id_number": "10000"
		},
		"api_output_format": "json",
		"api_badge_preview_format": "webp",
		"api_version": "2.2.2"
	}

}
RESPONSE
{
	"status": "success",
	"message": null,
	"code": 200,
	"data": {
	"badge_preview_count": 1,
		"badge_preview_1": {
			"imagedata": "data:application\/pdf;base64,JVBERi0xLjcK...",
		"width": 1013,
			"height": 639,
			"imageformat": "webp",
			"status": "success",
			"message": null,
			"code": 200
		}
	},
	"api": {
		API OBJECT
	}
}

post_record (Insert)

Insert a data structure into a Project Record (projects are unlimited). A Base64 Photo ID and the status: ACTIVE and TRASH can also be included in the data structure.

Data Object
The data object list all the fields you need to update in the IDpack Cloud database. You can find the list of our fields here: https://www.idpack.cloud/supported-database-fields/.

IDC fully manages the database, and you must choose the fields for data collection. These fields will be reflected in Designer and Producer, as each project has its Field Definition. Don’t see the field you need? Request a field here.

How to send a Photo ID to IDC?
Using the post_record (Insert) or put_record (Update), add the property photo_id_1 to the data object. The property’s value must be a Base64 Photo ID in jpeg, png, or webp format. Anything else will be skipped.

"photo_id_1": "data:image\/webp;base64,UklGRqwWAABXRUJQVlA4WAoAAAAgAAA..."

Example

“data” properties

Properties Value Optional
idc_active 1 (active by default) or 0 (inactive)

idc_trash 1 (trashed) or 0 (not trashed by default)

idc_colorcode null or 1 to 15

photo_id_1 Base64 image must be in jpeg, png, or webp format.

Properties

Properties Value Optional
api_authorization basic
api_action PUSH_record
api_output_format json, xml
api_version 2.2.2
POST https://api.idpack.cloud/producer
{
	"user_secret_key": "YOUR USER SECRET KEY",
	"project_secret_key": "YOUR PROJECT SECRET KEY",
	"data": {
		"idc_firstname": "David",
		"idc_lastname": "Wilsons",
		"idc_email": "david@example.com"
	},
	"api": {
		"api_authorization": "basic",
		"api_action": "post_record",
		"api_output_format": "json",
		"api_version": "2.2.2"
	}

}
RESPONSE
{
	"status": "success",
	"message": null,
	"code": 200,
	"data": {
		"idc_id_number": "10023"
	},
	"api": {
		"api_action": "post_record",
		"api_queries_remaining": 8706,
		"api_software": "IDpack Cloud",
		"api_version": "2.2.2",
		"api_request_date": "2023-02-08 17:29:53"
	}
}

put_record (Update)

Update the data structure from a Project Record (projects are unlimited). The data structure can also include a Base64 Photo ID and the ACTIVE, TRASH, or DELETE status.

What is the difference between PUT and POST?
The HTTP PUT method is generally used to update an existing resource, while the POST method creates a new resource.

Data Object
The data object list all the fields you need to update in the IDpack Cloud database. You can find the list of our fields here: https://www.idpack.cloud/supported-database-fields/.

IDC fully manages the database, and you must choose the fields for data collection. These fields will be reflected in Designer and Producer, as each project has its Field Definition. Don’t see the field you need? Request a field here.

How to send a Photo ID to IDC?
Using the post_record (Insert) or put_record (Update), add the property photo_id_1 to the data object. The property’s value must be a Base64 Photo ID in jpeg, png, or webp format. Anything else will be skipped.

"photo_id_1": "data:image\/webp;base64,UklGRqwWAABXRUJQVlA4WAoAAAAgAAA..."

Example

“data” properties

Properties Value Optional
idc_active 1 (active by default) or 0 (inactive)

idc_trash 1 (trashed) or 0 (not trashed by default)

idc_delete 1 (deleted)

idc_colorcode null or 1 to 15

photo_id_1 Base64 image must be in jpeg, png, or webp format.

The record will be deleted when idc_delete is set to 1. There is no way back, and this record and Photo ID will be deleted permanently.

Properties

Properties Value Optional
api_authorization basic
api_action put_record
api_output_format json, xml
api_version 2.2.2
POST https://api.idpack.cloud/producer
{
	"user_secret_key": "YOUR USER SECRET KEY",
	"project_secret_key": "YOUR PROJECT SECRET KEY",
	"data": {
		"idc_firstname": "David",
		"idc_lastname": "Wilsons",
		"idc_email": "david@example.com"
	},
	"api": {
		"api_authorization": "basic",
		"api_action": "put_record",
		"api_primary_key": {
			"idc_id_number": "10000"
		},
		"api_output_format": "json",
		"api_version": "2.2.2"
	}
}
RESPONSE
{
	"status": "success",
	"message": null,
	"code": 200,
	"data": {
		"idc_id_number": "10000"
	},
	"api": {
		"api_action": "put_record",
		"api_queries_remaining": 8706,
		"api_software": "IDpack Cloud",
		"api_version": "2.2.2",
		"api_request_date": "2023-02-08 17:29:53"
	}
}