Card printing API

Our card printing service includes an application interface (API) allowing card data to be loaded in bulk from your own systems.

Simple examples, using curl:-

Note, using --form avoids issues with url escaping base64 data in curl's --data command.

Summary

The API works over https: using JSON objects. You can use common tools like curl to access the API.

A Deck of cards has a (numeric) DeckID which is used in the API. Each Card in the deck then has a CardID as well as a number of Fields.

Card Fields

Each field has a field name and a value. A named field can then be used in multiple places are part of the card design, for example the value could be printed on the card and also encoded in a bar code or a magnetic stripe, etc.

TextText fields are the simplest type - they have a textual value. There is no separate type for numeric fields, they are just a series of digits in a text field. The system places no limits on the format or length of text fields, and so you will need to consider how they are used in the design and ensure values provided are suitable. For example, a long name may not fit in the card design, or a date may be expected in a certain format. You should also consider that a field may be used in more than one place in the card design. Text fields are coded using UTF-8, and text printing supports a wide range of accented characters and emojis.
Multiple choiceIn some cases the design makes a field a multiple choice. In this case you must supply the value of a tag from a pre-set list of options. These tags are them mapped on to values or images on the card design itself and can be used in multiple places.
ImageID cards often include a photo of the card holder. Images can be provided to a named field and are scaled to cover the appropriate part of the design. You need to consider the design aspect ratio to ensure the image is displayed, and consider that the image may have rounded corners, etc. Image formats png, and jpg, are recommended. PNG alpha channel (semi-transparent) images are supported, but consider if the design allows for this (i.e. what is behind the image). Also consider that the image may be used in more than one place, including invisible (UV fluorescent) layer.

Note that field names are case sensitive and never start with an underscore character.

Encoding

Some fields can also be included which are non-printing. These are typically used for encoding on mag stripe or RFID cards. The format of such fields can be quite specific in the design, and the system does not validate the format of values you submit. Note, for example, some MIFARE block fields expect data in hexadecimal.

Authorisation

To use the API you need an API key. Edit the title/info in the card design and the API key is shown. You can issue a new API key at any time (cancelling the old one).

All access to the API requires Basic authorisation with the username being DeckID and the API Key as the password.

Using curl you can add a header with -u $DECKID:$APIKEY.

Errors

The API returns a JSON object. If there are any errors in your request this object includes an _errors array, each object of which includes description explaining the error as well as additional information.

Always check replies for _errors.

Fields info

You can request a list of field information using a GET to https://cards.aa.net.uk/api.cgi. This provides a response including a _fields array. Each object in the array includes field holding the field name. If the field is multiple choice an array of tags is included as a choices array.

The _fields array may also be included if there is an error with data provided for a field.

Add/change card

To create a new card, post the card data to https://cards.aa.net.uk/api.cgi. To edit an existing card, include the existing CardID as _cardid in the data posted. When changing a card, any omitted fields are left unchanged.

The card data is simply a list of fields, using the field names in the card design. You can submit this in multiple ways.

If using common tools like curl you can add each field using --form fieldname=value.

The value for each field is the text, or tag for multiple choice. However image fields are handled specially as follows.

Images

Images can be supplied in one of several ways.

Web siteProvide a value that is the URL for the image, starting https:// or http://. The image is fetched, and an error reported if there is a problem.
Data URLProvide a value that is direct data URL, starting data:image/, encoding the image in base64 in the URL. This avoids having to have the image available on a public web site.
HashAny previously loaded image can be provided by supplying the lower case hex SHA1 hash of the image file.

Retrieve card

Retrieve a card by sending _cardid with the CardID required and no other fields. This is the same as a null update and returns the details of the card.

The result is a JSON object with the card fields. Image fields are reported as the lower case hexadecimal SHA1 hash of the image file.

Additional fields may be included, these all start with an underscore which is never valid as a field name in normal card data.

_cardidCard ID
_printsdueNumber of prints due
_printsNumber of prints ever produced
_printlastWhen last print produced
_lastidCard IC/RF ID of last printed card, if known, e.g. ICCID of SIM card
_previewURL of preview of card artwork.
_warningsAn array of warnings about your card (e.g. invalid MIFARE data)td>

Further additional fields may be added in future, all starting with an underscore.