API guide

Sending a postcard through our API is simple and can be set up in 3 simple steps


Step 1: Create an account

First you will need to create a partner account with us. To do this please visit our contact page and let us know how you plan to use our service.

After you have contacted us we will set you up with an account. You can then log in to see find your API token and API secret codes. You need these to access our API.


Step 2: Code your API call

Our API works over HTTP and returns XML responses. For us to authorise your call you will have to send us your API token and send a signature hash of the call. A call will look similar to the following.

http://www.stannp.com/api/v1/client/apicall.php?token=frt556gge5t&method=get_partner_credits()&nonce=1234567890&hash=weRWer78yrhhuu4vvgfk74fgg77mzw2QS

We can see the query string has four parameters.

token
This is your API token found in your partner admin area
method
This is the method that you will be calling.
nonce
This has to always be a unique value for each call. So we recommend you use the UNIX timestamp in microseconds. This is used to prevent API replay calls.
hash
This is an MD5 hash of the above parameters and your API secret. You have to concatenate each value like so: token + method + nonce + secret. Then you md5 hash the resulting string.

Step 3: Send us postcard data

To create a postcard you will need to send a multipart HTTP POST containing an image and an XML file.

The image file

The current maximum file size for uploads is 8mb although we highly recommend compressing this to below 1mb if possible due to the upload time needed. The optimal resolution we use is 1843 x 1311 pixels which is 300 dpi for a postcard. Anything lower than this will be stretched. Portrait and Landscape images are both compatible as our software will automatically rotate the image for the best fit. All of the postcards are vetted at print time and any obscene, offensive or illegal content will be dealt with according to the laws of the United Kingdom

The XML file

Here is an example of the XML file that needs to be posted

          <?xml version="1.0" encoding="ISO-8859-1"?>
            <card>
              <token>[Your API Token]</token>
              <message>[Card Message]</message>
              <card_order_date>[Send Date in YYYYMMDD Format]</card_order_date>
              <recipient_add1>[Name]</recipient_add1>
              <recipient_add2>[Address Line 1]</recipient_add2>
              <recipient_add3>[Address Line 2]</recipient_add3>
              <recipient_add4>[Address Line 3]</recipient_add4>
              <recipient_add5>[Address Line 4]</recipient_add5>
              <recipient_add6>[Postcode]</recipient_add6>
              <recipient_add7>[Country]</recipient_add7>
              <api_owner_ref>[Your unique identifier]</api_owner_ref>
              <device>[Device Name (iPhone, Android, winPhone, Win8app, Web)]</device>
              <app_version>[Version of your app]</app_version>
            </card>
          
  • <recipient_add7> must be used as country only. The country must be in ISO-2 format. eg: GB
  • <recipient_add1> is usually used for the recipients name
  • Your unique identifier (UID) can be anything that allows you to identify individual cards that your customers have sent. We recommend that you Do Not use the following
    • Your customers name, address or other personal information
    • Your Token or a deriviative of it
    • Your Password or a deriviative of it
    • Your email address or a deriviative of it
    UID we recommend are
    • A sha1(or similar) hash of the time of the postcard being ordered
    • A sha1(or similar) hash of the database row ID
    • App or Website Name followed by the current postcard count (stannp001, stannp002).
    Please do not use any punctuation or special characters in your UID. The maximum size limit for your UID is 20 characters.
  • The format for calling the upload functions is
    http://www.stannp.com/api/v1/client/apicall.php?token={Your API token}&method=upload(7jf1770f872b80735dbe01f0)&nonce={Nonce}hash={The security hash}
              
     <form enctype="multipart/form-data" method="post" action="http://www.stannp.com/api/v1/client/apicall.php?token={Your API token}&method=upload([Users public ID])&nonce={Nonce}hash={The security hash}">
  • Once the upload(public_id) function is called and the image and xml have been Posted. The postcard will be created.
  • The users balanced is checked and if the users balance is insufficient a message will be returned and the card will not be produced.
  • If the users balance is sufficient, the customers account will be deducted either 1 or 2 credits depending on the destination. The card will then be created, printed and, if the card is created before 2:00pm (GMT), sent via Royal Mail.
  • If there are any problems with the JPG or XML file that has been posted, an error message will be returned and the postcard will not be created. The customer will only be charged for a successful postcard creation.