Cardly - Keep it Personal
API
The Cardly API
Testing & Helpers
Account
Resources
Contacts & Lists
Ordering
User Management
References

API Overview

The version 2 Cardly API is organised around REST, with predictable resource-oriented URLs. It accepts JSON-encoded request bodies, returns JSON-encoded responses and uses standard HTTP response codes and verbs to make understanding and integrating the API as quick and painless as possible.

When you're set up on the Cardly API, you'll be provided with two API keys - one for test mode, the other for live calls. Your test mode key will allow you to make all the calls available in the API, however won't mutate any data. So, you can test your integration and make sure everything works, get back (generally!) the same response as you would for a live call, then switch out your keys when you're ready to move to live ordering.

Currently the API accepts only JSON-encoded bodies for POST requests. As such, please ensure you provide the appropriate Content-type: text/json header when forming your requests. Other content types will likely fail as the request body will not be interpreted correctly.

As we release new products and features, the Cardly API will evolve to include access to these where possible. This documentation will also evolve to cover these new features as they're released.

While we do our best to avoid it, in the event we release a breaking change, we'll let you know well in advance so you have time to plan, test and release any updates necessary to accommodate the change.

Base URL

https://api.card.ly/v2

Accepted Content-Types

Content-type: text/json

Quick Start

We've tried to design the Cardly API to make integration as quick and painless as possible for the most common ways we see businesses integrate with us. Most basic integrations with the Cardly API can be achieved with a single call, Place Order.

There's a few things you should prepare before you get started:

  1. Create a business account and confirm your email address. This will give you access to a personalised business portal.
  2. Once logged in to your business portal, navigate to Settings > API Keys and generate a new API key. For now, note the development mode API key.
  3. If you're bringing your own artwork, ensure it's added under Assets > Manage Artwork.
  4. If you're creating automated sends with common wording across each card, with personalisation details such as first name added to your messaging, ensure you've created the necessary templates under Assets > Templates

Once you have your business account, API key, artwork and templates ready to go, you'll be able to authenticate with the API using your development key. Please review the Authentication section for more details, however using your API key is as simple as adding a API-Key: (Your API Key) header to all of your calls to the API. You can test your authentication out on the Echo endpoint and verify you have this good to go.

For simple direct card sends using data from your CRM or other source you'll then use the Place Order endpoint, feeding in your desired artwork ID, template ID and recipient details.

For more complex integrations, please refer to the documentation below. Our team is always happy to discuss and guide you through the integration process, so please contact us for assistance if needed.

OpenAPI Standard

In order to speed up your development, this documentation is available in OpenAPI format. A number of IDEs will allow you to import these documents in order to quickly mock up request formats and provide in-context help for various properties and data structures used throughout the API.

We've only recently provided this publicly, so we'd love to hear your feedback on how useful these documents are and if you'd like to see any further features added to them to support your work.

Related Links

  • Download OpenAPI Specification (JSON)
  • Download OpenAPI Specification (YAML)

Authentication

The Cardly API uses API keys to authenticate requests. Your API keys can be obtained and managed from your organisation portal.

Each set of API keys provides both test and live mode keys. Test mode keys are prefixed with test_ and can perform all the functions that live keys can, however they will not perform any mutations. That is, if a test mode key calls the Place Order endpoint, the request will be validated and provide a mostly-identical response as though you'd used a live key, however no actual order will be placed. Test mode responses will always contain a testMode: true element as part of the main return body.

Live mode keys are prefixed with live_ and have none of the restrictions of test mode keys.

Authentication to the API is performed via the API-Key header, as per the provided example.

API keys permit many functions to be performed against your organisation, including billable requests. You must keep your keys secure and if you believe them to be compromised, invalidate and re-issue your keys via your organisation portal.

All API requests must be performed over HTTPS. Calls made over plain HTTP will be rejected, as will requests without authentication.

API-Key Header

API-Key: test_QRJfLM9cGJyjdaINUPJu3XVT1QltYMJLtoncY73X

Return Structure

All returns from the Cardly API will present as a JSON-encoded body with the same overall structure: an element to denote the overall call success, along with any relevant messages, a data element to pass back data relevant to the call performed, and optionally a flag to indicate the request was performed in test mode.

Additionally, HTTP status codes can also help inform your request's success. Typically, you can rely on 200 - OK and 201 - Created response codes to indicate success.

It is highly recommended that you check for the presence of testMode: true in responses to ensure you are not accidentally processing live requests with a testing key.

Common Return Structure
{"state":{"status":"OK","messages":[],"build":1234},"data":{"foo":"bar","moo":null},"testMode":true}

Response Status Object

Provides a standard status identifier to indicate overall success, along with messages and the current API build version.

Properties

Response Status Object Example
{"status":"OK","messages":[],"version":1181}

Validation Status Object

One or more elements denoting validations failures with the named field(s), and the reason for failure.

Properties

Validation Status Object Example
{"email":"This value should be a valid email address."}

Errors & Responses

The API uses standard HTTP response codes to indicate the success or failure of your API requests. Generally, codes in the 2xx range indicate success. Codes in the 4xx range indicate issues due to the data provided - authentication failures, required fields missing, insufficient funds etc. Codes in the 5xx range indicate an error on Cardly's end - these should be rare!

Where possible, we'll provide you with information on why your call failed to help you quickly diagnose and remedy the issue.

Utilised HTTP Status Codes
200 - OK
The request processed as expected.
201 - Created
The request processed, creating a relevant resource as expected.
400 - Bad Request
The request failed, likely due to missing data.
401 - Unauthorized
No valid API key was supplied.
402 - Request Failed
The request passed validation, but failed for another reason.
403 - Forbidden
The passed API key does not have privileges to perform the requested operation.
404 - Not Found
The requested resource does not exist.
422 - Unprocessable Entity
The request failed, likely due to one or more fields not passing validation.
429 - Too Many Requests
You have performed too many requests to the API in a short period of time. We recommend slowing down your request rate and implementing exponential backoff of your requests.
500 - Internal Server Error
Something went wrong on Cardly's end. We're likely already looking into it!

Idempotent Requests

The Cardly API supports idempotent requests, allowing you to safely retry requests without accentially performing the same operation twice. This is extremely useful when your API call is distrupted and you do not receive a response, or fail to complete processing of this response on your applications end (due to loss of connectivity etc).

For example, if a request to the Place Order endpoint does not result in a response, or the response times out, you can retry the exact same request again and receive the response you would have otherwise missed. This helps guarantee the original request you wanted to make is processed once, and once only.

To perform a request utilising Idempotency, supply an additional Idempotency-Key: <key> header in your request.

The API's idempotency works by saving the resulting status code and body of the original request for any given idempotency key, regardless of success. Subsequent requests with the same key return the same result, without hitting the processing layer.

Your idempotency keys are unique values generated by your client which the API uses to identify subsequent retries of the same request. Generation and format of idempotency keys is up to you, however Cardly recommends v4 UUIDs or another random string of sufficent length to guarantee uniqueness. Your idempotency keys may be up to 64 characters in length.

In addition, to ensure you do not accidentally reuse or change your original request when utilising idempotency keys, we analyse the incoming request to ensure it is consistent with any previously logged request. In the event an idempotency result is found with a different request signature, you'll receive an error indicating the request was changed, but an idempotency key was being reused.

Idempotent results will only be saved if the request started started processing - if the request failed due to invalid credentials, missing parameters etc, the idempotency key will not be consumed by the request. You can therefore safely re-use idempotency keys until a successful operation is processed.

Please note that only POST requests accept idempotency keys. All other HTTP verbs currently in use by the Cardly API will ignore idempotency keys, as these requests are idempotent by definition.

Idempotency-Key Header

Idempotency-Key: f47b838a-304d-f88c-4d2c-a8709cacfdc8

Request IDs

Every API request performed will return an associated request identifier in the response headers. You can find this in your response under the Request-Id header. You will also be able to find request identifiers within your organisation portal API logs.

If you need to contact us for support, particularly with regard to a specific request, providing the relevant Request-Id will help us to resolve your query as quickly as possible.

Request-Id Response Header

Request-Id: c64695af-eaf4-1d4e-c2fa-c89417a3fd7c

Pagination

Most top-level endpoints in the API provide support for bulk fetches for list-style data. The request and response formats for these calls share a common structure to simplify understanding these calls. They all at minimum accept the following parameters: limit and offset.

To navigate lists of paginated data, simply increase the offset parameter by the limit value you are utilising (or the default of 25 if you aren't specifying a limit). Ensure that you don't navigate past the end of a resource list by checking to ensure your offset is below the meta.totalRecords value in the previous response.

Request: GET /v2/art?limit=10&offset=20
{"state":{"status":"OK","messages":[],"version":1234},"data":{"meta":{"orderBy":"name","orderDirection":"asc","startRecord":21,"lastRecord":30,"limit":10,"page":3,"offset":20,"totalRecords":395},"results":[]}}

Pagination Metadata Object

Provides a standard description of a listing result set and the records that were retrieved.

Properties

Pagination Metadata Object Example
{"orderBy":"name","orderDirection":"asc","startRecord":1,"lastRecord":25,"limit":25,"page":2,"offset":0,"totalRecords":123}

Development Helpers

Echo provides a simple, low impact means of testing API features. We'll simply take your request, headers and body parameters and return these back to you in a standard structure.

This way you can quickly test your authentication, idempotency behaviour and get a feel for the API features before diving in to real requests.

ANY Echo Request

The echo endpoint will take any parameters, body structure and headers and return them to you in a JSON structure. You can use this endpoint to quickly debug other requests, validate your authentication, idempotency and other API features without any impact on your account or any risk of credit usage.

This endpoint is special in that it will accept any HTTP verb and still provide an output to the caller.

Please note: you must still authenticate to this endpoint and you'll receive appropriate error responses if your API key is invalid or not supplied.

Request Parameters

Request Body

ANY /echo
{"foo":"bar","bar":["A","B","C"]}

200 Response Body

A description of all data passed in the request.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"method":"POST","url":"https:\/\/api.card.ly\/v2\/echo","headers":{"api-key":"test_QRJ***73X","content-type":"application\/json","accept":"*\/*","cache-control":"no-cache","host":"api.card.ly","accept-encoding":"gzip, deflate","content-length":60,"connection":"keep-alive"},"params":{"test":"foo"},"body":{"foo":"bar","bar":["A","B","C"]}}}

