Developer API

The ScribblePics developer API enables you to easily integrate real postcards into your applications.

With our JSON API you can use any modern programming language to create, preview and send real postcards.

Register now to get a FREE account and start sending postcards right away.

There's no minimum spend, no setup fees and no cancellation fees.

Create postcard

Description

Create a draft postcard. Note that this does not actually send the postcard, it simply prepares it ready to be sent. Once a postcard has been created a JPG preview of the front and back can be generated, and a separate call can be made to send the card.

A postcard can be created standalone, or be added to an existing cart. If sender details (first name, last name, email) are included in the request then the postcard will be created and added to a new cart. If a cart ID is included in the request then the postcard will be created and added to the existing cart.

The ID of the postcard and its cart is always included in the response.

URL

HTTP method

POST

Example request JSON

{
    "apiKey": "12345678-90ab-cdef-1234-567890abcdef",
    "sender": {
        "firstName": "John",
        "lastName": "Smith",
        "email": "john.smith@email.com"
    },
    "recipient": {
        "name": "Mary Brown",
        "addressLine1": "Level 1",
        "addressLine2": "1 Main Street",
        "city": "Sydney",
        "state": "NSW",
        "zip": "2000",
        "country": "Australia"
    },
    "message": "Dear Mary,\n\n Wish you were here.\n\nLove,\nJohn",
    "imageData": "<base64 encoded JPG image data>"
}

Example request JSON (adding postcard to an existing cart)

{
    "apiKey": "12345678-90ab-cdef-1234-567890abcdef",
    "cartId": "fedcba09-8765-4321-fedc-ba0987654321",
    "recipient": {
        "name": "Mary Brown",
        "addressLine1": "Level 1",
        "addressLine2": "1 Main Street",
        "city": "Sydney",
        "state": "NSW",
        "zip": "2000",
        "country": "Australia"
    },
    "message": "Dear Mary,\n\n Wish you were here.\n\nLove,\nJohn",
    "imageId": "abcdef01-2345-6789-abcd-ef0123456789"
}
Field Description Required?
apiKey API key mandatory
sender.firstName the first name of the sender Either 'sender' or 'cartId' is mandatory
sender.lastName the last name of the sender Either 'sender' or 'cartId' is mandatory
sender.email the email address of the sender Either 'sender' or 'cartId' is mandatory
cartId the ID of a cart to add the postcard to Either 'sender' or 'cartId' is mandatory
recipient.name the name of the recipient mandatory
recipient.addressLine1 the first list of the recipient's address mandatory
recipient.addressLine2 the second line of the recipient’s address optional
recipient.city the recipient’s city mandatory
recipient.state the recipient’s state optional
recipient.zip the recipient’s zip/post code mandatory
recipient.country the recipient’s city mandatory
message the message to include on the back of the postcard mandatory
imageId The ID of an image that has been uploaded One of 'imageId', 'imageUrl' or imageData' is mandatory
imageUrl The URL to a publicly available image on the Internet One of 'imageId', 'imageUrl' or imageData' is mandatory. Note that the server hosting the image is expected to return a 'Content-Type' header of either image/jpg or image/jpeg, and a 'Content-Length' of 1MB or less (1,000,000 bytes).
imageData base64 encoded JPG image data One of 'imageId', 'imageUrl' or imageData' is mandatory

Example success response

HTTP status code: 200

{
    "postcardId": "abcdef12-3456-7890-abcd-ef1234567890",
    "cartId": "fedcba09-8765-4321-fedc-ba0987654321"
}

Example error response

HTTP status code: 400

{
    "errors": [
        "apiKey is required",
        "message is required"
    ]
}

Upload image

Description

Upload an image to use on a postcard. Once an image has been uploaded it can be used on multiple postcards if desired.

The ID of the uploaded image is returned in the JSON response.

URL

HTTP method

POST

Request parameters

Field Description Required?
apiKey API key mandatory
image Multi-part file attachment - JPG images only mandatory

Example success response

HTTP status code: 200

{
    "imageId": "abcdef12-3456-7890-abcd-ef1234567890"
}

Example error response

HTTP status code: 400

{
    "errors": [
        "apiKey is required",
        "image is required"
    ]
}

Postcard front preview

Description

Get a preview of the front (photo side) of a postcard. The default size of the preview image is 1748 x 1240 pixels. The preview image can be scaled down using the “scale” parameter.

URL

HTTP method

GET

Request parameters

