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.
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.
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.
| Text | Text 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 choice | In 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. |
| Image | ID 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.
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.
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.
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.
Note that apart from authorisation errors, the HTTP level status will be 200 (or 201 if a card was created) regardless of any errors reported, so always check for _errors in the reply
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.
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 can be supplied in one of several ways.
| Web site | Provide 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 URL | Provide 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. | |
| Hash | Any previously loaded image can be provided by supplying the lower case hex SHA1 hash of the image file. |
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.
| _cardid | Card ID |
| _printsdue | Number of prints due |
| _orderno | Order number if pending order |
| _invoice | Invoice number of last order |
| _prints | Number of prints ever produced |
| _printlast | When last print produced |
| _lastid | Card IC/RF ID of last printed card, if known, e.g. ICCID of SIM card |
| _preview | URL of preview of card artwork. |
| _warnings | An 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.
It is possible to place an order for a batch of cards via the API. For this you need to post a JSON object with a JSON object field _order containing.
| cards | An array of card IDs to order (one of each is ordered) |
| reference | An order reference (optional) |
| delivery | UK delivery address as detailed below (optional, otherwise account address used). |
The delivery address contains:-
| name | Name |
| company | Company name (optional) |
| address | Array of one or more strings - not including posttown or postcode |
| posttown | Post town |
| postcode | Post code |
| tel | Telephone number (optional) |
| Email address (optional) |
Cards with an ID, such as SIM cards and RFID cards can be set up with a provisioning URL (once an API key has been set). During card printing a JSON object is posted to this URL, and providing a normal 2XX response the card printing goes ahead. This includes the card fields with _ID which is the card ID.
In the case of DESFire EV cards, if a provisioning URL is set, then the card is formatted to use AES and a random master key is allocated. The provisioning JSON includes _KEYVER and _KEYAES of the random key. The card printing then sets this as the master card AES key. You need to store these details so you can use them to access the card. Even though we do not store this key, it is good practice to change to a new key on first access.