Account

Account functions aid with checking your organistaion's current balance, reviewing previous transactions, adding more credit and performing updates to organisation details.

Credit History Object

The credit history object models an entry - positive or negative - for the organisation's credit purchase and spends.

Properties

Credit History Object Example
{"id":"484ed6af-416e-1f76-7807-c88104734f09","orderId":"7807d6af-484e-c881-1f76-416e04734f09","transactionId":"f47b838a-304d-f88c-4d2c-a8709cacfdc8","type":"Signup Bonus","typeCode":"C","change":3,"newBalance":15.5,"effectiveTime":"2019-11-23 12:10:54","notes":"Payment for order 1bb30e7f-afde-b822-762a-ecd5c2dc1c40 lodged at 21\/11\/2022 10:31:36"}

Gift Credit History Object

The gift credit history object models an entry - positive or negative - for the organisation's gift credit purchase and spends.

Properties

Gift Credit History Object Example
{"id":"484ed6af-416e-1f76-7807-c88104734f09","orderId":"7807d6af-484e-c881-1f76-416e04734f09","transactionId":"f47b838a-304d-f88c-4d2c-a8709cacfdc8","type":"Signup Bonus","typeCode":"C","change":33,"changeNet":30,"changeTax":3,"newBalance":15.5,"effectiveTime":"2019-11-23 12:10:54","notes":"Payment for order 1bb30e7f-afde-b822-762a-ecd5c2dc1c40 lodged at 21\/11\/2022 10:31:36"}

GET Retrieve Account Balance

This endpoint allows you to quickly query the current balance for your organisation.

Where relevant, API calls which consume or have the potential to consume balance will return your organisation's balance in the return structure for convenience. This will allow you to easily determine if additional balance should be added to your account if not utilising the automatic account topup feature.

GET /account/balance
(No body required)

200 Response Body

Your account's current credit and gift credit balances.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"balance":123.21,"giftCredit":{"balance":145.43,"currency":"USD"}}}

GET List Credit History

Retrieve a section of balance history records pertaning to your organistaion. This will list both credits and debits, along with links / reasons for each, where applicable.

This request accepts standard pagination options limit, offset along with the following additional filters:

Request Parameters

GET /account/credit-history
(No body required)

200 Response Body

A paginated array of zero or more CreditHistory objects.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"meta":{"orderBy":"name","orderDirection":"asc","startRecord":1,"lastRecord":25,"limit":25,"page":2,"offset":0,"totalRecords":123},"results":[{"id":"484ed6af-416e-1f76-7807-c88104734f09","orderId":"7807d6af-484e-c881-1f76-416e04734f09","transactionId":"f47b838a-304d-f88c-4d2c-a8709cacfdc8","type":"Signup Bonus","typeCode":"C","change":3,"newBalance":15.5,"effectiveTime":"2019-11-23 12:10:54","notes":"Payment for order 1bb30e7f-afde-b822-762a-ecd5c2dc1c40 lodged at 21\/11\/2022 10:31:36"}]}}

GET List Gift Credit History

Retrieve a section of gift credit history records pertaning to your organistaion. This will list both credits and debits, along with links / reasons for each, where applicable.

This request accepts standard pagination options limit, offset along with the following additional filters:

Request Parameters

GET /account/gift-credit-history
(No body required)

200 Response Body

A paginated array of zero or more GiftCreditHistory objects.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"meta":{"orderBy":"name","orderDirection":"asc","startRecord":1,"lastRecord":25,"limit":25,"page":2,"offset":0,"totalRecords":123},"results":[{"id":"484ed6af-416e-1f76-7807-c88104734f09","orderId":"7807d6af-484e-c881-1f76-416e04734f09","transactionId":"f47b838a-304d-f88c-4d2c-a8709cacfdc8","type":"Signup Bonus","typeCode":"C","change":33,"changeNet":30,"changeTax":3,"newBalance":15.5,"effectiveTime":"2019-11-23 12:10:54","notes":"Payment for order 1bb30e7f-afde-b822-762a-ecd5c2dc1c40 lodged at 21\/11\/2022 10:31:36"}]}}

Artwork

Artwork functions allow you to retrieve, add and update your organisation's current available artwork. The identifiers used in artwork models are required in other calls such as PlaceOrder and these endpoints can facilitate finding or creating these programatically if required.

Artwork Object

The artwork object represents a product at a given media size and provides preview images for each page capable of hosting artwork imagery.

Properties

Artwork Object Example
{"id":"484ed6af-416e-1f76-7807-c88104734f09","revision":8,"name":"API Artwork Upload","slug":"api-artwork-upload","fullPath":"\/pied-piper\/api-artwork-upload","description":"Testing adding a 4p card via API call.","artwork":["https:\/\/www.cardly.net\/card\/1\/2862abe8-a299-30f2-6324-bd891e687f0d\/page1-r2-i6142-04ebfa87e8f09f1127d6f0c4a27e02c9.png\/vp\/detail-card\/1200",null,"https:\/\/www.cardly.net\/card\/3\/2862abe8-a299-30f2-6324-bd891e687f0d\/page3-r2-i6142-6ea511b3b4d4e99bd41188704026cecc.png\/vp\/detail-card\/1200",null],"media":{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}},"createdAt":"2020-06-14T09:40:09+10:00","updatedAt":"2020-06-14T14:39:35+10:00"}

GET List Artwork

Retrieve the currently available artwork for your organisation.

This request accepts standard pagination options limit, offset along with the following additional filters:

Request Parameters

GET /art
(No body required)

200 Response Body

A paginated array of zero or more Artwork objects.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"meta":{"orderBy":"name","orderDirection":"asc","startRecord":1,"lastRecord":25,"limit":25,"page":2,"offset":0,"totalRecords":123},"results":[{"id":"484ed6af-416e-1f76-7807-c88104734f09","revision":8,"name":"API Artwork Upload","slug":"api-artwork-upload","fullPath":"\/pied-piper\/api-artwork-upload","description":"Testing adding a 4p card via API call.","artwork":["https:\/\/www.cardly.net\/card\/1\/2862abe8-a299-30f2-6324-bd891e687f0d\/page1-r2-i6142-04ebfa87e8f09f1127d6f0c4a27e02c9.png\/vp\/detail-card\/1200",null,"https:\/\/www.cardly.net\/card\/3\/2862abe8-a299-30f2-6324-bd891e687f0d\/page3-r2-i6142-6ea511b3b4d4e99bd41188704026cecc.png\/vp\/detail-card\/1200",null],"media":{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}},"createdAt":"2020-06-14T09:40:09+10:00","updatedAt":"2020-06-14T14:39:35+10:00"}]}}

POST Create Artwork

Add a new piece of artwork.

Request Body

POST /art
{"media":"fd7368b0-ad4d-11ea-9da9-04d4c4254e1b","name":"API Artwork Upload","description":"Testing adding a 4p card via API call.","artwork":[{"page":1,"image":"iVBORw0KGg..."},{"page":3,"image":"iVBORw0KGg..."}]}

200 Response Body

An Artwork representing the artwork that was just created. Use the ID property from this to feed into order/preview requests as needed.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"484ed6af-416e-1f76-7807-c88104734f09","revision":8,"name":"API Artwork Upload","slug":"api-artwork-upload","fullPath":"\/pied-piper\/api-artwork-upload","description":"Testing adding a 4p card via API call.","artwork":["https:\/\/www.cardly.net\/card\/1\/2862abe8-a299-30f2-6324-bd891e687f0d\/page1-r2-i6142-04ebfa87e8f09f1127d6f0c4a27e02c9.png\/vp\/detail-card\/1200",null,"https:\/\/www.cardly.net\/card\/3\/2862abe8-a299-30f2-6324-bd891e687f0d\/page3-r2-i6142-6ea511b3b4d4e99bd41188704026cecc.png\/vp\/detail-card\/1200",null],"media":{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}},"createdAt":"2020-06-14T09:40:09+10:00","updatedAt":"2020-06-14T14:39:35+10:00"}}

GET Retrieve Artwork

Retrieve information on a specific piece of artwork.

Request Parameters

GET /art/{id}
(No body required)

200 Response Body

An Artwork representing the requested piece of artwork.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"484ed6af-416e-1f76-7807-c88104734f09","revision":8,"name":"API Artwork Upload","slug":"api-artwork-upload","fullPath":"\/pied-piper\/api-artwork-upload","description":"Testing adding a 4p card via API call.","artwork":["https:\/\/www.cardly.net\/card\/1\/2862abe8-a299-30f2-6324-bd891e687f0d\/page1-r2-i6142-04ebfa87e8f09f1127d6f0c4a27e02c9.png\/vp\/detail-card\/1200",null,"https:\/\/www.cardly.net\/card\/3\/2862abe8-a299-30f2-6324-bd891e687f0d\/page3-r2-i6142-6ea511b3b4d4e99bd41188704026cecc.png\/vp\/detail-card\/1200",null],"media":{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}},"createdAt":"2020-06-14T09:40:09+10:00","updatedAt":"2020-06-14T14:39:35+10:00"}}

POST Edit Artwork

Update a piece of artwork with new descriptors or images. All parameters are optional, and only supplied parameters will be updated.

Request Parameters

Request Body

POST /art/{id}
{"name":"API Artwork Update","description":"Testing updating a 4p card via API call.","artwork":[{"page":1,"image":"iVBORw0KGg..."},{"page":3,"image":"iVBORw0KGg..."}]}

200 Response Body

An Artwork representing the updated piece of artwork.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"484ed6af-416e-1f76-7807-c88104734f09","revision":8,"name":"API Artwork Upload","slug":"api-artwork-upload","fullPath":"\/pied-piper\/api-artwork-upload","description":"Testing adding a 4p card via API call.","artwork":["https:\/\/www.cardly.net\/card\/1\/2862abe8-a299-30f2-6324-bd891e687f0d\/page1-r2-i6142-04ebfa87e8f09f1127d6f0c4a27e02c9.png\/vp\/detail-card\/1200",null,"https:\/\/www.cardly.net\/card\/3\/2862abe8-a299-30f2-6324-bd891e687f0d\/page3-r2-i6142-6ea511b3b4d4e99bd41188704026cecc.png\/vp\/detail-card\/1200",null],"media":{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}},"createdAt":"2020-06-14T09:40:09+10:00","updatedAt":"2020-06-14T14:39:35+10:00"}}

