Below is an example of using our JSON API to send a letter.
Our JSON API has exactly the same fields as our SOAP API and uses the same functionality as our SOAP API.
In the example below we are sending a letter to one person with the body included as free text. You may also use HTML to format the body of your letter. The JSON below could quite easily be used straight from JavaScript or from nodejs, but could just as well be used from almost any coding language. The endpoint to post your JSON to is https://www.pc2paper.co.uk/lettercustomerapi.svc/json/SendSubmitLetterForPosting
{
"letterForPosting":
{
"SourceClient" : "My App name 1",
"Addresses" :[
{"ReceiverName": "John Smith",
"ReceiverAddressLine1" : "1 Acme Road",
"ReceiverAddressLine2" : "My Street",
"ReceiverAddressTownCityOrLine3" : "Town",
"ReceiverAddressCountyStateOrLine4" : "County",
"ReceiverAddressPostCode" : "Postcode"}
],
"ReceiverCountryCode" :1,
"Postage":31,
"Paper":1,
"Envelope":1,
"Extras":0,
"LetterBody" : "Dear Peter,
Please find my letter attached",
"IncludeSenderAddressOnEnvelope" : true,
"SenderAddress" : "22 Acme Acres\n Acme Town",
"YourRef" : "MyRef001"
},
"username" : "yourusername",
"password" : "yourpassword"
}
In the above examples you will notice we use a ReceiverCountryCode you can lookup the code to use for the country you are sending to here. In the above example the country code 1 represents the UK.
For the postage options you can lookup the options you would like to use by using our postage calculator. The postage calculator will list the API options at the bottom of the page for you after you make your selection. In the example above we have chosen Postage 31 (UK Second Class), Paper 1 (Black and White 80 gsm), Envelope 1 (Standard DL). If you would like the ability to lookup your own postage options, you can use our letter pricing API which you can find out more about here.
If you'd like to include PDF's as attachment's to your letter, you can upload these and use the unique id's the website gives you to attach them to your letter.
You can upload PDF's one of three ways.
HTTP POST
This is probably one of the easiest ways to upload your file submitting your file over HTTP POST. Simple call https://www.pc2paper.co.uk/uploadfileapi.aspx?fileName=myfileName.pdf
In the headers of your HTTP POST place the following
- username - This will be your PC2Paper username or API key
- password - This will be your PC2Paper password or API secret
You will recieve a response that contains the GUID for your PDF and how many pages it has.
JSON PDF File Upload
https://www.pc2paper.co.uk/lettercustomerapi.svc/json/UploadDocument
With a JSON file upload you will need to convert what ever file you are uploading into an integer array. This can usually be done by converting your file into a byte array and then into an integer array.
{
"filename":"myfile.pdf",
"username":"yourusername",
"password":"yourpassword",
"fileContent":[37,80,68,70,45,49,46,53,13,10,37...]
}
After successfully uploading your PDF file you should receive a response similar to the following.
{
"d": {
"__type": "UploadedFileResult:#PC2Paper.Entity.Public.Letters",
"ErrorMessages": null,
"FileCreatedGUID": "648b6725-a3c6-4396-b28a-33e86589aa4b",
"Status": "OK"
}
}
Store the FileCreatedGUID somewhere as you will need this to attach it to your letter.
SOAP PDF File Upload
If you would prefer to upload your PDF file over SOAP instead of JSON you can use this endpoint.
https://www.pc2paper.co.uk/lettercustomerapi.svc?wsd
You can find a PHP example and C# example of how to use our SOAP API to upload a file.
Using an uploaded PDF file in your letter
After you have uploaded your PDF file using one of the two methods above you will be provided with a FileCreatedGUID for each file you upload. Construct the JSON for your letter as before but include an array of File GUIDs you would like to attach in the FileAttachementGUIDs field.
{
"letterForPosting":
{
"SourceClient" : "My PC2Paper Client",
"Addresses" :[
{"ReceiverName": "John Smith",
"ReceiverAddressLine1" : "1 Acme Road",
"ReceiverAddressLine2" : "My Street",
"ReceiverAddressTownCityOrLine3" : "Town",
"ReceiverAddressCountyStateOrLine4" : "County",
"ReceiverAddressPostCode" : "Postcode"}
],
"ReceiverCountryCode" :1,
"Postage":31,
"Paper":1,
"Envelope":11,
"Extras":0,
"LetterBody" : "Dear Peter,
Please find my letter attached",
"FileAttachementGUIDs":["648b6725-a3c6-4396-b28a-33e86589aa4b"]
},
"username" : "your username",
"password" : "yourpassword"
}
You should receive the following response after submitting a successful letter.
{
"d": {
"__type": "LetterForPostingResult:#PC2Paper.Entity.Public.Letters",
"CostOfLetter": 2.02,
"ErrorMessages": null,
"FundsLeftInYourAccount": 160.54,
"LetterId": "71566",
"Status": "OK"
}
}
Sending a letter to more than one person
If you would like to send the same letter to more than one person. Just add more people to the Addresses array.
"Addresses" :[
{"ReceiverName": "John Smith",
"ReceiverAddressLine1" : "1 Acme Road",
"ReceiverAddressLine2" : "My Street",
"ReceiverAddressTownCityOrLine3" : "Town",
"ReceiverAddressCountyStateOrLine4" : "County",
"ReceiverAddressPostCode" : "Postcode"},
{"ReceiverName": "Bob Smith",
"ReceiverAddressLine1" : "The Gables",
"ReceiverAddressLine2" : "Another Road",
"ReceiverAddressTownCityOrLine3" : "Town",
"ReceiverAddressCountyStateOrLine4" : "County",
"ReceiverAddressPostCode" : "ZZ1 0ZZ"}
]