Cardly API (0.1.0)

Download OpenAPI specification:Download

Cardly Text-to-Correspondence (T2C) API for sending out physical stationery with simulated handwriting and doodles. Currently posting 5×7 inch greeting cards to the US, UK and Australia.

Authentication

token

When your organization account is provisioned you will be provided an API Key and API Secret. The OAuth2 Client Credentials flow involves trading these for a token. Include the token in request headers to API endpoints as Authorization: Bearer [token] to authorize requests. When the token expires, call the tokenUrl again to get a new one. OAuth2 client libraries with support for the Client Credentials flow will handle some of this process automatically.

Security scheme type: OAuth2
clientCredentials OAuth Flow
Token URL: /oauth/token
Scopes:
  • org:send -

    Send out correspondence on behalf of an organization.

Testing

The following endpoints can help while developing an integration.

Echo

Test endpoint. Indicates if request was successfully authenticated, and echoes headers and JSON args to assist troubleshooting.

Authorizations:
Request Body schema: application/json

Responses

200

Echo response.

default

General error response.

post /echo
https://api.card.ly/v0/echo

Request samples

application/json
Copy
Expand all Collapse all
{
  • "foo": "bar"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "authenticated": false,
  • "args":
    {
    },
  • "headers":
    {
    },
}

T2C

The following endpoints relate to Text-to-Correspondence (sending out physical stationery).

T2C Preview

Preview the result of a T2C order. Use to confirm output before placing a T2C Order using the same request content.

There is a small price associated with this endpoint (the product related prices are not charged).

Authorizations:
token (org:send)
Request Body schema: application/json
product
required
string (ProductId)
Enum:"Card5x7In" "Card7x5In"

Physical product to send out. See T2C Product Overview.

artwork
required
object

The front, and optionally inside, artwork to use for the product.

contributions
Array of object (Contribution)

Each contribution represents content from one person: writing, doodles and associated style. Multiple contributors can be used to include messages or signatures (doodles) from multiple people, each in their own style. No contributions results in a blank product (aside from the artwork).

images
Array of object or object

Images can be used to place photos or pre-rendered content.

The recommended image resolution is 15 pixels per mm. E.g. when including an image at 85 × 42 mm, the recommended image resolution is 85 × 15 = 1,275 px wide and 42 × 15 = 630 px high. Note that this is much higher than a typical image used for web, because print resolution is much higher than for screens.

recipient
object (Address)

Mailing address.

packaging
string
Default: "PrintedEnvelope"
Value:"PrintedEnvelope"
Option Description
PrintedEnvelope Brown craft style recycled paper envelope with simulated handwritten address.

For pricing, see T2C Order Pricing.

postalService
string (PostalService)
Enum:"AustraliaPostDomesticLetterRegular" "AustraliaPostDomesticLetterPriority" "RoyalMailFirstClassMail" "USPSFirstClassMailStampedLetter"
Country Service Delivery Time
AU AustraliaPostDomesticLetterRegular 2-6 business days
AU AustraliaPostDomesticLetterPriority 1-4 business days
GB RoyalMailFirstClassMail 1 business day inc. Sat
US USPSFirstClassMailStampedLetter 1-3 business days

For postal service pricing, see T2C Order Pricing.

requestedArrival
string <date> (RequestedArrival)

Schedule the item for future delivery. This is the calendar date that the consignment should arrive at the recipient's address.

The date the item is posted is calculated based on the maximum stated delivery time of the postage method used and the days the postal service delivers in the destination country.

shippingCallbackUrl
string (ShippingCallbackUrl)

Providing a URL here allows your system to be notified when the consignment ships. To keep track of which consignment in which order is shipping, store the order and consignment ids returned when the order is created, and match them against the content of this callback.

Example callback JSON content

{
  "orderId": "Oa9ff99478da06919",
  "consignmentId": "C0f293d380f983f1a"
  "shipped": true,
  "shippedDate": "2018-12-13"
}

Responses

200

base64 encoded preview images.

default

General error response.

post /t2c/preview
https://api.card.ly/v0/t2c/preview

Request samples

application/json
Copy
Expand all Collapse all
{
  • "product": "Card5x7In",
  • "artwork":
    {
    },
  • "contributions":
    [
    ],
  • "images":
    []
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "images":
    {
    },
  • "price":
    {
    }
}

T2C Order

Place a T2C order. Based on the selected artwork, style and content, a physical product will be printed and despatched to the specified recipient address. Sending the same request content as this endpoint to the Preview endpoint allows for showing what the printed product will look like prior to ordering.

For the price associated with calling this endpoint, see product, packaging and postalService, or call the T2C Preview endpoint for a confirmation, please refer to T2C Order Pricing for details.

Authorizations:
token (org:send)
Request Body schema: application/json
product
required
string (ProductId)
Enum:"Card5x7In" "Card7x5In"

Physical product to send out. See T2C Product Overview.

artwork
required
object

The front, and optionally inside, artwork to use for the product.

contributions
Array of object (Contribution)

Each contribution represents content from one person: writing, doodles and associated style. Multiple contributors can be used to include messages or signatures (doodles) from multiple people, each in their own style. No contributions results in a blank product (aside from the artwork).

images
Array of object or object

Images can be used to place photos or pre-rendered content.

The recommended image resolution is 15 pixels per mm. E.g. when including an image at 85 × 42 mm, the recommended image resolution is 85 × 15 = 1,275 px wide and 42 × 15 = 630 px high. Note that this is much higher than a typical image used for web, because print resolution is much higher than for screens.