DELETE Delete Artwork

Delete a piece of artwork owned by your organisation.

Request Parameters

DELETE /art/{id}
(No body required)

200 Response Body

An Artwork representing the artwork that was deleted.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"484ed6af-416e-1f76-7807-c88104734f09","revision":8,"name":"API Artwork Upload","slug":"api-artwork-upload","fullPath":"\/pied-piper\/api-artwork-upload","description":"Testing adding a 4p card via API call.","artwork":["https:\/\/www.cardly.net\/card\/1\/2862abe8-a299-30f2-6324-bd891e687f0d\/page1-r2-i6142-04ebfa87e8f09f1127d6f0c4a27e02c9.png\/vp\/detail-card\/1200",null,"https:\/\/www.cardly.net\/card\/3\/2862abe8-a299-30f2-6324-bd891e687f0d\/page3-r2-i6142-6ea511b3b4d4e99bd41188704026cecc.png\/vp\/detail-card\/1200",null],"media":{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}},"createdAt":"2020-06-14T09:40:09+10:00","updatedAt":"2020-06-14T14:39:35+10:00"}}

Doodles

The doodles endpoints provide data about the doodles available to you within Cardly. This data can be used to build doodle sample interfaces for external integrations which build and send cards via Cardly for consumer or promotion-based activities.

Doodle Object

The doodle object represents a vector-based image which can be included within card artwork.

Properties

Doodle Object Example
{"id":"31035c6a-9311-15aa-638e-6894acb0e668","name":"4WD Car","slug":"4wd-car","description":null,"image":"https:\/\/www.cardly.net\/doodle\/preview\/31035c6a-9311-15aa-638e-6894acb0e668","dimensions":{"height":105,"width":148},"restricted":false}

GET List Doodles

Retrieve your currently available doodles.

This request accepts standard pagination options limit, offset along with the following additional filters:

Request Parameters

GET /doodles
(No body required)

200 Response Body

A paginated array of zero or more Doodle objects.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"meta":{"orderBy":"name","orderDirection":"asc","startRecord":1,"lastRecord":25,"limit":25,"page":2,"offset":0,"totalRecords":123},"results":[{"id":"31035c6a-9311-15aa-638e-6894acb0e668","name":"4WD Car","slug":"4wd-car","description":null,"image":"https:\/\/www.cardly.net\/doodle\/preview\/31035c6a-9311-15aa-638e-6894acb0e668","dimensions":{"height":105,"width":148},"restricted":false}]}}

Fonts

The font endpoints provide data about the fonts available to you within Cardly. This data can be used to build font sample interfaces for external integrations which build and send cards via Cardly for consumer or promotion-based activities.

Font Object

The font object models a style of writing available within Cardly, either from our shared library or your exclusive handwriting conversions.

Properties

Font Object Example
{"id":"461910d8-ff8c-ee8d-efe5-d5feb3f9113a","name":"Brad","category":"hand","familyVariants":3,"canHumanise":true,"restricted":false}

GET List Fonts

Retrieve your currently available fonts.

This request accepts standard pagination options limit, offset along with the following additional filters:

Request Parameters

GET /fonts
(No body required)

200 Response Body

A paginated array of zero or more Font objects.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"meta":{"orderBy":"name","orderDirection":"asc","startRecord":1,"lastRecord":25,"limit":25,"page":2,"offset":0,"totalRecords":123},"results":[{"id":"461910d8-ff8c-ee8d-efe5-d5feb3f9113a","name":"Brad","category":"hand","familyVariants":3,"canHumanise":true,"restricted":false}]}}

Media

The media endpoints provide data about the types and dimensions of available products within Cardly. This information can be used to validate specifications on new artwork, or see which products are currently on offer in various regions.

Please note: Some media sizes are not all available in all regions Cardly covers. Where you attempt to order media from an unsupported region, the relevant endpoint will return an error.

Media Object

The media object models a product available on Cardly and denotes the regions it is available for purchase in. It also provides information on the dimensions of the product, both physical and pixel dimensions for artwork supply.

Properties

Media Object Example
{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}}

GET List Media

Retrieve the currently available media sizes for product artwork.

This request accepts standard pagination options limit, offset along with the following additional filters:

Request Parameters

GET /media
(No body required)

200 Response Body

A paginated array of zero or more Media objects.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"meta":{"orderBy":"name","orderDirection":"asc","startRecord":1,"lastRecord":25,"limit":25,"page":2,"offset":0,"totalRecords":123},"results":[{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}}]}}

Templates

The template endpoints allow you to retrieve and manipulate templates available to your organisation.

Template Object

The template object denotes styling and structure to be applied to a given media size card.

Properties

Template Object Example
{"id":"18ecf6e6-d2e2-49cb-bae0-fa980241db73","name":"Happy Birthday","slug":"happy-birthday","generic":false,"media":{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}},"giftCard":{"id":"4b458510-5b7f-0bdc-7e21-891ce658a935","region":"AU","currency":"AUD","amount":50,"canChange":true},"definition":{"version":2.2,"style":{"align":"left","color":"1144a7","size":25,"writing":"987d50c7-25e1-3b1c-aa78-6f60b1411fe5","font":"0d372503-c81b-987d-7636-bd6321290528"},"pages":[],"variables":{"firstName":{"description":"Customer's first name to display in card front and salutation.","example":"John"}}},"createdAt":"2020-06-14T09:40:09+10:00","updatedAt":"2020-06-14T14:39:35+10:00"}

GET List Templates

Retrieve your currently available templates.

GET /templates
(No body required)

200 Response Body

A paginated array of zero or more Template objects.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"meta":{"orderBy":"name","orderDirection":"asc","startRecord":1,"lastRecord":25,"limit":25,"page":2,"offset":0,"totalRecords":123},"results":[{"id":"18ecf6e6-d2e2-49cb-bae0-fa980241db73","name":"Happy Birthday","slug":"happy-birthday","generic":false,"media":{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}},"giftCard":{"id":"4b458510-5b7f-0bdc-7e21-891ce658a935","region":"AU","currency":"AUD","amount":50,"canChange":true},"definition":{"version":2.2,"style":{"align":"left","color":"1144a7","size":25,"writing":"987d50c7-25e1-3b1c-aa78-6f60b1411fe5","font":"0d372503-c81b-987d-7636-bd6321290528"},"pages":[],"variables":{"firstName":{"description":"Customer's first name to display in card front and salutation.","example":"John"}}},"createdAt":"2020-06-14T09:40:09+10:00","updatedAt":"2020-06-14T14:39:35+10:00"}]}}

Writing Styles

The writing-styles endpoints provide data about the doodles available to you within Cardly. This data can be used to build writing sample interfaces for external integrations which build and send cards via Cardly for consumer or promotion-based activities.

Writing Style Object

The writing object denotes a messiness level applied to our algorithmic handwriting generation.

Properties

Writing Style Object Example
{"id":"18ecf6e6-d2e2-49cb-bae0-fa980241db73","name":"Perfection","description":"No humanisation applied at all, absolutely perfect writing.","order":0}

GET List Writing Styles

Retrieve your currently available writing styles.

GET /writing-styles
(No body required)

200 Response Body

A paginated array of zero or more WritingStyle objects.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"meta":{"orderBy":"name","orderDirection":"asc","startRecord":1,"lastRecord":25,"limit":25,"page":2,"offset":0,"totalRecords":123},"results":[{"id":"18ecf6e6-d2e2-49cb-bae0-fa980241db73","name":"Perfection","description":"No humanisation applied at all, absolutely perfect writing.","order":0}]}}

Contact Lists

The contact-lists endpoints provide the ability to create, manipulate and interrogate lists of users, employees and other contacts. These groupings allow you to then set up automation rules based on fields within your lists (such as a birthday or anniversary date) to automatically send a specified card and message to a user at an appropriate point in future - potentially yearly, if desired.

While contact lists and associated fields can be created and managed by these endpoints, currently automation rules will need to be managed via your Cardly portal. We'll open the ability to do this programatically in future, however given the complex nature of these rules our UI is the best way of managing these for the moment.

Contact List Object

The contact list object provides detail on a given list on your account, along with currently set up custom fields and automation details.

Properties

Contact List Object Example
{"id":"6d7c260b-f39f-e822-6aa5-612014047d20","name":"Online Sales","description":"All customers purchased since 2017-01-01","status":"active","contacts":154,"automations":3,"fields":[{"id":"9da307a4-1c37-f69a-c6ec-1ba002165d57","code":"dateField","name":"Date Field","description":null,"type":"date","status":"active"}],"rules":[{"id":"45702de2-dee0-2b14-ed52-ae63886f28f1","fieldId":"b9763d1b-e0fd-77a3-7afb-6edbf07fe087","cardArt":[{"id":"484ed6af-416e-1f76-7807-c88104734f09","revision":8,"name":"API Artwork Upload","slug":"api-artwork-upload","fullPath":"\/pied-piper\/api-artwork-upload","description":"Testing adding a 4p card via API call.","artwork":["https:\/\/www.cardly.net\/card\/1\/2862abe8-a299-30f2-6324-bd891e687f0d\/page1-r2-i6142-04ebfa87e8f09f1127d6f0c4a27e02c9.png\/vp\/detail-card\/1200",null,"https:\/\/www.cardly.net\/card\/3\/2862abe8-a299-30f2-6324-bd891e687f0d\/page3-r2-i6142-6ea511b3b4d4e99bd41188704026cecc.png\/vp\/detail-card\/1200",null],"media":{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}},"createdAt":"2020-06-14T09:40:09+10:00","updatedAt":"2020-06-14T14:39:35+10:00"}],"templateId":"cddf4ba9-747c-aee9-5373-6d985cbfb198","enabled":true,"name":"Trigger When Number Field Zero","description":null,"operator":"eq","value":0,"annual":true,"bindings":{"name":"birthday","format":null}}],"validation":{"pending":11,"requireAction":6,"validated":4}}