Field Description Required?
postcardId the ID of the postcard to preview mandatory
scale the factor to scale the image by (greater than 0 and less than or equal to 1) optional (default = 1)

Example request

https://api.scribblepics.com/postcard/preview/front?postcardId=abcdef12-3456-7890-abcd-ef1234567890&scale=0.5

Example success response

HTTP status code: 200

Example error response

HTTP status code: 400

{
    "errors": [
        "postcardId is required"
    ]
}

Postcard back preview

Description

Get a preview of the back (message side) of a postcard. The default size of the preview image is 1748 x 1240 pixels. The preview image can be scaled down using the “scale” parameter.

URL

HTTP method

GET

Request parameters

Field Description Required?
postcardId the ID of the postcard to preview mandatory
scale the factor to scale the image by (greater than 0 and less than or equal to 1) optional (default = 1)

Example request

https://api.scribblepics.com/postcard/preview/back?postcardId=abcdef12-3456-7890-abcd-ef1234567890&scale=0.5

Example success response

HTTP status code: 200

Example error response

HTTP status code: 400

{
    "errors": [
        "postcardId is required"
    ]
}

Send postcard

Description

Send a previously created postcard. Within 24 hours the postcard will be printed and mailed to the recipient. A confirmation email will be sent to the sender.

Note that a postcard can only be sent individually if it is the only postcard in the cart it belongs to. If the postcard's cart has other postcards then the send method will fail. In this situation, the cart must be sent using the /cart/send method.

URL

HTTP method

POST

Example request JSON

{
    "apiKey": "12345678-90ab-cdef-1234-567890abcdef",
    "postcardId": "abcdef12-3456-7890-abcd-ef1234567890"
}

Request parameters

Field Description Required?
apiKey API key mandatory
postcardId the ID of the postcard to send mandatory

Example sucess response

HTTP status code: 200

{
    "postcardId": "abcdef12-3456-7890-abcd-ef1234567890",
    "cartId": "fedcba09-8765-4321-fedc-ba0987654321"
}

Example error response

HTTP status code: 400

{
    "errors": [
        "postcardId is required"
    ]
}

Create cart

Description

Create a empty cart. Multiple postcards can be added to a cart which allows them all to be sent together.

URL

HTTP method

POST

Example request JSON

{
    "apiKey": "12345678-90ab-cdef-1234-567890abcdef",
    "sender": {
        "firstName": "John",
        "lastName": "Smith",
        "email": "john.smith@email.com"
    }
}
Field Description Required?
apiKey API key mandatory
sender.firstName the first name of the sender mandatory
sender.lastName the last name of the sender mandatory
sender.email the email address of the sender mandatory

Example success response

HTTP status code: 200

{
    "cartId": "abcdef12-3456-7890-abcd-ef1234567890",
    "postcardIds": []
}

Example error response

HTTP status code: 400

{
    "errors": [
        "apiKey is required",
        "sender.email is required"
    ]
}

List cart

Description

List the postcards in a cart.

URL

HTTP method

GET

Example request

https://api.scribblepics.com/cart/list?apiKey=12345678-90ab-cdef-1234-567890abcdef&cartId=fedcba09-8765-4321-fedc-ba0987654321

Field Description Required?
apiKey API key mandatory
cartId the ID of the cart to send mandatory

Example success response

HTTP status code: 200

{
    "cartId": "fedcba09-8765-4321-fedc-ba0987654321",
    "postcardIds": [
        "abcdef12-3456-7890-abcd-ef1234567890",
        "bcdef123-4567-890a-bcde-f1234567890a"
    ]
}

Example error response

HTTP status code: 400

{
    "errors": [
        "apiKey is required",
        "cartId is required"
    ]
}

Send cart

Description

Send all postcards in a cart. Within 24 hours the postcards will be printed and mailed to the recipient. A confirmation email will be sent to the sender for each postcard.

URL

HTTP method

POST

Example request JSON

{
    "apiKey": "12345678-90ab-cdef-1234-567890abcdef",
    "cartId": "fedcba09-8765-4321-fedc-ba0987654321"
}
Field Description Required?
apiKey API key mandatory
cartId the ID of the cart to send mandatory

Example success response

HTTP status code: 200

{
    "cartId": "fedcba09-8765-4321-fedc-ba0987654321",
    "postcardIds": [
        "abcdef12-3456-7890-abcd-ef1234567890",
        "bcdef123-4567-890a-bcde-f1234567890a"
    ]
}

Example error response

HTTP status code: 400

{
    "errors": [
        "apiKey is required",
        "cartId is required"
    ]
}