recipient
required
object (Address)

Mailing address.

packaging
string
Default: "PrintedEnvelope"
Value:"PrintedEnvelope"
Option Description
PrintedEnvelope Brown craft style recycled paper envelope with simulated handwritten address.

For pricing, see T2C Order Pricing.

postalService
required
string (PostalService)
Enum:"AustraliaPostDomesticLetterRegular" "AustraliaPostDomesticLetterPriority" "RoyalMailFirstClassMail" "USPSFirstClassMailStampedLetter"
Country Service Delivery Time
AU AustraliaPostDomesticLetterRegular 2-6 business days
AU AustraliaPostDomesticLetterPriority 1-4 business days
GB RoyalMailFirstClassMail 1 business day inc. Sat
US USPSFirstClassMailStampedLetter 1-3 business days

For postal service pricing, see T2C Order Pricing.

requestedArrival
string <date> (RequestedArrival)

Schedule the item for future delivery. This is the calendar date that the consignment should arrive at the recipient's address.

The date the item is posted is calculated based on the maximum stated delivery time of the postage method used and the days the postal service delivers in the destination country.

shippingCallbackUrl
string (ShippingCallbackUrl)

Providing a URL here allows your system to be notified when the consignment ships. To keep track of which consignment in which order is shipping, store the order and consignment ids returned when the order is created, and match them against the content of this callback.

Example callback JSON content

{
  "orderId": "Oa9ff99478da06919",
  "consignmentId": "C0f293d380f983f1a"
  "shipped": true,
  "shippedDate": "2018-12-13"
}

Responses

200

Order confirmation.

default

General error response.

post /t2c/order
https://api.card.ly/v0/t2c/order

Request samples

application/json
Copy
Expand all Collapse all
{
  • "product": "Card5x7In",
  • "artwork":
    {
    },
  • "contributions":
    [
    ],
  • "recipient":
    {
    },
  • "postalService": "AustraliaPostDomesticLetterRegular",
  • "requestedArrival": "2018-12-13"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "orderId": "Oa9ff99478da06919",
  • "consignmentId": "C0f293d380f983f1a"
}

T2C Product Overview

Products

The products currently available in a T2C order are:

Product ID Description
Card5x7In 5×7 inch (portrait / side fold) greeting card.
Card7x5In 7×5 inch (landscape / top fold) greeting card.

Positioning Content

Content, such as images, doodles and handwriting areas, are positioned relative to the top left of the product when laid flat and open.

The areaIds inside/side1 and inside/side2 used for the standard handwriting areas depend on the product.

See the product-specific sections below for details about positioning and dimensions.

Card5x7In

5×7 inch (portrait / side fold) greeting card.

5×7 inch greeting card dimensions diagram. Each card side is 127 × 177.8 mm. The dimentions when open / laid flat are 254 × 177.8 mm.

inside/side1 is the inside left of the card. inside/side2 is the inside right. The 'main' message typically goes on inside/side2 (inside right).

Note that content is positioned relative to the top left of the opened / flattened card. E.g. an image placed on the card's inside right has a larger 'left' position.

Position Example use Format
Bottom left of the card's inside right First contributor's signature as a doodle
{ pos: { left: 132, top: 150 }
Bottom left of the card's inside left Second contributor's signature as a doodle
{ pos: { left: 5, top: 150 }
Center of the card's inside left Key imagery or word art
{ pos: { left: 15, top: 20 }, size: { width: 97, height: 77.8 } }

Card7x5In

7×5 inch (landscape / top fold) greeting card.

7×5 inch greeting card dimensions diagram. Each card side is 177.8 × 127 mm. The dimensions when open / laid flat are 177.8 × 254 mm

inside/side1 is the inside top of the card. inside/side2 is the inside bottom. The 'main' message typically goes on inside/side2 (inside bottom).

Note that content is positioned relative to the top left of the opened / flattened card. E.g. an image placed on the card's inside bottom has a larger 'top' position.

Position Example use Format
Bottom left of the card's inside bottom First contributor's signature as a doodle
{ pos: { left: 5, top: 244 }
Bottom left of the card's inside top Second contributor's signature as a doodle
{ pos: { left: 5, top: 117 }
Center of the card's inside top Key imagery or word art
{ pos: { left: 15, top: 15 }, size: { width: 147.8, height: 52 } }

Preview Pricing

Operation Price AUD Price GBP Price USD
T2C Preview 0.005 0.003 0.004

T2C Order Pricing

Product

Product Description Price AUD Price GBP Price USD
Card5x7In 5×7 inch (portrait) folded greeting card 2.70 1.39 2.30
Card7x5In 7×5 inch (landscape) folded greeting card 2.70 1.39 2.30

Packaging

Option Description Price AUD Price GBP Price USD
PrintedEnvelope Brown craft style recycled paper envelope with simulated handwritten address. 0.20 0.11 0.15

Postal Service

Country Service Delivery Time Price AUD Price GBP Price USD
AU AustraliaPostDomesticLetterRegular 2-6 business days 1.00 0.55 0.80
AU AustraliaPostDomesticLetterPriority 1-4 business days 1.50 0.85 1.20
GB RoyalMailFirstClassMail 1 business day inc. Sat 1.25 0.67 0.95
US USPSFirstClassMailStampedLetter 1-3 business days 0.65 0.35 0.49