GET List Contact Lists

Retrieve active contact lists for your organisation.

GET /contact-lists
(No body required)

200 Response Body

A paginated array of zero or more ContactList objects.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"meta":{"orderBy":"name","orderDirection":"asc","startRecord":1,"lastRecord":25,"limit":25,"page":2,"offset":0,"totalRecords":123},"results":[{"id":"6d7c260b-f39f-e822-6aa5-612014047d20","name":"Online Sales","description":"All customers purchased since 2017-01-01","status":"active","contacts":154,"automations":3,"fields":[{"id":"9da307a4-1c37-f69a-c6ec-1ba002165d57","code":"dateField","name":"Date Field","description":null,"type":"date","status":"active"}],"rules":[{"id":"45702de2-dee0-2b14-ed52-ae63886f28f1","fieldId":"b9763d1b-e0fd-77a3-7afb-6edbf07fe087","cardArt":[{"id":"484ed6af-416e-1f76-7807-c88104734f09","revision":8,"name":"API Artwork Upload","slug":"api-artwork-upload","fullPath":"\/pied-piper\/api-artwork-upload","description":"Testing adding a 4p card via API call.","artwork":["https:\/\/www.cardly.net\/card\/1\/2862abe8-a299-30f2-6324-bd891e687f0d\/page1-r2-i6142-04ebfa87e8f09f1127d6f0c4a27e02c9.png\/vp\/detail-card\/1200",null,"https:\/\/www.cardly.net\/card\/3\/2862abe8-a299-30f2-6324-bd891e687f0d\/page3-r2-i6142-6ea511b3b4d4e99bd41188704026cecc.png\/vp\/detail-card\/1200",null],"media":{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}},"createdAt":"2020-06-14T09:40:09+10:00","updatedAt":"2020-06-14T14:39:35+10:00"}],"templateId":"cddf4ba9-747c-aee9-5373-6d985cbfb198","enabled":true,"name":"Trigger When Number Field Zero","description":null,"operator":"eq","value":0,"annual":true,"bindings":{"name":"birthday","format":null}}],"validation":{"pending":11,"requireAction":6,"validated":4}}]}}

POST Create Contact List

Add a new contact list, optionally with custom fields.

Request Body

POST /contact-lists
{"name":"Employee Birthdays","description":"Current employee birthdays for all staff.","fields":[{"name":"Birthday","type":"date","image":"iVBORw0KGg..."},{"name":"Preferred Name","type":"text","description":"The customer's preferred name when we address them."}]}

200 Response Body

A ContactList representing the list that was just created. Use the ID property from this to feed into further requests as needed.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"6d7c260b-f39f-e822-6aa5-612014047d20","name":"Online Sales","description":"All customers purchased since 2017-01-01","status":"active","contacts":154,"automations":3,"fields":[{"id":"9da307a4-1c37-f69a-c6ec-1ba002165d57","code":"dateField","name":"Date Field","description":null,"type":"date","status":"active"}],"rules":[{"id":"45702de2-dee0-2b14-ed52-ae63886f28f1","fieldId":"b9763d1b-e0fd-77a3-7afb-6edbf07fe087","cardArt":[{"id":"484ed6af-416e-1f76-7807-c88104734f09","revision":8,"name":"API Artwork Upload","slug":"api-artwork-upload","fullPath":"\/pied-piper\/api-artwork-upload","description":"Testing adding a 4p card via API call.","artwork":["https:\/\/www.cardly.net\/card\/1\/2862abe8-a299-30f2-6324-bd891e687f0d\/page1-r2-i6142-04ebfa87e8f09f1127d6f0c4a27e02c9.png\/vp\/detail-card\/1200",null,"https:\/\/www.cardly.net\/card\/3\/2862abe8-a299-30f2-6324-bd891e687f0d\/page3-r2-i6142-6ea511b3b4d4e99bd41188704026cecc.png\/vp\/detail-card\/1200",null],"media":{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}},"createdAt":"2020-06-14T09:40:09+10:00","updatedAt":"2020-06-14T14:39:35+10:00"}],"templateId":"cddf4ba9-747c-aee9-5373-6d985cbfb198","enabled":true,"name":"Trigger When Number Field Zero","description":null,"operator":"eq","value":0,"annual":true,"bindings":{"name":"birthday","format":null}}],"validation":{"pending":11,"requireAction":6,"validated":4}}}

GET Retrieve Contact List

Retrieve information on a specific contact list.

Request Parameters

GET /contact-lists/{id}
(No body required)

200 Response Body

A ContactList representing the requested contact list.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"6d7c260b-f39f-e822-6aa5-612014047d20","name":"Online Sales","description":"All customers purchased since 2017-01-01","status":"active","contacts":154,"automations":3,"fields":[{"id":"9da307a4-1c37-f69a-c6ec-1ba002165d57","code":"dateField","name":"Date Field","description":null,"type":"date","status":"active"}],"rules":[{"id":"45702de2-dee0-2b14-ed52-ae63886f28f1","fieldId":"b9763d1b-e0fd-77a3-7afb-6edbf07fe087","cardArt":[{"id":"484ed6af-416e-1f76-7807-c88104734f09","revision":8,"name":"API Artwork Upload","slug":"api-artwork-upload","fullPath":"\/pied-piper\/api-artwork-upload","description":"Testing adding a 4p card via API call.","artwork":["https:\/\/www.cardly.net\/card\/1\/2862abe8-a299-30f2-6324-bd891e687f0d\/page1-r2-i6142-04ebfa87e8f09f1127d6f0c4a27e02c9.png\/vp\/detail-card\/1200",null,"https:\/\/www.cardly.net\/card\/3\/2862abe8-a299-30f2-6324-bd891e687f0d\/page3-r2-i6142-6ea511b3b4d4e99bd41188704026cecc.png\/vp\/detail-card\/1200",null],"media":{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}},"createdAt":"2020-06-14T09:40:09+10:00","updatedAt":"2020-06-14T14:39:35+10:00"}],"templateId":"cddf4ba9-747c-aee9-5373-6d985cbfb198","enabled":true,"name":"Trigger When Number Field Zero","description":null,"operator":"eq","value":0,"annual":true,"bindings":{"name":"birthday","format":null}}],"validation":{"pending":11,"requireAction":6,"validated":4}}}

POST Create Contact List

Add a new contact list, optionally with custom fields.

Request Parameters

Request Body

POST /contact-lists/{id}
{"name":"Employee Birthdays","description":"Current employee birthdays for all staff.","fields":[{"id":"58255904-7cbf-4421-9af7-c2dac50e4a91","remove":true},{"name":"Birthday","type":"date"},{"name":"Preferred Name","type":"text","description":"The customer's preferred name when we address them."}]}

200 Response Body

A ContactList representing the list that was updated.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"6d7c260b-f39f-e822-6aa5-612014047d20","name":"Online Sales","description":"All customers purchased since 2017-01-01","status":"active","contacts":154,"automations":3,"fields":[{"id":"9da307a4-1c37-f69a-c6ec-1ba002165d57","code":"dateField","name":"Date Field","description":null,"type":"date","status":"active"}],"rules":[{"id":"45702de2-dee0-2b14-ed52-ae63886f28f1","fieldId":"b9763d1b-e0fd-77a3-7afb-6edbf07fe087","cardArt":[{"id":"484ed6af-416e-1f76-7807-c88104734f09","revision":8,"name":"API Artwork Upload","slug":"api-artwork-upload","fullPath":"\/pied-piper\/api-artwork-upload","description":"Testing adding a 4p card via API call.","artwork":["https:\/\/www.cardly.net\/card\/1\/2862abe8-a299-30f2-6324-bd891e687f0d\/page1-r2-i6142-04ebfa87e8f09f1127d6f0c4a27e02c9.png\/vp\/detail-card\/1200",null,"https:\/\/www.cardly.net\/card\/3\/2862abe8-a299-30f2-6324-bd891e687f0d\/page3-r2-i6142-6ea511b3b4d4e99bd41188704026cecc.png\/vp\/detail-card\/1200",null],"media":{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}},"createdAt":"2020-06-14T09:40:09+10:00","updatedAt":"2020-06-14T14:39:35+10:00"}],"templateId":"cddf4ba9-747c-aee9-5373-6d985cbfb198","enabled":true,"name":"Trigger When Number Field Zero","description":null,"operator":"eq","value":0,"annual":true,"bindings":{"name":"birthday","format":null}}],"validation":{"pending":11,"requireAction":6,"validated":4}}}

DELETE Delete Contact List

Delete a contact list, disabling any automations linked to it.

Request Parameters

DELETE /contact-lists/{id}
(No body required)

200 Response Body

A ContactList representing the contact list that was deleted.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"6d7c260b-f39f-e822-6aa5-612014047d20","name":"Online Sales","description":"All customers purchased since 2017-01-01","status":"active","contacts":154,"automations":3,"fields":[{"id":"9da307a4-1c37-f69a-c6ec-1ba002165d57","code":"dateField","name":"Date Field","description":null,"type":"date","status":"active"}],"rules":[{"id":"45702de2-dee0-2b14-ed52-ae63886f28f1","fieldId":"b9763d1b-e0fd-77a3-7afb-6edbf07fe087","cardArt":[{"id":"484ed6af-416e-1f76-7807-c88104734f09","revision":8,"name":"API Artwork Upload","slug":"api-artwork-upload","fullPath":"\/pied-piper\/api-artwork-upload","description":"Testing adding a 4p card via API call.","artwork":["https:\/\/www.cardly.net\/card\/1\/2862abe8-a299-30f2-6324-bd891e687f0d\/page1-r2-i6142-04ebfa87e8f09f1127d6f0c4a27e02c9.png\/vp\/detail-card\/1200",null,"https:\/\/www.cardly.net\/card\/3\/2862abe8-a299-30f2-6324-bd891e687f0d\/page3-r2-i6142-6ea511b3b4d4e99bd41188704026cecc.png\/vp\/detail-card\/1200",null],"media":{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}},"createdAt":"2020-06-14T09:40:09+10:00","updatedAt":"2020-06-14T14:39:35+10:00"}],"templateId":"cddf4ba9-747c-aee9-5373-6d985cbfb198","enabled":true,"name":"Trigger When Number Field Zero","description":null,"operator":"eq","value":0,"annual":true,"bindings":{"name":"birthday","format":null}}],"validation":{"pending":11,"requireAction":6,"validated":4}}}

