Idempotent Requests


Our API supports an optional idempotency key for safely retrying requests without performing a repeat operation. If a request is idempotent we will return the original response body with a 409 http status. We match the body of the request so only identical requests will be treated as idempotent.

To perform an idempotent request the optional header X-Idempotency-Key: {key} must be set. They key may be anything you like however we recommend a UUID with a high level of entropy to avoid collisions. Idempotency keys must be between 10 and 1024 characters in length.

Only POST requests may be idempotent. Setting an idempotency key for GET will have no effect.

We store idempotency keys for 24 hours. A request made ofter this time will be treated as a new request and the operation will be performed normally.

Request
$ curl https://dash.stannp.com/api/v1/letters/create \
-u {API_KEY}: \
-H "X-Idempotency-Key: e367c03e-3082-4c8e-b647-d6810761dcd4" \ 
-d "test=1" \ 
-d "background=https://www.stannp.com/assets/samples/letter-heading.jpg" \ 
-d "pages=Hello {firstname}, 

This is my first letter." \ -d "recipient[title]=Mr" \ -d "recipient[firstname]=John" \ -d "recipient[lastname]=Smith" \ -d "recipient[address1]=123 Sample Street" \ -d "recipient[address2]=Sampleland" \ -d "recipient[town]=Sampletown" \ -d "recipient[postcode]=AB12 3CD" \ -d "recipient[country]=GB"
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://dash.stannp.com/api/v1/letters/create?api_key={API_KEY}',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => array(
        'test' => "1",
        'background' => "https://www.stannp.com/assets/samples/letter-heading.jpg",
        'pages' => "Hello {firstname}, 

This is my first letter.", 'recipient[title]' => "Mr", 'recipient[firstname]' => "John", 'recipient[lastname]' => "Smith", 'recipient[address1]' => "123 Sample Street", 'recipient[address2]' => "Sampleland", 'recipient[town]' => "Sampletown", 'recipient[postcode]' => "AB12 3CD", 'recipient[country]' => "GB" ), CURLOPT_HTTPHEADER => array( "X-Idempotency-Key: e367c03e-3082-4c8e-b647-d6810761dcd4" ) )); $response = curl_exec($curl); curl_close($curl); print_r($response);
import requests
headers = {
    'X-Idempotency-Key': 'e367c03e-3082-4c8e-b647-d6810761dcd4'
}
data = {
    'test': '1',
    'background': 'https://www.stannp.com/assets/samples/letter-heading.jpg',
    'pages': 'Hello {firstname}, 

This is my first letter.', 'recipient[title]': 'Mr', 'recipient[firstname]': 'John', 'recipient[lastname]': 'Smith', 'recipient[address1]': '123 Sample Street', 'recipient[address2]': 'Sampleland', 'recipient[town]': 'Sampletown', 'recipient[postcode]': 'AB12 3CD', 'recipient[country]': 'GB' } response = requests.post('https://dash.stannp.com/api/v1/letters/create?api_key={API_KEY}', data=data, headers=headers) print(response.text)
var client = new RestClient("https://dash.stannp.com/api/v1/letters/create?api_key={API_KEY}");

var request = new RestRequest(Method.POST);

request.AddParameter("test", "1");
request.AddParameter("background", "https://www.stannp.com/assets/samples/letter-heading.jpg");
request.AddParameter("pages", "Hello {firstname}, 

This is my first letter."); request.AddParameter("recipient[title]", "Mr"); request.AddParameter("recipient[firstname]", "John"); request.AddParameter("recipient[lastname]", "Smith"); request.AddParameter("recipient[address1]", "123 Sample Street"); request.AddParameter("recipient[address2]", "Sampleland"); request.AddParameter("recipient[town]", "Sampletown"); request.AddParameter("recipient[postcode]", "AB12 3CD"); request.AddParameter("recipient[country]", "GB"); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content)
Response
{
   "success":true,
   "data":{
      "pdf":"https://www.stannp.com/assets/samples/letter-sample.pdf",
      "id":"0",
      "created":"2020-12-17T15:42:22+00:00",
      "format":"letter",
      "cost":"0.78",
      "status":"test"
   }
}