Contacts

The contact endpoints provide the ability to create, manipulate and interrogate records of users, employees and other contacts.

Contact Object

The contact object provides detail on a given record within a contact list. This contains their addressing information, unique identifiers (email, external ID where supplied) and any additional custom field data you may have supplied for the list.

Properties

Contact Object Example
{"id":"23fb4b1c-f127-eeea-9f68-6f0a7945da43","externalId":"thor1234","contactListId":"b905e966-ecdf-9656-2564-049c334a4db3","status":"active","firstName":"Thor","lastName":"Odinson","fullName":"Thor Odinson","email":"thor@avengers.com","company":"Avengers Inc.","address":"1 Main Street","address2":null,"locality":"Brooklyn","adminAreaLevel1":"NY","country":"US","postcode":12345,"latitude":40.761635,"longitude":-73.971802,"rawAddress":"1 Main Street, Brooklyn, New York, USA","requiresAction":false,"fields":{"birthday":"1052-04-01","homepage":"https:\/\/www.avengers.com\/profile\/thor"}}

GET List Contacts

Retrieve active contacts in a given list.

Request Parameters

GET /contact-lists/{listId}/contacts
(No body required)

200 Response Body

A paginated array of zero or more Contact records.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"meta":{"orderBy":"name","orderDirection":"asc","startRecord":1,"lastRecord":25,"limit":25,"page":2,"offset":0,"totalRecords":123},"results":[{"id":"23fb4b1c-f127-eeea-9f68-6f0a7945da43","externalId":"thor1234","contactListId":"b905e966-ecdf-9656-2564-049c334a4db3","status":"active","firstName":"Thor","lastName":"Odinson","fullName":"Thor Odinson","email":"thor@avengers.com","company":"Avengers Inc.","address":"1 Main Street","address2":null,"locality":"Brooklyn","adminAreaLevel1":"NY","country":"US","postcode":12345,"latitude":40.761635,"longitude":-73.971802,"rawAddress":"1 Main Street, Brooklyn, New York, USA","requiresAction":false,"fields":{"birthday":"1052-04-01","homepage":"https:\/\/www.avengers.com\/profile\/thor"}}]}}

POST Create Contact

Add a new contact to a given list.

Please note: contacts added via API calls will be checked for uniqueness based on your externalId and email fields, if supplied. If a contact already exists for one of these fields the addition operation will be rejected.

Request Parameters

Request Body

POST /contact-lists/{listId}/contacts
{"externalId":"thor1234","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","company":"Avengers Inc.","address":"1 Main Street","address2":"Suite 1451","locality":"Brooklyn","region":"NY","country":"US","postcode":12345,"fields":{"birthday":"1052-04-01","homepage":"https:\/\/www.avengers.com\/profile\/thor"}}

200 Response Body

A Contact representing the contact that was created.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"23fb4b1c-f127-eeea-9f68-6f0a7945da43","externalId":"thor1234","contactListId":"b905e966-ecdf-9656-2564-049c334a4db3","status":"active","firstName":"Thor","lastName":"Odinson","fullName":"Thor Odinson","email":"thor@avengers.com","company":"Avengers Inc.","address":"1 Main Street","address2":null,"locality":"Brooklyn","adminAreaLevel1":"NY","country":"US","postcode":12345,"latitude":40.761635,"longitude":-73.971802,"rawAddress":"1 Main Street, Brooklyn, New York, USA","requiresAction":false,"fields":{"birthday":"1052-04-01","homepage":"https:\/\/www.avengers.com\/profile\/thor"}}}

DELETE Delete Contact

Delete a contact, disabling any automations linked to it.

Contact matching is performed in order of matching external ID or email address. At least one of these details must be provided.

Request Parameters

Request Body

DELETE /contact-lists/{listId}/contacts
{"email":"thor@avengers.com","externalId":"thor1234"}

200 Response Body

A Contact representing the contact that was deleted.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"23fb4b1c-f127-eeea-9f68-6f0a7945da43","externalId":"thor1234","contactListId":"b905e966-ecdf-9656-2564-049c334a4db3","status":"active","firstName":"Thor","lastName":"Odinson","fullName":"Thor Odinson","email":"thor@avengers.com","company":"Avengers Inc.","address":"1 Main Street","address2":null,"locality":"Brooklyn","adminAreaLevel1":"NY","country":"US","postcode":12345,"latitude":40.761635,"longitude":-73.971802,"rawAddress":"1 Main Street, Brooklyn, New York, USA","requiresAction":false,"fields":{"birthday":"1052-04-01","homepage":"https:\/\/www.avengers.com\/profile\/thor"}}}

GET Retrieve Contact

Retrieve information on a specific contact from a given list, identified by Cardly's unique identifier for the record.

Request Parameters

GET /contact-lists/{listId}/contacts/{id}
(No body required)

200 Response Body

A Contact representing the requested contact.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"23fb4b1c-f127-eeea-9f68-6f0a7945da43","externalId":"thor1234","contactListId":"b905e966-ecdf-9656-2564-049c334a4db3","status":"active","firstName":"Thor","lastName":"Odinson","fullName":"Thor Odinson","email":"thor@avengers.com","company":"Avengers Inc.","address":"1 Main Street","address2":null,"locality":"Brooklyn","adminAreaLevel1":"NY","country":"US","postcode":12345,"latitude":40.761635,"longitude":-73.971802,"rawAddress":"1 Main Street, Brooklyn, New York, USA","requiresAction":false,"fields":{"birthday":"1052-04-01","homepage":"https:\/\/www.avengers.com\/profile\/thor"}}}

POST Edit Contact

Edit an existing contact, providing updated information for the contact record.

Request Parameters

Request Body

POST /contact-lists/{listId}/contacts/{id}
{"externalId":"thor1234","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","company":"Avengers Inc.","address":"1 Main Street","address2":"Suite 1451","locality":"Brooklyn","region":"NY","country":"US","postcode":12345,"fields":{"birthday":"1052-04-01","homepage":"https:\/\/www.avengers.com\/profile\/thor"}}

200 Response Body

A Contact representing the contact that was updated.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"23fb4b1c-f127-eeea-9f68-6f0a7945da43","externalId":"thor1234","contactListId":"b905e966-ecdf-9656-2564-049c334a4db3","status":"active","firstName":"Thor","lastName":"Odinson","fullName":"Thor Odinson","email":"thor@avengers.com","company":"Avengers Inc.","address":"1 Main Street","address2":null,"locality":"Brooklyn","adminAreaLevel1":"NY","country":"US","postcode":12345,"latitude":40.761635,"longitude":-73.971802,"rawAddress":"1 Main Street, Brooklyn, New York, USA","requiresAction":false,"fields":{"birthday":"1052-04-01","homepage":"https:\/\/www.avengers.com\/profile\/thor"}}}

DELETE Delete Contact

Delete a contact, disabling any automations linked to it.

Request Parameters

DELETE /contact-lists/{listId}/contacts/{id}
(No body required)

200 Response Body

A Contact representing the contact that was deleted.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"23fb4b1c-f127-eeea-9f68-6f0a7945da43","externalId":"thor1234","contactListId":"b905e966-ecdf-9656-2564-049c334a4db3","status":"active","firstName":"Thor","lastName":"Odinson","fullName":"Thor Odinson","email":"thor@avengers.com","company":"Avengers Inc.","address":"1 Main Street","address2":null,"locality":"Brooklyn","adminAreaLevel1":"NY","country":"US","postcode":12345,"latitude":40.761635,"longitude":-73.971802,"rawAddress":"1 Main Street, Brooklyn, New York, USA","requiresAction":false,"fields":{"birthday":"1052-04-01","homepage":"https:\/\/www.avengers.com\/profile\/thor"}}}

GET Search Contacts

Retrieve information on a specific contact from a given list, searching for the contact by an email address or previously supplied external identifier.

Request Parameters

GET /contact-lists/{listId}/contacts/find
(No body required)

200 Response Body

A Contact representing the requested contact.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"23fb4b1c-f127-eeea-9f68-6f0a7945da43","externalId":"thor1234","contactListId":"b905e966-ecdf-9656-2564-049c334a4db3","status":"active","firstName":"Thor","lastName":"Odinson","fullName":"Thor Odinson","email":"thor@avengers.com","company":"Avengers Inc.","address":"1 Main Street","address2":null,"locality":"Brooklyn","adminAreaLevel1":"NY","country":"US","postcode":12345,"latitude":40.761635,"longitude":-73.971802,"rawAddress":"1 Main Street, Brooklyn, New York, USA","requiresAction":false,"fields":{"birthday":"1052-04-01","homepage":"https:\/\/www.avengers.com\/profile\/thor"}}}

POST Sync Contact

Sync a contact based on an external ID or email address. If a matching contact does not exist, a new one is created, otherwise existing contact records are updated. Previously removed contacts will be reactivated if they match provided details.

Contact matching is performed in order of matching external ID or email address. At least one of these details must be provided, and the first matching contact (if found) is used for update operations.

Request Parameters

Request Body

POST /contact-lists/{listId}/contacts/sync
{"externalId":"thor1234","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","company":"Avengers Inc.","address":"1 Main Street","address2":"Suite 1451","locality":"Brooklyn","region":"NY","country":"US","postcode":12345,"fields":{"birthday":"1052-04-01","homepage":"https:\/\/www.avengers.com\/profile\/thor"}}

200 Response Body

A Contact representing the contact that was updated or created.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"23fb4b1c-f127-eeea-9f68-6f0a7945da43","externalId":"thor1234","contactListId":"b905e966-ecdf-9656-2564-049c334a4db3","status":"active","firstName":"Thor","lastName":"Odinson","fullName":"Thor Odinson","email":"thor@avengers.com","company":"Avengers Inc.","address":"1 Main Street","address2":null,"locality":"Brooklyn","adminAreaLevel1":"NY","country":"US","postcode":12345,"latitude":40.761635,"longitude":-73.971802,"rawAddress":"1 Main Street, Brooklyn, New York, USA","requiresAction":false,"fields":{"birthday":"1052-04-01","homepage":"https:\/\/www.avengers.com\/profile\/thor"}}}

Orders

The orders endpoints provide the ability to generate on-the-fly previews with supplied card data, lodge live orders and query your organisation's order history.

Please note: Once lodged with a live API key, orders are typically difficult to cancel reliably due to our printer partner's schedules. If you have lodged an order in error, please immediately contact the Cardly support team so we can attempt to intervene on your behalf. However, Cardly is unable to make any guarantee on how successful cancelling an order that has gone to print will be.

Order Object

The order object provides detail on a given order on your account, along with individual line item recipient, sender, cost and timing information.

Properties

Order Object Example
{"id":"c988c0c0-f6a3-4e90-bbd5-759497a82607","status":"paid","origin":"api","customer":{"firstName":"Thor","lastName":"Thor","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","email":"thor@avengers.com","purchaseOrderNo":"AVG01145","notes":"Please pack carefully!"},"costs":{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"},"timings":{"created":"2024-12-04 11:11:41","paid":"2024-12-04 11:11:41","updated":"2024-12-04 12:11:46"},"items":[{"id":"60051a2c-86af-45bb-a34f-febf37d9070c","type":"card","media":"51897b27-81d6-e82b-dcfe-36f748d516e9","artwork":"5c40d96b-b7c3-4980-9bdc-14306104ebd4","template":"73bf3d63-5bca-45dc-86f6-d5c01946d78b","label":"Cardly - Happy Birthday","quantity":1,"costs":{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"},"shipTo":"D","shipMethod":"standard","scheduledDate":"2024-12-25","recipient":{"name":"Thor Odinson","company":"Avengers Inc","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","omitAddress":false},"sender":{"name":"Thor Odinson","company":"Avengers Inc","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","omitAddress":false},"delivery":{"requested":"2024-12-25","dispatch":"2024-12-12","estimatedMinArrival":"2024-12-17","estimatedMaxArrival":"2024-12-20"},"timings":{"lodgeAfter":"2024-12-04 11:12:00","lodged":"2024-12-04 11:24:41","shipped":"2024-12-04 12:11:46","held":"2024-12-04 12:06:46"},"tracking":{"carrier":"USPS","code":"056116819325","link":"http:\/\/tracking.usps.com\/consigment\/056116819325"},"related":[{"id":"60051a2c-86af-45bb-a34f-febf37d9070c","type":"card","label":"Cardly - Happy Birthday","quantity":1,"costs":{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"}}]}]}

Order Item Object

The order item object provides detail on a component of a larger order, along with detail related to add-on components to this item (ie, gift cards, additional envelopes).

Properties

Order Item Object Example
{"id":"60051a2c-86af-45bb-a34f-febf37d9070c","type":"card","media":"51897b27-81d6-e82b-dcfe-36f748d516e9","artwork":"5c40d96b-b7c3-4980-9bdc-14306104ebd4","template":"73bf3d63-5bca-45dc-86f6-d5c01946d78b","label":"Cardly - Happy Birthday","quantity":1,"costs":{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"},"shipTo":"D","shipMethod":"standard","scheduledDate":"2024-12-25","recipient":{"name":"Thor Odinson","company":"Avengers Inc","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","omitAddress":false},"sender":{"name":"Thor Odinson","company":"Avengers Inc","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","omitAddress":false},"delivery":{"requested":"2024-12-25","dispatch":"2024-12-12","estimatedMinArrival":"2024-12-17","estimatedMaxArrival":"2024-12-20"},"timings":{"lodgeAfter":"2024-12-04 11:12:00","lodged":"2024-12-04 11:24:41","shipped":"2024-12-04 12:11:46","held":"2024-12-04 12:06:46"},"tracking":{"carrier":"USPS","code":"056116819325","link":"http:\/\/tracking.usps.com\/consigment\/056116819325"},"related":[{"id":"60051a2c-86af-45bb-a34f-febf37d9070c","type":"card","label":"Cardly - Happy Birthday","quantity":1,"costs":{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"}}]}

Style Object

The style object denotes styling options to be applied to a template, card page, or individual element (where applicable). Not all options below have an effect on all elements, however are described here for ease of reference.

Properties

Style Object Example
{"align":"left","color":"1144a7","font":"0d372503-c81b-987d-7636-bd6321290528","size":25,"verticalAlign":"top","writing":"987d50c7-25e1-3b1c-aa78-6f60b1411fe5"}

GET List Orders

Retrieve orders placed by your organisation.

GET /orders
(No body required)

200 Response Body

A paginated array of zero or more Order objects.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"meta":{"orderBy":"name","orderDirection":"asc","startRecord":1,"lastRecord":25,"limit":25,"page":2,"offset":0,"totalRecords":123},"results":[{"id":"c988c0c0-f6a3-4e90-bbd5-759497a82607","status":"paid","origin":"api","customer":{"firstName":"Thor","lastName":"Thor","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","email":"thor@avengers.com","purchaseOrderNo":"AVG01145","notes":"Please pack carefully!"},"costs":{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"},"timings":{"created":"2024-12-04 11:11:41","paid":"2024-12-04 11:11:41","updated":"2024-12-04 12:11:46"},"items":[{"id":"60051a2c-86af-45bb-a34f-febf37d9070c","type":"card","media":"51897b27-81d6-e82b-dcfe-36f748d516e9","artwork":"5c40d96b-b7c3-4980-9bdc-14306104ebd4","template":"73bf3d63-5bca-45dc-86f6-d5c01946d78b","label":"Cardly - Happy Birthday","quantity":1,"costs":{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"},"shipTo":"D","shipMethod":"standard","scheduledDate":"2024-12-25","recipient":{"name":"Thor Odinson","company":"Avengers Inc","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","omitAddress":false},"sender":{"name":"Thor Odinson","company":"Avengers Inc","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","omitAddress":false},"delivery":{"requested":"2024-12-25","dispatch":"2024-12-12","estimatedMinArrival":"2024-12-17","estimatedMaxArrival":"2024-12-20"},"timings":{"lodgeAfter":"2024-12-04 11:12:00","lodged":"2024-12-04 11:24:41","shipped":"2024-12-04 12:11:46","held":"2024-12-04 12:06:46"},"tracking":{"carrier":"USPS","code":"056116819325","link":"http:\/\/tracking.usps.com\/consigment\/056116819325"},"related":[{"id":"60051a2c-86af-45bb-a34f-febf37d9070c","type":"card","label":"Cardly - Happy Birthday","quantity":1,"costs":{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"}}]}]}]}}

GET Retrieve Order

Retrieve information on a specific order.

Request Parameters

GET /orders/{id}
(No body required)

200 Response Body

An Order representing the order that was requested.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"c988c0c0-f6a3-4e90-bbd5-759497a82607","status":"paid","origin":"api","customer":{"firstName":"Thor","lastName":"Thor","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","email":"thor@avengers.com","purchaseOrderNo":"AVG01145","notes":"Please pack carefully!"},"costs":{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"},"timings":{"created":"2024-12-04 11:11:41","paid":"2024-12-04 11:11:41","updated":"2024-12-04 12:11:46"},"items":[{"id":"60051a2c-86af-45bb-a34f-febf37d9070c","type":"card","media":"51897b27-81d6-e82b-dcfe-36f748d516e9","artwork":"5c40d96b-b7c3-4980-9bdc-14306104ebd4","template":"73bf3d63-5bca-45dc-86f6-d5c01946d78b","label":"Cardly - Happy Birthday","quantity":1,"costs":{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"},"shipTo":"D","shipMethod":"standard","scheduledDate":"2024-12-25","recipient":{"name":"Thor Odinson","company":"Avengers Inc","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","omitAddress":false},"sender":{"name":"Thor Odinson","company":"Avengers Inc","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","omitAddress":false},"delivery":{"requested":"2024-12-25","dispatch":"2024-12-12","estimatedMinArrival":"2024-12-17","estimatedMaxArrival":"2024-12-20"},"timings":{"lodgeAfter":"2024-12-04 11:12:00","lodged":"2024-12-04 11:24:41","shipped":"2024-12-04 12:11:46","held":"2024-12-04 12:06:46"},"tracking":{"carrier":"USPS","code":"056116819325","link":"http:\/\/tracking.usps.com\/consigment\/056116819325"},"related":[{"id":"60051a2c-86af-45bb-a34f-febf37d9070c","type":"card","label":"Cardly - Happy Birthday","quantity":1,"costs":{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"}}]}]}}

POST Generate Preview

The preview endpoint allows you to generate a quick, low-quality, watermarked preview document for a given piece of card art and template, along with passed user data. You will also be provided with delivery window estimates and a projected credit cost for the order based on your passed data.

This call is intentionally nearly identical to the PlaceOrder function to facilitate testing and a quick migration to ordering. The main difference between these calls is a PlaceOrder request permits multiple line items with differing data and settings, while Preview deals with only a single card at a time.

Request Body

POST /orders/preview
{"artwork":"happy-birthday","template":"happy-birthday-promo","style":{"align":"left","color":"1144a7","font":"0d372503-c81b-987d-7636-bd6321290528","size":25,"verticalAlign":"top","writing":"987d50c7-25e1-3b1c-aa78-6f60b1411fe5"},"messages":{"pages":[{"page":1,"text":""},{"name":2,"text":"This is the inner left content."},{"name":3,"text":"This is the inner right content.","style":{"color":"1144a7","verticalAlign":"center"}}]},"variables":{"firstName":"Thor","company":"Avengers Inc."},"recipient":{"firstName":"Thor","lastName":"Thor","company":"Avengers Inc","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US"},"sender":{"firstName":"Bruce","lastName":"Banner","company":"Avengers Inc","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","omitAddress":null},"shippingMethod":"standard","shipToMe":false,"requestedArrival":"2024-12-25","purchaseOrderNumber":"PO1234"}

200 Response Body

A description of your current account credit and gift credit balances, along with links to the relevant preview documents for your request.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"balance":203,"giftBalance":{"balance":2064.1,"currency":"USD"},"order":{"creditCost":22.1,"giftCreditCost":56.21,"delivery":{"requested":"2024-12-25","dispatch":"2024-12-12","estimatedMinArrival":"2024-12-17","estimatedMaxArrival":"2024-12-20"}},"preview":{"expires":null,"format":"pdf","urls":{"card":"http:\/\/api.card.ly\/v2\/preview\/4e898074-6a2e-e3fb-9778-518596c36c2a\/card\/pdf","envelope":"http:\/\/api.card.ly\/v2\/preview\/4e898074-6a2e-e3fb-9778-518596c36c2a\/envelope\/pdf"}}}}

POST Place Order

The place endpoint allows you to place an order for one or more items, being delivered to one or more distinct recipients. Generally, we recommend that individual orders are created for individual recipients to minimise potential validation and other rejection issues.

Note that you must have sufficient credit on your account to place your order. If you have insufficient credit, a 402 response will be returned with detail on the required credit cost and your current balance.

Request Body

POST /orders/place
{"lines":[{"artwork":"happy-birthday","template":"happy-birthday-promo","quantity":1,"style":{"align":"left","color":"1144a7","font":"0d372503-c81b-987d-7636-bd6321290528","size":25,"verticalAlign":"top","writing":"987d50c7-25e1-3b1c-aa78-6f60b1411fe5"},"messages":{"pages":[{"page":1,"text":""},{"name":2,"text":"This is the inner left content."},{"name":3,"text":"This is the inner right content.","style":{"color":"1144a7","verticalAlign":"center"}}]},"variables":{"firstName":"Thor","company":"Avengers Inc."},"recipient":{"firstName":"Thor","lastName":"Thor","company":"Avengers Inc","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US"},"sender":{"firstName":"Bruce","lastName":"Banner","company":"Avengers Inc","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","omitAddress":null},"shippingMethod":"standard","shipToMe":false,"requestedArrival":"2024-12-25"}],"purchaseOrderNumber":"PO1234"}

200 Response Body

An Order representing the order that was created.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"balance":203,"giftBalance":{"balance":2064.1,"currency":"USD"},"order":{"id":"c988c0c0-f6a3-4e90-bbd5-759497a82607","status":"paid","origin":"api","customer":{"firstName":"Thor","lastName":"Thor","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","email":"thor@avengers.com","purchaseOrderNo":"AVG01145","notes":"Please pack carefully!"},"costs":{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"},"timings":{"created":"2024-12-04 11:11:41","paid":"2024-12-04 11:11:41","updated":"2024-12-04 12:11:46"},"items":[{"id":"60051a2c-86af-45bb-a34f-febf37d9070c","type":"card","media":"51897b27-81d6-e82b-dcfe-36f748d516e9","artwork":"5c40d96b-b7c3-4980-9bdc-14306104ebd4","template":"73bf3d63-5bca-45dc-86f6-d5c01946d78b","label":"Cardly - Happy Birthday","quantity":1,"costs":{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"},"shipTo":"D","shipMethod":"standard","scheduledDate":"2024-12-25","recipient":{"name":"Thor Odinson","company":"Avengers Inc","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","omitAddress":false},"sender":{"name":"Thor Odinson","company":"Avengers Inc","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","omitAddress":false},"delivery":{"requested":"2024-12-25","dispatch":"2024-12-12","estimatedMinArrival":"2024-12-17","estimatedMaxArrival":"2024-12-20"},"timings":{"lodgeAfter":"2024-12-04 11:12:00","lodged":"2024-12-04 11:24:41","shipped":"2024-12-04 12:11:46","held":"2024-12-04 12:06:46"},"tracking":{"carrier":"USPS","code":"056116819325","link":"http:\/\/tracking.usps.com\/consigment\/056116819325"},"related":[{"id":"60051a2c-86af-45bb-a34f-febf37d9070c","type":"card","label":"Cardly - Happy Birthday","quantity":1,"costs":{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"}}]}]}}}

Invitations

The invitations endpoints provide the ability to create, manipulate and interrogate lists of invitations to access your organisation account.

These allow you to programmatically and on-demand provide access to your account to allow users to send via your portal and use credits (if permitted). Such access is particularly useful for promotions or internal activities, such as penpal and gratitude initiatives.

Invitation Object

The invitation object provides detail on user that's been invited to your account and the status of that invitation.

Properties

Invitation Object Example
{"id":"8d207658-12fc-6068-23fe-09135f7b31f1","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","status":"invited","permissions":{"useCredits":true,"useGiftCredit":true,"useSavedCard":true},"invited":"2022-03-14 12:34:27","inviteSent":"2021-03-14 12:35:53","accepted":null,"expires":"2021-03-17 12:35:01","links":{"accept":"https:\/\/avengers.cardly.net\/invitations\/accept\/8d207658-12fc-6068-23fe-09135f7b31f1\/e167ed69-a05f-1b1c-2bb9-0cf8b73fb57c"}}

GET List Invitations

Retrieve active invitations for your organisation.

This request accepts standard pagination options limit, offset along with the following additional filters:

Request Parameters

GET /invitations
(No body required)

200 Response Body

A paginated array of zero or more Invitation objects.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"meta":{"orderBy":"name","orderDirection":"asc","startRecord":1,"lastRecord":25,"limit":25,"page":2,"offset":0,"totalRecords":123},"results":[{"id":"8d207658-12fc-6068-23fe-09135f7b31f1","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","status":"invited","permissions":{"useCredits":true,"useGiftCredit":true,"useSavedCard":true},"invited":"2022-03-14 12:34:27","inviteSent":"2021-03-14 12:35:53","accepted":null,"expires":"2021-03-17 12:35:01","links":{"accept":"https:\/\/avengers.cardly.net\/invitations\/accept\/8d207658-12fc-6068-23fe-09135f7b31f1\/e167ed69-a05f-1b1c-2bb9-0cf8b73fb57c"}}]}}

POST Create Invitation

Send an invitation to use your organisation portal, if the provided email address doesn't already have access.

Request Body

POST /invitations
{"firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","permissions":["use-credits","use-gift-credits","use-saved-card"]}

200 Response Body

An Invitation representing the invitation that was created.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"8d207658-12fc-6068-23fe-09135f7b31f1","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","status":"invited","permissions":{"useCredits":true,"useGiftCredit":true,"useSavedCard":true},"invited":"2022-03-14 12:34:27","inviteSent":"2021-03-14 12:35:53","accepted":null,"expires":"2021-03-17 12:35:01","links":{"accept":"https:\/\/avengers.cardly.net\/invitations\/accept\/8d207658-12fc-6068-23fe-09135f7b31f1\/e167ed69-a05f-1b1c-2bb9-0cf8b73fb57c"}}}

DELETE Delete Invitation by Email

Delete an invitation by email address, immediately invalidating it for acceptance.

Request Body

DELETE /invitations
{"email":"thor@avengers.com"}

200 Response Body

An Invitation representing the invitation that was deleted.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"8d207658-12fc-6068-23fe-09135f7b31f1","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","status":"invited","permissions":{"useCredits":true,"useGiftCredit":true,"useSavedCard":true},"invited":"2022-03-14 12:34:27","inviteSent":"2021-03-14 12:35:53","accepted":null,"expires":"2021-03-17 12:35:01","links":{"accept":"https:\/\/avengers.cardly.net\/invitations\/accept\/8d207658-12fc-6068-23fe-09135f7b31f1\/e167ed69-a05f-1b1c-2bb9-0cf8b73fb57c"}}}

GET Retrieve Invitation

Retrieve information on a specific invitation, identified by Cardly's unique identifier for the record.

Request Parameters

GET /invitations/{id}
(No body required)

200 Response Body

An Invitation representing the invitation that was located.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"8d207658-12fc-6068-23fe-09135f7b31f1","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","status":"invited","permissions":{"useCredits":true,"useGiftCredit":true,"useSavedCard":true},"invited":"2022-03-14 12:34:27","inviteSent":"2021-03-14 12:35:53","accepted":null,"expires":"2021-03-17 12:35:01","links":{"accept":"https:\/\/avengers.cardly.net\/invitations\/accept\/8d207658-12fc-6068-23fe-09135f7b31f1\/e167ed69-a05f-1b1c-2bb9-0cf8b73fb57c"}}}

DELETE Delete Invitation

Delete an invitation by unique ID address, immediately invalidating it for acceptance.

Request Parameters

DELETE /invitations/{id}
(No body required)

200 Response Body

An Invitation representing the invitation that was deleted.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"8d207658-12fc-6068-23fe-09135f7b31f1","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","status":"invited","permissions":{"useCredits":true,"useGiftCredit":true,"useSavedCard":true},"invited":"2022-03-14 12:34:27","inviteSent":"2021-03-14 12:35:53","accepted":null,"expires":"2021-03-17 12:35:01","links":{"accept":"https:\/\/avengers.cardly.net\/invitations\/accept\/8d207658-12fc-6068-23fe-09135f7b31f1\/e167ed69-a05f-1b1c-2bb9-0cf8b73fb57c"}}}

GET Find Invitation

Retrieve information on a specific invitation, searching by a provided email address.

Request Parameters

GET /invitations/find
(No body required)

200 Response Body

An Invitation representing the invitation that was located.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"8d207658-12fc-6068-23fe-09135f7b31f1","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","status":"invited","permissions":{"useCredits":true,"useGiftCredit":true,"useSavedCard":true},"invited":"2022-03-14 12:34:27","inviteSent":"2021-03-14 12:35:53","accepted":null,"expires":"2021-03-17 12:35:01","links":{"accept":"https:\/\/avengers.cardly.net\/invitations\/accept\/8d207658-12fc-6068-23fe-09135f7b31f1\/e167ed69-a05f-1b1c-2bb9-0cf8b73fb57c"}}}

POST Resend Invitation by Email

Resend an invitation to a specified email address if that invitation has not yet been accepted.

Request Body

POST /invitations/resend
{"email":"thor@avengers.com"}

200 Response Body

An Invitation representing the invitation that was resent.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"8d207658-12fc-6068-23fe-09135f7b31f1","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","status":"invited","permissions":{"useCredits":true,"useGiftCredit":true,"useSavedCard":true},"invited":"2022-03-14 12:34:27","inviteSent":"2021-03-14 12:35:53","accepted":null,"expires":"2021-03-17 12:35:01","links":{"accept":"https:\/\/avengers.cardly.net\/invitations\/accept\/8d207658-12fc-6068-23fe-09135f7b31f1\/e167ed69-a05f-1b1c-2bb9-0cf8b73fb57c"}}}

POST Resend Invitation

Resend an invitation identified by Cardly's unique ID.

Request Parameters

POST /invitations/resend/{id}
(No body required)

200 Response Body

An Invitation representing the invitation that was resent.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"8d207658-12fc-6068-23fe-09135f7b31f1","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","status":"invited","permissions":{"useCredits":true,"useGiftCredit":true,"useSavedCard":true},"invited":"2022-03-14 12:34:27","inviteSent":"2021-03-14 12:35:53","accepted":null,"expires":"2021-03-17 12:35:01","links":{"accept":"https:\/\/avengers.cardly.net\/invitations\/accept\/8d207658-12fc-6068-23fe-09135f7b31f1\/e167ed69-a05f-1b1c-2bb9-0cf8b73fb57c"}}}

Users

The users endpoints provide the ability to interrogate and remove users who have access your organisation account.

These allow you to programmatically and check and remove access to your account as required.

Please note: Access can not be removed for users with administrator privileges on your account. These must be removed via your portal directly.

User Object

The user object provides detail on user has accepted an invitation to use your to your account.

Properties

User Object Example
{"id":"8d207658-12fc-6068-23fe-09135f7b31f1","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","status":"active","permissions":{"administrator":true,"artwork":true,"billing":true,"campaigns":true,"developer":true,"lists":true,"moderate":false,"moderateHistory":false,"orders":true,"templates":true,"users":true,"useCredits":true,"useGiftCredit":true,"useSavedCard":true}}

GET List Users

Retrieve active users for your organisation.

GET /users
(No body required)

200 Response Body

A paginated array of zero or more User objects.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"meta":{"orderBy":"name","orderDirection":"asc","startRecord":1,"lastRecord":25,"limit":25,"page":2,"offset":0,"totalRecords":123},"results":[{"id":"8d207658-12fc-6068-23fe-09135f7b31f1","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","status":"active","permissions":{"administrator":true,"artwork":true,"billing":true,"campaigns":true,"developer":true,"lists":true,"moderate":false,"moderateHistory":false,"orders":true,"templates":true,"users":true,"useCredits":true,"useGiftCredit":true,"useSavedCard":true}}]}}

DELETE Delete User by Email

Delete a user by email address, immediately revoking their access to your organisation portal.

Please note: Access can not be removed for users with administrator privileges on your account. These must be removed via your portal directly.

Request Body

DELETE /users
{"email":"thor@avengers.com"}

200 Response Body

An User representing the user that was deleted.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"8d207658-12fc-6068-23fe-09135f7b31f1","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","status":"active","permissions":{"administrator":true,"artwork":true,"billing":true,"campaigns":true,"developer":true,"lists":true,"moderate":false,"moderateHistory":false,"orders":true,"templates":true,"users":true,"useCredits":true,"useGiftCredit":true,"useSavedCard":true}}}

GET Retrieve User

Retrieve information on a specific user, identified by Cardly's unique identifier for the record.

Request Parameters

GET /users/{id}
(No body required)

200 Response Body

An User representing the user that was located.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"8d207658-12fc-6068-23fe-09135f7b31f1","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","status":"active","permissions":{"administrator":true,"artwork":true,"billing":true,"campaigns":true,"developer":true,"lists":true,"moderate":false,"moderateHistory":false,"orders":true,"templates":true,"users":true,"useCredits":true,"useGiftCredit":true,"useSavedCard":true}}}

DELETE Delete user

Delete a user by unique ID address, immediately revoking their access to your organisation portal.

Please note: Access can not be removed for users with administrator privileges on your account. These must be removed via your portal directly.

Request Parameters

DELETE /users/{id}
(No body required)

200 Response Body

A User representing the invitation that was deleted.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"8d207658-12fc-6068-23fe-09135f7b31f1","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","status":"active","permissions":{"administrator":true,"artwork":true,"billing":true,"campaigns":true,"developer":true,"lists":true,"moderate":false,"moderateHistory":false,"orders":true,"templates":true,"users":true,"useCredits":true,"useGiftCredit":true,"useSavedCard":true}}}

GET Find User

Retrieve information on a specific user, searching by a provided email address.

Request Parameters

GET /users/find
(No body required)

200 Response Body

An User representing the user that was located.

200 Response
{"state":{"status":"OK","messages":[],"version":1181},"data":{"id":"8d207658-12fc-6068-23fe-09135f7b31f1","firstName":"Thor","lastName":"Odinson","email":"thor@avengers.com","status":"active","permissions":{"administrator":true,"artwork":true,"billing":true,"campaigns":true,"developer":true,"lists":true,"moderate":false,"moderateHistory":false,"orders":true,"templates":true,"users":true,"useCredits":true,"useGiftCredit":true,"useSavedCard":true}}}

Object References

Contact List Field

The contact list field object defines additional, custom fields to be applied to all contacts within a list.

Properties

Contact List Field Example
{"id":"9da307a4-1c37-f69a-c6ec-1ba002165d57","code":"dateField","name":"Date Field","description":null,"type":"date","status":"active"}

Contact List Rule

A contact list rule object describes tasks be performed automatically at specified intervals or based on triggers set up in the Cardly platform.

Properties

Contact List Rule Example
{"id":"45702de2-dee0-2b14-ed52-ae63886f28f1","fieldId":"b9763d1b-e0fd-77a3-7afb-6edbf07fe087","cardArt":[{"id":"484ed6af-416e-1f76-7807-c88104734f09","revision":8,"name":"API Artwork Upload","slug":"api-artwork-upload","fullPath":"\/pied-piper\/api-artwork-upload","description":"Testing adding a 4p card via API call.","artwork":["https:\/\/www.cardly.net\/card\/1\/2862abe8-a299-30f2-6324-bd891e687f0d\/page1-r2-i6142-04ebfa87e8f09f1127d6f0c4a27e02c9.png\/vp\/detail-card\/1200",null,"https:\/\/www.cardly.net\/card\/3\/2862abe8-a299-30f2-6324-bd891e687f0d\/page3-r2-i6142-6ea511b3b4d4e99bd41188704026cecc.png\/vp\/detail-card\/1200",null],"media":{"id":"8cdcfaed-ae1c-11ea-8ee1-021187248360","name":"Standard Postcard","description":"Standard postcard for all locales.","creditCost":0.6,"pages":2,"dimensions":{"mm":{"height":105,"width":148}},"bleed":{"mm":{"x":5,"y":5}},"art":{"px":{"innerHeight":1653,"innerWidth":2330,"height":1811,"width":2488}}},"createdAt":"2020-06-14T09:40:09+10:00","updatedAt":"2020-06-14T14:39:35+10:00"}],"templateId":"cddf4ba9-747c-aee9-5373-6d985cbfb198","enabled":true,"name":"Trigger When Number Field Zero","description":null,"operator":"eq","value":0,"annual":true,"bindings":{"name":"birthday","format":null}}

Order Costs Object

Describes the costs of the order as a whole, whether paid by credits or real currency. Note that only credit/giftCredit elements are only present and other fields (gross, discount, etc) are omitted if paid for via credits. The reverse is also true if paid for via real currency - credits/giftCredit fields will be omitted, while the others will be present.

Properties

Order Costs Object Example
{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"}

Order Customer Details Object

Details about the organisation or user that placed this order. For API-originating orders, this will be your organisation details.

Properties

Order Customer Details Object Example
{"firstName":"Thor","lastName":"Thor","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","email":"thor@avengers.com","purchaseOrderNo":"AVG01145","notes":"Please pack carefully!"}

Order Timings Object

Contains details of the overall order creation, update and payment times.

Properties

Order Timings Object Example
{"created":"2024-12-04 11:11:41","paid":"2024-12-04 11:11:41","updated":"2024-12-04 12:11:46"}

Related Item Object

A component of a parent OrderItem, such as an additional envelope or gift card.

Properties

Related Item Object Example
{"id":"60051a2c-86af-45bb-a34f-febf37d9070c","type":"card","label":"Cardly - Happy Birthday","quantity":1,"costs":{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"}}

Order Item Address Object

Describes an addressing element such as sender or recipient or for a given order item.

Properties

Order Item Address Object Example
{"name":"Thor Odinson","company":"Avengers Inc","address":"1 Main Street","address2":"Suite 1054","city":"Brooklyn","region":"NY","postcode":12345,"country":"US","omitAddress":false}

Order Item Costs Object

Describes the costs of an individual line item within an order, whether paid by credits or real currency. Note that only credit/giftCredit elements are only present and other fields (gross, discount, etc) are omitted if paid for via credits. The reverse is also true if paid for via real currency - credits/giftCredit fields will be omitted, while the others will be present.

Properties

Order Item Costs Object Example
{"credits":0.5,"giftCredit":45.67,"gross":6.58,"discount":0.98,"tax":0.69,"shipping":1.54,"shippingTax":0.15,"total":7.98,"currency":"USD"}

Order Item Delivery Details

Describes requested and estimated delivery windows for a given item.

Properties

Order Item Delivery Details Example
{"requested":"2024-12-25","dispatch":"2024-12-12","estimatedMinArrival":"2024-12-17","estimatedMaxArrival":"2024-12-20"}

Order Item Timings Object

Describes various timings within an card's lifecycle, from request to lodgement, production and dispatch.

Properties

Order Item Timings Object Example
{"lodgeAfter":"2024-12-04 11:12:00","lodged":"2024-12-04 11:24:41","shipped":"2024-12-04 12:11:46","held":"2024-12-04 12:06:46"}

Order Item Tracking Object

Describes requested and estimated delivery windows for a given item.

Properties

Order Item Tracking Object Example
{"carrier":"USPS","code":"056116819325","link":"http:\/\/tracking.usps.com\/consigment\/056116819325"}
  • Cardly for Business
  • Disclaimer
  • Privacy Policy
  • Terms & Conditions
Cardly - Keep it Personal