Cardly v2 API

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

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.

We highly recommend checking for the presence of testMode: true to ensure you are not accidentally processing live requests with a testing key.

Attributes
state.status
string

A code to indicate the overall success of the call. One of OK, WARN or ERROR.

state.messages
array

A list of feedback messages to provide more information on a failure, or optionally warnings for successful calls.

data
object

If this call results in any data to be passed back to the caller, the structure will be located here.

Data structures differ per call and are detailed in the relevant API functions below.

Common Return Structure
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        ...
    },
    "testMode": true
}

Errors

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 Code List
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 Parameters
limit
integer

The maximum number of records to return. Minimum: 1, maxium: 100, default: 25.

page
integer

The page of results to retrieve based on the limit parameter.

Result Structure
meta.startRecord
integer

The row number (1-based) of the first record in the result set.

meta.lastRecord
integer

The row number (1-based) of the last record in the result set.

meta.limit
integer

The maximum number of records in this result set.

meta.page
integer

The page number of the results being displayed, based on the specified row limit.

meta.offset
integer

The number of rows offset from the start of this result set.

meta.totalRecords
integer

The total number of results in the entire result set, ignoring pagination limits.

results
array

The list of result records for a given endpoint call.

Request: GET /v2/art?limit=10&offset=20
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 21,
            "lastRecord": 30,
            "limit": 10,
            "offset": 20,
            "totalRecords": 134
        },
        "results": [
            ...
        ]
    }
}

Testing & 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.

Endpoints

/v2/echo

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.

/v2/echo?test=foo
{
    "foo": "bar",
    "array": ["A", "B", "C"]
}
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "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",
            "array": [
                "A",
                "B",
                "C"
            ]
        }
    },
    "testMode": true
}

Account

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

Endpoints

/v2/account/balance

/v2/account/credit-history

/v2/account/gift-credit-history

Credit History Object

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

Attributes
id
UUID

Unique identifier for this credit history entry.

orderId
UUID

Identifier for an order that triggered this credit history entry. Generally used whenever paid transactions take place.

transactionId
UUID

Identifier for a transaction that triggered this credit history entry, typically related to the purchase of credits.

type
string

A human-readable, brief description of what this entry is for, ie; Credit Purchase, Order Placement.

change
float

Value that was either credited or debited from the organisation in this action.

effectiveTime
datetime

Timestamp of when this credit history entry occurred.

Balance History Example
{
    "id": "ef974e61-8496-0de9-446c-ffc21bf7e2e2",
    "orderId": null,
    "transactionId": null,
    "type": "Credit",
    "change": 120,
    "effectiveTime": "2019-11-23 12:10:54"
}

Gift Credit History Object

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

Attributes
id
UUID

Unique identifier for this gift credit history entry.

orderId
UUID

Identifier for an order that triggered this gift credit history entry. Generally used whenever paid transactions take place.

transactionId
UUID

Identifier for a transaction that triggered this gift credit history entry, typically related to the purchase of credits.

type
string

A human-readable, brief description of what this entry is for, ie; Credit Purchase, Order Placement.

change
float

Value that was either credited or debited from the organisation in this action.

changeNet
float

Value that was either credited or debited from the organisation in this action, exclusive of tax.

changeTax
float

Tax component for this transaction, were relevant. Note that currently no region involves taxed gift card payments.

effectiveTime
datetime

Timestamp of when this credit history entry occurred.

Balance History Example
{
    "id": "ef974e61-8496-0de9-446c-ffc21bf7e2e2",
    "orderId": null,
    "transactionId": null,
    "type": "Credit",
    "change": 120,
    "effectiveTime": "2019-11-23 12:10:54"
}

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.

Return
balance
float

Your organisation's current card credit balance. Note that this may not be a whole number.

giftCredit.balance
float

Your organisation's current gift credit balance. Note that this may not be a whole number.

giftCredit.currency
float

The currency your organisation's gift balance is held in.

/v2/account/balance
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "balance": 123,
        "giftCredit": {
            "balance": 145.43,
            "currency": "USD"
        }
    },
    "testMode": true
}

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
effectiveTime.lt
datetime

YYYY-MM-DD HH:ii:ss formatted string to retrieve only results before this time.

effectiveTime.lte
datetime

YYYY-MM-DD HH:ii:ss formatted string to retrieve only results before or equal to this time.

effectiveTime.gt
datetime

YYYY-MM-DD HH:ii:ss formatted string to retrieve only results after this time.

effectiveTime.gte
datetime

YYYY-MM-DD HH:ii:ss formatted string to retrieve only results after or equal to this time.

Return
results
array

A paginated array of zero or more Credit History objects.

/v2/account/credit-history
(No body required)
Response

    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 1,
            "lastRecord": 5,
            "limit": 25,
            "offset": 0,
            "totalRecords": 5
        },
        "results": [
            {
                "id": "484ed6af-416e-1f76-7807-c88104734f09",
                "orderId": null,
                "transactionId": null,
                "type": "Signup Bonus",
                "change": 3,
                "effectiveTime": "2019-11-23 12:10:54"
            },
            ...
        ]
    }
}

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
effectiveTime.lt
datetime

YYYY-MM-DD HH:ii:ss formatted string to retrieve only results before this time.

effectiveTime.lte
datetime

YYYY-MM-DD HH:ii:ss formatted string to retrieve only results before or equal to this time.

effectiveTime.gt
datetime

YYYY-MM-DD HH:ii:ss formatted string to retrieve only results after this time.

effectiveTime.gte
datetime

YYYY-MM-DD HH:ii:ss formatted string to retrieve only results after or equal to this time.

Return
results
array

A paginated array of zero or more Gift Credit History objects.

/v2/account/gift-credit-history
(No body required)
Response

    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 1,
            "lastRecord": 5,
            "limit": 25,
            "offset": 0,
            "totalRecords": 5
        },
        "results": [
            {
                "id": "ee63a362-929b-5cb5-4db2-b7f2b273d39a",
                "orderId": "85658025-f4bb-1af7-bcb6-ddd3078aa9d4",
                "transactionId": null,
                "type": "Debit",
                "typeCode": "D",
                "currency": "AUD",
                "change": -89.34,
                "changeNet": -89.34,
                "changeTax": 0,
                "newBalance": 2064.1,
                "effectiveTime": "2022-07-18 02:26:00",
                "notes": "Payment for order 85658025-f4bb-1af7-bcb6-ddd3078aa9d4 lodged at 18/07/2022 12:26:00"
            },
            ...
        ]
    }
}

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 Place Order and these endpoints can facilitate finding or creating these programatically if required.

Endpoints

/v2/art

/v2/art

/v2/art/{id}

/v2/art/{id}

/v2/art/{id}

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.

Attributes
id
string

Unique identifier for this piece of artwork. To be passed through to Place Order and similar calls requiring artwork IDs.

revision
integer

The revision number of this piece of artwork. Revision increases when artwork descriptors or image assets change.

name
string

The title of this piece of artwork.

slug
string

A search-engine-friendly identifier for this artwork. Can be added to your organisation domain to provide a path to the artwork's page, ie /test-organisation/artwork-slug.

description
string

A longer description of the artwork.

artwork
array

A list of URLs for preview images of each page in the artwork document, without customisations. Any pages without artwork will return null.

media
Media Object

The media size associated with this piece of artwork..

createdAt
datetime

YYYY-MM-DDTHH:ii:ss+00:00 formatted string to denote when this piece of artwork was created.

updatedAt
datetime

YYYY-MM-DDTHH:ii:ss+00:00 formatted string to denote when this piece of artwork was last updated.

Artwork Example
{
    "id": "2862abe8-a299-30f2-6324-bd891e687f0d",
    "revision": 8,
    "name": "API Artwork Upload",
    "slug": "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": {
        ...
    },
    "createdAt": "2020-06-14T09:40:09+10:00",
    "updatedAt": "2020-06-14T14:39:35+10:00"
}

Artwork Listing

Retrieve the currently available artwork for your organisation.

Query Parameters
ownOnly
boolean

If set to a truthy value, results will contain only artwork that belongs to your organisation and no shared or freely available artwork. Defaults to false, showing all artwork.

Return
results
array

A paginated array of zero or more Artwork objects.

/v2/art
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 1,
            "lastRecord": 5,
            "limit": 25,
            "offset": 0,
            "totalRecords": 5
        },
        "results": [
            {
                "id": "2862abe8-a299-30f2-6324-bd891e687f0d",
                "revision": 8,
                "name": "API Artwork Upload",
                "slug": "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": {
                    ...
                },
                "createdAt": "2020-06-14T09:40:09+10:00",
                "updatedAt": "2020-06-14T14:39:35+10:00"
            },
            ...
        ]
    }
}

Get Artwork

Retrieve information on a specific piece of artwork.

Return
(Data Body)
Artwork Object

An artwork object representing the requested piece of artwork..

/v2/art/{id}
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "id": "2862abe8-a299-30f2-6324-bd891e687f0d",
        "revision": 8,
        "name": "API Artwork Upload",
        "slug": "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": {
            ...
        },
        "createdAt": "2020-06-14T09:40:09+10:00",
        "updatedAt": "2020-06-14T14:39:35+10:00"
    }
}

Add Artwork

Add a new piece of artwork.

Request Parameters
media
UUID

UUID for the card size this artwork is for.

name
string

A short description for this artwork.

description
string

A longer human-readable description of the artwork.

artwork
array

A list of pages and associated images to attach to this artwork.

artwork[].page
integer

1-based identifier for the page this artwork file relates to.

artwork[].image
string

Base64 encoded string containing the content of the image file.

Return
(Data Body)
Artwork Object

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

/v2/art
{
    "media": "fd7368b0-ad4d-11ea-9da9-04d4c4254e1b",
    "name": "Awesome Artwork",
    "description": "Featuring large amounts of awesome and things.",
    "artwork": [
        {"page": 1, "image": "iVBORw0KGg..."},
        {"page": 3, "image": "iVBORw0KGg..."}
    ]
}
Response
{
                
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "id": "2862abe8-a299-30f2-6324-bd891e687f0d",
        "revision": 8,
        "name": "API Artwork Upload",
        "slug": "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": {
            ...
        },
        "createdAt": "2020-06-14T09:40:09+10:00",
        "updatedAt": "2020-06-14T14:39:35+10:00"
    }
}

Update Artwork

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

Request Parameters
name
string

A short description for this artwork.

description
string

A longer human-readable description of the artwork.

artwork
array

A list of pages and associated images to attach to this artwork.

artwork[].page
integer

1-based identifier for the page this artwork file relates to.

artwork[].image
string

Base64 encoded string containing the content of the image file.

Return
(Data Body)
Artwork Object

The artwork object representing the artwork that was updated.

/v2/art/{id}
{
    "media": "fd7368b0-ad4d-11ea-9da9-04d4c4254e1b",
    "name": "Awesome Artwork",
    "description": "Featuring large amounts of awesome and things.",
    "artwork": [
        {"page": 1, "image": "iVBORw0KGg..."},
        {"page": 3, "image": "iVBORw0KGg..."}
    ]
}
Response
{
                
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "id": "2862abe8-a299-30f2-6324-bd891e687f0d",
        "revision": 8,
        "name": "API Artwork Upload",
        "slug": "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": {
            ...
        },
        "createdAt": "2020-06-14T09:40:09+10:00",
        "updatedAt": "2020-06-14T14:39:35+10:00"
    }
}

Delete Artwork

Delete a piece of artwork owned by your organisation.

Return
(Data Body)
Artwork Object

The artwork object representing the artwork that was deleted.

/v2/art/{id}
(No body required)
Response
{
                
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "id": "2862abe8-a299-30f2-6324-bd891e687f0d",
        "revision": 8,
        "name": "API Artwork Upload",
        "slug": "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": {
            ...
        },
        "createdAt": "2020-06-14T09:40:09+10:00",
        "updatedAt": "2020-06-14T14:39:35+10:00"
    }
}

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.

Endpoints

/v2/fonts

Font Object

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

Attributes
id
integer

Unique identifier for this font option.

name
string

A localised, human-readable name for this font.

familyVariants
string

The number of font variants this family contains for each character.

canHumanise
boolean

Whether or not this font is marked for being eligible for humanisation techniques. Typically, screen or machine-readable fonts have this flagged off.

restricted
boolean

Whether or not this font is exclusive to your organisation, or freely available across the Cardly platform..

Font Example
{
    "id": "481910d1-ff8c-ee8d-efe5-d5f1b3f9113a",
    "name": "Brad",
    "familyVariants": 3,
    "canHumanise": true,
    "restricted": false
}

Font Listing

Retrieve your currently available fonts.

Request Parameters
organisationOnly
boolean

If truthy, only return fonts that are exclusive to your organisation.

Return
results
array

A paginated array of zero or more Font objects.

/v2/fonts
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 1,
            "lastRecord": 25,
            "limit": 25,
            "offset": 0,
            "totalRecords": 48
        },
        "results": [
            {
                "id": "461910d8-ff8c-ee8d-efe5-d5feb3f9113a",
                "name": "Brad",
                "familyVariants": 3,
                "canHumanise": true,
                "restricted": false
            },
            {
                "id": "1db8e103-1ee3-21c5-1465-d6bfe5d50117",
                "name": "Dawn",
                "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: 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.

Endpoints

/v2/media

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.

Attributes
id
integer

Unique identifier for this media option.

name
string

A localised, human-readable name for this product.

description
string

A longer description of the product, along with any restrictions or important information.

creditCost
float

The number of credits that would be consumed when ordering this media type.

pages
integer

The total number of pages to this product. A standard greeting card is four pages (front, inner left, inner right, back), while a postcard-style product is two pages (front & back).

dimensions.mm.height
dimensions.mm.width
integer

Dimensions of this product in millimeters, exclusive of bleed.

bleed.mm.x
bleed.mm.y
integer

Bleed zone of this product in millimeters, added to the dimensions measurements for the overall page size.

Using the provided example, this would be a 115x158mm product for the purposes of artwork dimensions.

art.px.width
art.px.height
integer

Size of the artwork required for this product, in pixels, inclusive of bleed zones.

Please ensure when providing artwork these bleed zones are accounted for in your supplied imagery.

art.px.innerWidth
art.px.innerHeight
integer

Size of the artwork inner area for this product, in pixels, exclusive of bleed zones. Provided for convenience only, all artwork must contain bleed zones as specified above.

Media Example
{
    "id": 3,
    "name": "Standard Postcard",
    "description": null,
    "creditCost": 0.5,
    "pages": 2,
    "dimensions": {
        "mm": {
            "height": 105,
            "width": 148
        }
    },
    "bleed": {
        "mm": {
            "x": 5,
            "y": 5
        }
    },
    "art": {
        "px": {
            "width": 2488,
            "height": 1811
        }
}

Media Listing

Retrieve the currently available media sizes for product artwork.

Request Parameters
organisationOnly
boolean

If truthy, only return media items that are exclusive to your organisation.

Return
results
array

A paginated array of zero or more Media objects.

/v2/media
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 1,
            "lastRecord": 5,
            "limit": 25,
            "offset": 0,
            "totalRecords": 5
        },
        "results": [
            {
                "id": 4,
                "name": "148 x 202mm Card",
                "description": null,
                "creditCost": 1,
                "pages": 4,
                "dimensions": {
                    "mm": {
                        "height": 148,
                        "width": 111
                    }
                },
                "bleed": {
                    "mm": {
                        "x": 5,
                        "y": 5
                    }
                },
                "art": {
                    "px": {
                        "width": 1905,
                        "height": 2488
                    }
                }
            },
            ...
        ]
    }
}

Templates

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

Endpoints

/v2/templates

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.

Attributes
align
string

One of 'left' (default) or 'center' to denote text flow behaviour.

color
string

RRGGBB hex code (without the hash mark) denoting the colour to use for text or doodle elements.

font
UUID

ID of a font to apply to a text area. Must be either a publically available font or accessible by your organisation.

size
int

A number to control the size of rendered text. Note that the actual rendered size depends on both this and settings build in to your selected font style.

verticalAlign
string

One of 'top' (default), 'center', or 'bottom' to denote where rendered text should sit in relation to the editor page.

writing
UUID

ID of a writing style to apply. Defaults to 'standard' as per the main Cardly editor if not defined.

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

Template Object

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

Attributes
id
UUID

Unique identifier for this template option.

name
string

The human-readable description for this template.

slug
string

A human-readable identifier for this template unique within your organisation.

media
Media Object

The media object that represents the media size associated with this template.

definition.version
integer

The version of the Cardly editor this template was created by.

definition.style
object

The default styles to filter through to pages in this template, if no styles are defined at the page level.

definition.pages[]
array

A list of page objects to define page-level objects (doodles, text areas, gift cards etc) and text data, along with individual page style overrides if applicable.

definition.variables
object

A list of variables associated with this template, where the property name is the variable key and additional description / example data is provided for each variable.

Template Example
{
    "id": "18ecf6e6-d2e2-49cb-bae0-fa980241db73",
    "name": "Happy Birthday",
    "slug": "happy-birthday",
    "media": (Media Object),
    "definition": {
        "version": 2,
        "style": {
            "color": "1144a7",
            "size": 25,
            "writing": "987d50c7-25e1-3b1c-aa78-6f60b1411fe5",
            "font": "0d372503-c81b-987d-7636-bd6321290528"
        },
        "pages": [
            {
                "style": {
                    "align": "left",
                    "color": "1144a7",
                    "size": 25,
                    "writing": "987d50c7-25e1-3b1c-aa78-6f60b1411fe5",
                    "font": "0d372503-c81b-987d-7636-bd6321290528"
                },
                "objects": [],
                "text": {
                    "lines": []
                }
            },
            {
                "style": {
                    "align": "left",
                    "color": "1144a7",
                    "size": 25,
                    "writing": "987d50c7-25e1-3b1c-aa78-6f60b1411fe5",
                    "font": "0d372503-c81b-987d-7636-bd6321290528"
                },
                "objects": [],
                "text": {
                    "lines": []
                }
            }
        ],
        "variables": {
            "firstName": {
                "description": "Customer's first name to display in card front and salutation.",
                "example": "John"
            },
			...
        }
    }
}

Template Listing

Retrieve the currently available templates for this organisation.

Return
results
array

A paginated array of zero or more Template objects.

/v2/templates
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 1,
            "lastRecord": 5,
            "limit": 25,
            "offset": 0,
            "totalRecords": 5
        },
        "results": [
            {
                "id": "18ecf6e6-d2e2-49cb-bae0-fa980241db73",
                "name": "Happy Birthday",
                "slug": "happy-birthday",
                "media": (Media Object),
                "definition": {
                    "version": 2,
                    "style": {
                        "color": "1144a7",
                        "size": 25,
                        "writing": "987d50c7-25e1-3b1c-aa78-6f60b1411fe5",
                        "font": "1d372503-c81b-987d-7636-b16321290528"
                    },
                    "pages": [
                        {
                            "style": {
                                "align": "left",
                                "color": "1144a7",
                                "size": 25,
                                "writing": "987d50c7-25e1-3b1c-aa78-6f60b1411fe5",
                                "font": "1d372503-c81b-987d-7636-b16321290528"
                            },
                            "objects": [],
                            "text": {
                                "lines": []
                            }
                        },
                        {
                            "style": {
                                "align": "left",
                                "color": "1144a7",
                                "size": 25,
                                "writing": "987d50c7-25e1-3b1c-aa78-6f60b1411fe5",
                                "font": "1d372503-c81b-987d-7636-b16321290528"
                            },
                            "objects": [],
                            "text": {
                                "lines": []
                            }
                        }
                    ],
                    "variables": {
                        "firstName": {
                            "description": "Customer's first name to display in card front and salutation.",
                            "example": "John"
                        },
						...
                    }
                }
            },
            ...
        ]
    }
}

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.

Endpoints

/v2/contact-lists

/v2/contact-lists

/v2/contact-lists/{id}

/v2/contact-lists/{id}

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.

Attributes
id
UUID

Unique identifier for this contact list.

name
string

The human-readable name for this list.

description
string

An extended description on what this list is for or related notes, if required.

status
string

The current status of this contact list.

contacts
integer

The number of unique contacts currently in this list.

automations
integer

The number of automation rules (active or disabled) currently applied to this list.

fields
array

List of Contact List Field objects that define additional information to store for each contact in the list.

fields[].id
UUID

A unique identifier for this field which never changes.

fields[].code
string

A human-readable code for this field, based on the field name. These don't change and can be used to reference additional data when syncing contacts.

fields[].name
string

A human-readable label for this field.

fields[].description
string

Extended information about this field, if required.

fields[].type
string

The type of field this is, currently one of text, date or number

fields[].status
string

The status of this field - currently always active.

automations
array

List of Contact List Automation objects that define rules to automatically send cards at specified intervals or based on triggers set up in the Cardly platform.

automations[].id
UUID

A unique identifier for this automation which never changes.

automations[].fieldId
UUID

The field ID linked to this validation rule as a trigger.

automations[].cardArtId
UUID

The card artwork to send based on this trigger.

automations[].templateId
UUID

The template to use for this trigger.

automations[].enabled
boolean

Whether or not this automation is currently enabled for sending.

automations[].name
string

A human-readable name for this automation rule.

automations[].description
string

Extended information on this rule, if required.

automations[].operator
string

The type of comparison (eq, db, da, etc) to apply to the trigger field.

automations[].value
string

The value to compare to in order to evaluate whether the trigger has succeeded or not.

automations[].annual
boolean

If true and linked to a date field, this automation will trigger yearly (ie, for birthday or anniversary type events).

automations[].bindings
object

Key-value mapped object of template variable code to contact list field for injecting data into the final card template.

validation
object

High-level stats around the number of contacts pending / completed validation or requiring manual intervention.

validation.pending
integer

The total number of contacts pending address validation.

validation.requireAction
integer

The total number of contacts requiring manual review of their address data.

validation.validated
integer

The total number of contacts that have completed address validation.

Contact List Example
{
    "id": "6d7c260b-f39f-e822-6aa5-612014047d20",
    "name": "Online Sales",
    "description": null,
    "status": "active",
    "contacts": 0,
    "automations": 0,
    "fields": [
        {
            "id": "9da307a4-1c37-f69a-c6ec-1ba002165d57",
            "code": "dateField",
            "name": "Date Field",
            "description": null,
            "type": "date",
            "status": "active"
        },
        {
            "id": "b9763d1b-e0fd-77a3-7afb-6edbf07fe087",
            "code": "numberField",
            "name": "Number Field",
            "description": null,
            "type": "number",
            "status": "active"
        },
        {
            "id": "17ac0886-87d5-e098-337e-6081a1fa969e",
            "code": "textField",
            "name": "Text Field",
            "description": null,
            "type": "text",
            "status": "active"
        }
    ],
    "rules": [
        {
            "id": "15375e7e-0709-79bc-0db5-f18de014935a",
            "fieldId": "9da307a4-1c37-f69a-c6ec-1ba002165d57",
            "cardArtId": "8fc7bf89-03d1-3d55-9d9e-f3d615c5bb34",
            "templateId": "a8288cf8-689f-4dc3-2fd0-6f6f9c86ecbd",
            "enabled": false,
            "name": "Trigger 30 Days Before",
            "description": null,
            "operator": "db",
            "value": 30,
            "annual": false,
            "bindings": {
                "name": {
                    "binding": "firstName",
                    "format": null
                },
                "variable": {
                    "binding": "fullName",
                    "format": null
                }
            }
        },
        {
            "id": "45702de2-dee0-2b14-ed52-ae63886f28f1",
            "fieldId": "b9763d1b-e0fd-77a3-7afb-6edbf07fe087",
            "cardArtId": "556e4478-a80d-d443-aa78-c11ad19c8d39",
            "templateId": "cddf4ba9-747c-aee9-5373-6d985cbfb198",
            "enabled": true,
            "name": "Trigger When Number Field Zero",
            "description": null,
            "operator": "eq",
            "value": 0,
            "annual": false,
            "bindings": {
                "date": {
                    "binding": "birthday",
                    "format": null
                },
                "name": {
                    "binding": "firstName",
                    "format": null
                },
                "years_as_a_customer": {
                    "binding": "customer_years",
                    "format": null
                }
            }
        }
    ],
    "validation": {
        "pending": 0,
        "requireAction": 0,
        "validated": 0
    }
}

Contact List Listing

Retrieve active contact lists for your organisation.

Return
results
array

A paginated array of zero or more Contact List objects.

/v2/contact-lists
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 1,
            "lastRecord": 8,
            "limit": 25,
            "offset": 0,
            "totalRecords": 8
        },
        "results": [
            {
                "id": "8b6638fc-8d9e-bf53-ac68-2b64030b459a",
                "name": "Contact List #1",
                "description": null,
                "status": "active",
                "contacts": 0,
                "automations": 0,
                "fields": [],
                "rules": [],
                "validation": {
                    "pending": 0,
                    "requireAction": 0,
                    "validated": 0
                }
            },
            {
                "id": "be07acfd-ab65-2818-83e4-9c0c88da6653",
                "name": "Contact List #2",
                "description": "",
                "status": "active",
                "contacts": 0,
                "automations": 2,
                "fields": [
                    {
                        "id": "bba982f4-66ba-4107-edcb-df523b0c2a89",
                        "code": "birthday",
                        "name": "Birthday",
                        "description": null,
                        "type": "date",
                        "status": "active"
                    },
                    {
                        "id": "6b5d32bc-17f3-11eb-8853-04d4c4254e1b",
                        "code": "completionDate",
                        "name": "Completion Date",
                        "description": null,
                        "type": "date",
                        "status": "active"
                    },
                    {
                        "id": "37db15aa-7e76-73c7-89e5-00b56a9c2525",
                        "code": "numericField",
                        "name": "Numeric Field",
                        "description": null,
                        "type": "number",
                        "status": "active"
                    },
                    {
                        "id": "8f45b894-dd24-1139-7292-5b18d5ba23b1",
                        "code": "testField",
                        "name": "Test Field",
                        "description": null,
                        "type": "text",
                        "status": "active"
                    }
                ],
                "rules": [
                    {
                        "id": "15375e7e-0709-79bc-0db5-f18de014935a",
                        "fieldId": "bba982f4-66ba-4107-edcb-df523b0c2a89",
                        "cardArtId": "8fc7bf89-03d1-3d55-9d9e-f3d615c5bb34",
                        "templateId": "a8288cf8-689f-4dc3-2fd0-6f6f9c86ecbd",
                        "enabled": false,
                        "name": "Rule #1",
                        "description": null,
                        "operator": "db",
                        "value": 30,
                        "annual": false,
                        "bindings": {
                            "name": {
                                "binding": "firstName",
                                "format": null
                            },
                            "variable": {
                                "binding": "fullName",
                                "format": null
                            }
                        }
                    },
                    {
                        "id": "45702de2-dee0-2b14-ed52-ae63886f28f1",
                        "fieldId": "37db15aa-7e76-73c7-89e5-00b56a9c2525",
                        "cardArtId": "556e4478-a80d-d443-aa78-c11ad19c8d39",
                        "templateId": "cddf4ba9-747c-aee9-5373-6d985cbfb198",
                        "enabled": true,
                        "name": "Rule #2",
                        "description": null,
                        "operator": "eq",
                        "value": 0,
                        "annual": false,
                        "bindings": {
                            "date": {
                                "binding": "birthday",
                                "format": null
                            },
                            "name": {
                                "binding": "firstName",
                                "format": null
                            },
                            "years_as_a_customer": {
                                "binding": "customer_years",
                                "format": null
                            }
                        }
                    }
                ],
                "validation": {
                    "pending": 0,
                    "requireAction": 0,
                    "validated": 0
                }
            },
            ...
        ]
    }
}

Get Contact List

Retrieve information on a specific contact list.

Return
(Data Body)
Contact List Object

A contact list object representing the requested information.

/v2/contact-lists/{id}
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "id": "6d7c260b-f39f-e822-6aa5-612014047d20",
        "name": "Test Contact List",
        "description": null,
        "status": "active",
        "contacts": 0,
        "automations": 0,
        "fields": [
            {
                "id": "9da307a4-1c37-f69a-c6ec-1ba002165d57",
                "code": "dateField",
                "name": "Date Field",
                "description": null,
                "type": "date",
                "status": "active"
            },
            {
                "id": "b9763d1b-e0fd-77a3-7afb-6edbf07fe087",
                "code": "numberField",
                "name": "Number Field",
                "description": null,
                "type": "number",
                "status": "active"
            },
            {
                "id": "17ac0886-87d5-e098-337e-6081a1fa969e",
                "code": "textField",
                "name": "Text Field",
                "description": null,
                "type": "text",
                "status": "active"
            }
        ],
        "rules": [],
        "validation": {
            "pending": 0,
            "requireAction": 0,
            "validated": 0
        }
    },
    "testMode": true
}

Add Contact List

Add a new contact list, optionally with custom fields.

Request Parameters
name
string

A short description for this contact list to allow it to be identified.

description
string

A free-text description of this list to store whatever additional information might be necesssary.

fields
array

Additional custom fields to add to this list, if required.

fields[].name
string

A short name for this field, which will be used to create a unique field identifier.

fields[].type
string

The type of data this field models, one of text, date, number or url.

fields[].description
string

A longer description of this field, if required.

Return
(Data Body)
Contact List Object

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

/v2/contact-lists
{
    "name": "Employee Birthdays",
    "description": "Current employee birthdays for all staff.",
    "fields": [
        {"name": "Birthday", "type": "date"},
        {"name": "Preferred Name", "type": "text", "description": "The customer's preferred name when we address them."}
    ]
}
Response
{
    "state": {
        "status": "OK",
        "messages": [],
        "version": "1418"
    },
    "data": {
        "id": "2862abe8-a299-30f2-6324-bd891e687f0d",
        "name": "Employee Birthdays",
        "description": "Current employee birthdays for all staff.",
        "status": "active",
        "contacts": 0,
        "automations": 0,
        "fields": [
            {
                "id": "30f2abe8-a299-30f2-6324-bd891e687f0d",
                "code": "birthday",
                "name": "Birthday",
                "description": null,
                "type": "date",
                "status": "active"
            },
            {
                "id": "a299abe8-a299-30f2-6324-bd891e687f0d",
                "code": "preferredName",
                "name": "Preferred Name",
                "description": "The customer's preferred name when we address them.",
                "type": "text",
                "status": "active"
            }
        ],
        "rules": [],
        "validation": {
            "pending": 0,
            "requireAction": 0,
            "validated": 0
        }
    }
}

Edit Contact List

Add a new contact list, optionally with custom fields.

Request Parameters
name
string

A short description for this contact list to allow it to be identified.

description
string

A free-text description of this list to store whatever additional information might be necesssary.

fields
array

Additional custom fields to add or remove from this list, if required. If existing fields are specifed, these fields will be updated or removed as required, otherwise fields will remain unchanged.

fields[].id
string

The identifier of an existing field to update.

fields[].name
string

A short name for this field, which will be used to create a unique field identifier.

Optional if removing a field.

fields[].type
string

The type of data this field models, one of text, date, number or url.

Optional if removing a field.
Ignored if updating an existing field.

fields[].description
string

A longer description of this field, if required.

fields[].remove
boolean

If set to true, removes this field from the list.

Return
(Data Body)
Contact List Object

The contact list object representing the list that was updated.

/v2/contact-lists
{
    "name": "Employee Birthdays",
    "description": "Current employee birthdays for all staff.",
    "fields": [
        {"name": "Birthday", "type": "date"},
        {"name": "Preferred Name", "type": "text", "description": "The customer's preferred name when we address them."}
    ]
}
Response
{
    "state": {
        "status": "OK",
        "messages": [],
        "version": "1418"
    },
    "data": {
        "id": "2862abe8-a299-30f2-6324-bd891e687f0d",
        "name": "Employee Birthdays",
        "description": "Current employee birthdays for all staff.",
        "status": "active",
        "contacts": 0,
        "automations": 0,
        "fields": [
            {
                "id": "30f2abe8-a299-30f2-6324-bd891e687f0d",
                "code": "birthday",
                "name": "Birthday",
                "description": null,
                "type": "date",
                "status": "active"
            },
            {
                "id": "a299abe8-a299-30f2-6324-bd891e687f0d",
                "code": "preferredName",
                "name": "Preferred Name",
                "description": "The customer's preferred name when we address them.",
                "type": "text",
                "status": "active"
            }
        ],
        "rules": [],
        "validation": {
            "pending": 0,
            "requireAction": 0,
            "validated": 0
        }
    }
}

Delete Contact List

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

Return
(Data Body)
Contact List Object

The contact list object representing the list that was deleted.

/v2/contact-lists/{id}
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": [],
        "version": "1418"
    },
    "data": {
        "id": "2862abe8-a299-30f2-6324-bd891e687f0d",
        "name": "Employee Birthdays",
        "description": "Current employee birthdays for all staff.",
        "status": "deleted",
        "contacts": 0,
        "automations": 0,
        "fields": [
            {
                "id": "30f2abe8-a299-30f2-6324-bd891e687f0d",
                "code": "birthday",
                "name": "Birthday",
                "description": null,
                "type": "date",
                "status": "active"
            },
            {
                "id": "a299abe8-a299-30f2-6324-bd891e687f0d",
                "code": "preferredName",
                "name": "Preferred Name",
                "description": "The customer's preferred name when we address them.",
                "type": "text",
                "status": "active"
            }
        ],
        "rules": [],
        "validation": {
            "pending": 0,
            "requireAction": 0,
            "validated": 0
        }
    }
}

Contacts

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

Endpoints

/v2/contact-lists/{listId}/contacts

/v2/contact-lists/{listId}/contacts

/v2/contact-lists/{listId}/contacts/find

/v2/contact-lists/{listId}/contacts/{id}

/v2/contact-lists/{listId}/contacts/{id}

/v2/contact-lists/{listId}/contacts/sync

/v2/contact-lists/{listId}/contacts/delete

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.

Attributes
id
UUID

Unique identifier for this contact.

externalId
string

Any external identifier you have supplied for this contact which can be used to update this contact in future calls.

contactListId
string

Identifier for the contact list this contact belongs to.

status
string

Current state of this contact.

firstName
string

The first name of a contact

lastName
string

The last name of a contact, if supplied

fullName
string

The contact's full name, a combination of firstName & lastName.

email
string

An email address for this contact, if supplied, which can be used to uniquely identify this contact for subsequent actions.

company
string

The company a contact belongs to, if supplied.

address
string

The primary address line.

address2
string

A secondary address line, typically containing a unit, apartment, suite number etc.

locality
string

A suburb or city for the contact.

adminAreaLevel1
string

The state or province for this address.

country
string

A 2-character ISO code identifying the contact's country.

postcode
string

A postal code or ZIP code for this contact, where required by local addressing formats.

latitude
longitude
float

Geo coordinates for this address, if it has been resolved with address lookups.

rawAddress
string

If a full, raw address was supplied for this contact, the original address as supplied by my spreadsheet upload or application.

requiresAction
boolean

If this contact was subject to address validation, whether this record requires manual intervention to resolve.

fields
object

Additional custom fields based on field codes for extended data on this contact record.

Contact List 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": null,
    "longitude": null,
    "rawAddress": null,
    "requiresAction": false,
    "fields": {
        "dateField": "1052-04-01",
        "urlField": "https://www.avengers.com/profile/thor"
    }
}

Contact Listing

Retrieve active contacts in a given list.

Return
results
array

A paginated array of zero or more Contact objects.

/v2/contact-lists/{listId}/contacts
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 1,
            "lastRecord": 25,
            "limit": 25,
            "offset": 0,
            "totalRecords": 851
        },
        "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": null,
                "longitude": null,
                "rawAddress": null,
                "requiresAction": false,
                "fields": {
                    "dateField": "1052-04-01",
                    "urlField": "https://www.avengers.com/profile/thor"
                }
            },
            ...
        ]
    }
}

Get Contact

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

Return
(Data Body)
Contact Object

A contact object representing the requested information.

/v2/contact-lists/{listId}/contacts/{id}
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "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": null,
        "longitude": null,
        "rawAddress": null,
        "requiresAction": false,
        "fields": {
            "dateField": "1052-04-01",
            "urlField": "https://www.avengers.com/profile/thor"
        }
    }
}

Find Contact

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
query
string

An email address or external identifier to locate a contact by within the given list.

Return
(Data Body)
Contact Object

A contact object representing the requested information.

/v2/contact-lists/{listId}/contacts/find
?query=thor@avengers.com
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "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": null,
        "longitude": null,
        "rawAddress": null,
        "requiresAction": false,
        "fields": {
            "dateField": "1052-04-01",
            "urlField": "https://www.avengers.com/profile/thor"
        }
    }
}

Add 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
externalId
string

Any external identifier you have supplied for this contact which can be used to update this contact in future calls.

firstName
string

The first name of a contact

lastName
string

The last name of a contact, if supplied

email
string

An email address for this contact, if supplied, which can be used to uniquely identify this contact for subsequent actions.

company
string

The company a contact belongs to, if supplied.

address
string

The primary address line.

address2
string

A secondary address line, typically containing a unit, apartment, suite number etc.

locality
string

A suburb or city for the contact.

region
string

The state or province for this address. Conditionally required based on the country supplied.

country
string

A 2-character ISO code identifying the contact's country.

postcode
string

A postal code or ZIP code for this contact, where required by local addressing formats. Conditionally required based on the country supplied.

fields
object

Additional custom fields based on field codes for extended data on this contact record.

fields[fieldId]
string

For each custom field in your list, fields may be specified based on the unique field ID created by Cardly.

Fields will be subject to data type checking where appropriate:

  • URL Fields require full, complete URLs supplied, if used.
  • Number Fields require any numeric string, free of any human readable formatting (ie, commas for thousands separators).
Return
(Data Body)
Contact Object

An object representing the contact that was just created. Use the ID property from this to feed into further requests as needed.

/v2/contact-lists/{listId}/contacts
{
    "externalId": "thor1234",
    "firstName": "Thor",
    "lastName": "Odinson",
    "email": "thor@avengers.com",
    "company": "Avengers Inc.",
    "address": "1 Main Street",
    "locality": "Brooklyn",
    "adminAreaLevel1": "NY",
    "country": "US",
    "postcode": "12345",
    "fields": {
        "e7000b81-332e-612f-6098-8ff8af04f1bb": "1052-04-01",
        "6098b81-332e-612f-e7000-8ff8af04f1bb": "https://www.avengers.com/profile/thor"
    }
}
Response
{
    "state": {
        "status": "OK",
        "messages": [],
        "version": "1418"
    },
    "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": null,
        "longitude": null,
        "rawAddress": null,
        "requiresAction": false,
        "fields": {
            "dateField": "1052-04-01",
            "urlField": "https://www.avengers.com/profile/thor"
        }
    }
}

Edit Contact

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

Request Parameters
externalId
string

Any external identifier you have supplied for this contact which can be used to update this contact in future calls.

firstName
string

The first name of a contact

lastName
string

The last name of a contact, if supplied

email
string

An email address for this contact, if supplied, which can be used to uniquely identify this contact for subsequent actions.

company
string

The company a contact belongs to, if supplied.

address
string

The primary address line.

address2
string

A secondary address line, typically containing a unit, apartment, suite number etc.

locality
string

A suburb or city for the contact.

region
string

The state or province for this address. Conditionally required based on the country supplied.

country
string

A 2-character ISO code identifying the contact's country.

postcode
string

A postal code or ZIP code for this contact, where required by local addressing formats. Conditionally required based on the country supplied.

fields
object

Additional custom fields based on field codes for extended data on this contact record.

fields[fieldId]
string

For each custom field in your list, fields may be specified based on the unique field ID created by Cardly.

Fields will be subject to data type checking where appropriate:

  • URL Fields require full, complete URLs supplied, if used.
  • Number Fields require any numeric string, free of any human readable formatting (ie, commas for thousands separators).
Return
(Data Body)
Contact Object

An object representing the contact that was just updated.

/v2/contact-lists/{listId}/contacts/{id}
{
    "externalId": "thor1234",
    "firstName": "Thor",
    "lastName": "Odinson",
    "email": "thor@avengers.com",
    "company": "Avengers Inc.",
    "address": "1 Main Street",
    "locality": "Brooklyn",
    "adminAreaLevel1": "NY",
    "country": "US",
    "postcode": "12345",
    "fields": {
        "e7000b81-332e-612f-6098-8ff8af04f1bb": "1052-04-01",
        "6098b81-332e-612f-e7000-8ff8af04f1bb": "https://www.avengers.com/profile/thor"
    }
}
Response
{
    "state": {
        "status": "OK",
        "messages": [],
        "version": "1418"
    },
    "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": null,
        "longitude": null,
        "rawAddress": null,
        "requiresAction": false,
        "fields": {
            "dateField": "1052-04-01",
            "urlField": "https://www.avengers.com/profile/thor"
        }
    }
}

Sync Contact

Sync a contact based on a provided ID, 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 Cardly ID, 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
externalId
string

Any external identifier you have supplied for this contact which can be used to update this contact in future calls, or identify this contact in this call.

firstName
string

The first name of a contact

lastName
string

The last name of a contact, if supplied

email
string

An email address for this contact, if supplied, which can be used to uniquely identify this contact for subsequent actions, or identify this contact in this call.

company
string

The company a contact belongs to, if supplied.

address
string

The primary address line.

address2
string

A secondary address line, typically containing a unit, apartment, suite number etc.

locality
string

A suburb or city for the contact.

region
string

The state or province for this address. Conditionally required based on the country supplied.

country
string

A 2-character ISO code identifying the contact's country.

postcode
string

A postal code or ZIP code for this contact, where required by local addressing formats. Conditionally required based on the country supplied.

fields
object

Additional custom fields based on field codes for extended data on this contact record.

fields[fieldId]
string

For each custom field in your list, fields may be specified based on the unique field ID created by Cardly.

Fields will be subject to data type checking where appropriate:

  • URL Fields require full, complete URLs supplied, if used.
  • Number Fields require any numeric string, free of any human readable formatting (ie, commas for thousands separators).
Return
(Data Body)
Contact Object

An object representing the contact that was just updated.

/v2/contact-lists/{listId}/contacts/sync/{id?}
{
    "externalId": "thor1234",
    "firstName": "Thor",
    "lastName": "Odinson",
    "email": "thor@avengers.com",
    "company": "Avengers Inc.",
    "address": "1 Main Street",
    "locality": "Brooklyn",
    "adminAreaLevel1": "NY",
    "country": "US",
    "postcode": "12345",
    "fields": {
        "e7000b81-332e-612f-6098-8ff8af04f1bb": "1052-04-01",
        "6098b81-332e-612f-e7000-8ff8af04f1bb": "https://www.avengers.com/profile/thor"
    }
}
Response
{
    "state": {
        "status": "OK",
        "messages": [],
        "version": "1418"
    },
    "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": null,
        "longitude": null,
        "rawAddress": null,
        "requiresAction": false,
        "fields": {
            "dateField": "1052-04-01",
            "urlField": "https://www.avengers.com/profile/thor"
        }
    }
}

Delete Contact

Delete a contact, disabling any automations linked to it.

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

Request Parameters
externalId
string

Any external identifier to identify the contact to delete with, if no email address or Cardly ID is supplied.

email
string

An email address to identify the contact to delete with, if no external ID or Cardly ID is supplied.

Return
(Data Body)
Contact Object

The contact object representing the contact that was deleted.

/v2/contact-lists/{listId}/contacts/{id?}
{
    "externalId": "thor1234",
    "email": "thor@avengers.com"
}
Response
{
    "state": {
        "status": "OK",
        "messages": [],
        "version": "1418"
    },
    "data": {
        "id": "23fb4b1c-f127-eeea-9f68-6f0a7945da43",
        "externalId": "thor1234",
        "contactListId": "b905e966-ecdf-9656-2564-049c334a4db3",
        "status": "deleted",
        "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": null,
        "longitude": null,
        "rawAddress": null,
        "requiresAction": false,
        "fields": {
            "dateField": "1052-04-01",
            "urlField": "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.

Endpoints

/v2/orders

/v2/orders/{id}

/v2/orders/preview

/v2/orders/place

Order Object

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

Attributes
id
UUID

Unique identifier for this order.

status
string

The current status of this order.

origin
string

Where the order originate - via the API, your organisation portal, etc.

customer
object

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

costs.credits
float

The total credits this order consumed, if paid by credits.

costs.giftCredit
float

The total gift credits this order consumed, if paid by credits.

costs.gross
float

The gross cost of this order, exclusive of tax.

costs.discount
float

The discount amount for this order overall.

costs.tax
float

The total amount of tax on this order, exclusive of shipping.

costs.shipping
float

The total tax-exclusive cost of shipping for this order.

costs.shippingTax
float

The total amount of tax applied to shipping.

costs.total
float

The total cost of this order.

costs.currency
string

The currency this order was priced in.

timings.paid
datetime

When this order was paid - if it is paid.

timings.created
datetime

When this order was first raised.

timings.updated
datetime

When this order was last updated.

items
array

List of Order Item objects that comprise this order.

Order Example
{
    "id": "c988c0c0-f6a3-4e90-bbd5-759497a82607",
    "status": "paid",
    "origin": "api",
    "description": null,
    "customer": {
        "firstName": "Cardly Pty Ltd",
        "lastName": null,
        "address": "10 Another Lane",
        "address2": null,
        "city": "Brisbane",
        "region": "QLD",
        "postcode": "4000",
        "country": "AU"
    },
    "costs": {
        "credits": 0.53,
        "giftCredit": 50
    },
    "timings": {
        "paid": "2019-12-04 12:06:46",
        "created": "2019-12-04 12:06:46",
        "updated": "2019-12-04 12:06:46"
    },
    "items": [
        {
            "id": "60051a2c-86af-45bb-a34f-febf37d9070c",
            "type": "card",
            "label": "Cardly - Happy Birthday",
            "quantity": 1,
            "costs": {
                "credits": 0.5,
                "giftCredit": 0
            },
            "shipTo": "S",
            "shipMethod": "standard",
            "scheduledDate": "2019-12-25 00:00:00",
            "recipient": {
                "address": "10 Somewhere Place",
                "address2": "",
                "city": "Fairyland",
                "region": "QLD",
                "postcode": "4110",
                "country": "AU"
            },
            "sender": {
                "name": "Cardly",
                "address": "10 Another Lane",
                "address2": null,
                "city": "Brisbane",
                "region": "QLD",
                "postcode": "4000",
                "country": "AU",
                "omitAddress": false
            },
            "timings": {
                "lodgeAfter": "2019-12-04 12:06:46",
                "shipped": null,
                "lodged": null,
                "held": null
            },
            "delivery": {
                "requested": "2019-12-25",
                "dispatch": "2019-12-12",
                "estimatedMinArrival": "2019-12-17",
                "estimatedMaxArrival": "2019-12-20"
            },
            "media": 3,
            "artwork": "5c40d96b-b7c3-4980-9bdc-14306104ebd4",
            "template": "73bf3d63-5bca-45dc-86f6-d5c01946d78b",
            "related": [
                {
                    "id": "3ae265f0-0f63-4018-a0a1-c26d31a3179f",
                    "type": "envelope",
                    "label": "Additional envelope",
                    "quantity": 1,
                    "costs": {
                        "credits": 0.03,
                        "giftCredit": 0
                    },
                    "related": []
                },
                {
                    "id": "51897b27-81d6-e82b-dcfe-36f748d516e9",
                    "type": "gift-card",
                    "label": "Gift Card: Amazon Gift Card Card for $50",
                    "quantity": 1,
                    "costs": {
                        "credits": 0,
                        "giftCredit": 50
                    },
                    "related": []
                }
            ]
        }
    ]
}

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).

Attributes
id
UUID

Unique identifier for this order item.

type
string

The type of item this is - typically card.

label
string

A description of this item, typically the card artwork title.

quantity
integer

The number of units of this item that were ordered.

costs.credits
float

The total credits this order consumed, if paid by credits.

costs.gross
float

The gross unit cost of this item, exclusive of tax.

costs.discount
float

The discount amount per unit for this item.

costs.tax
float

The amount of tax per unit on this item, exclusive of shipping.

costs.shipping
float

The per-unit tax-exclusive cost of shipping for this item.

costs.shippingTax
float

The amount per unit of tax applied to shipping.

costs.total
float

The total line cost for the entire quantity requested of this item.

costs.currency
string

The currency this item was priced in.

shipTo
string

Either S for shipping back to the sender, or D for shipping direct to the customer.

shipMethod
string

The shipping method used, either standard, priority or express.

scheduledDate
date

If requested at order time, the date this item was requested to arrive by.

recipient
object

The address details for the recipient of this item.

sender
object

The address details for the sender of this item.

timings.lodgeAfter
datetime

The scheduled time for sending this item to print. Lodgement will always occur after this time.

timings.lodged
datetime

When this item was sent to print.

timings.shipped
datetime

When this item was shipped. Please note: we rely on external data to populate this and it may not always be immediately available.

timings.held
datetime

If this item is being held, the time the item was marked for holding.

delivery.requested
date

The arrival date requested, if applicable. This will be null where you did not specify a requested delivery date.

delivery.dispatch
date

The date an order will be sent to print, either today if no requested delivery date is specified, or a date calculated from the maximum delivery window time for your selected shipping method.

delivery.estimatedMinArrival
date

The estimated earliest date an order should be received. Note that this is subject to end postal carriers and beyond the control of Cardly directly.

delivery.estimatedMaxArrival
date

The estimated latest date an order should be received. Note that this is subject to end postal carriers and beyond the control of Cardly directly.

media
integer

Identifier for the media type used for this item.

artwork
UUID

Identifier for the artwork used for this item.

template
UUID

Identifier for the template used to populate this item, if applicable.

related
array

Zero or more Order Item objects directly related to this one - additional envelopes, gift cards, etc.

tracking.carrier
string

The name of the carrier for orders with tracking.

tracking.code
string

The tracking code provided by the carrier for a given consignment.

tracking.link
string

Carrier's URL where applicable to view tracking information for this consignment.

Order Item Example
{
    "id": "60051a2c-86af-45bb-a34f-febf37d9070c",
    "type": "card",
    "label": "Cardly - Happy Birthday",
    "quantity": 1,
    "costs": {
        "credits": 0.5,
        "giftCredit": 50
    },
    "shipTo": "S",
    "shipMethod": "standard",
    "scheduledDate": "2019-12-25",
    "recipient": {
        "address": "10 Somewhere Place",
        "address2": "",
        "city": "Fairyland",
        "region": "QLD",
        "postcode": "4110",
        "country": "AU"
    },
    "sender": {
        "name": "Cardly",
        "address": "10 Another Lane",
        "address2": null,
        "city": "Brisbane",
        "region": "QLD",
        "postcode": "4000",
        "country": "AU",
        "omitAddress": false
    },
    "timings": {
        "lodgeAfter": "2019-12-04 12:06:46",
        "shipped": null,
        "lodged": null,
        "held": null
    },
    "delivery": {
        "requested": "2019-12-25",
        "dispatch": "2019-12-12",
        "estimatedMinArrival": "2019-12-17",
        "estimatedMaxArrival": "2019-12-20"
    },
    "media": 3,
    "artwork": "5c40d96b-b7c3-4980-9bdc-14306104ebd4",
    "template": "73bf3d63-5bca-45dc-86f6-d5c01946d78b",
    "related": [
        {
            "id": "3ae265f0-0f63-4018-a0a1-c26d31a3179f",
            "type": "envelope",
            "label": "Additional envelope",
            "quantity": 1,
            "costs": {
                "credits": 0.03,
                "giftCredit": 0
            },
            "related": []
        },
        {
            "id": "51897b27-81d6-e82b-dcfe-36f748d516e9",
            "type": "gift-card",
            "label": "Gift Card: Amazon Gift Card Card for $50",
            "quantity": 1,
            "costs": {
                "credits": 0,
                "giftCredit": 50
            },
            "related": []
        }
    ]
}

Order Listing

Retrieve orders placed by your organisation.

Return
results
array

A paginated array of zero or more Order objects.

/v2/orders
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 1,
            "lastRecord": 5,
            "limit": 25,
            "offset": 0,
            "totalRecords": 5
        },
        "results": [
            {
                "id": "cdb75194-c03b-1bab-e390-47853b1dba08",
                "status": "Paid",
                "origin": "api",
                "description": null,
                "customer": {
                    "firstName": "John",
                    "lastName": "Doe",
                    "address": "10 Somewhere Place",
                    "address2": null,
                    "city": "Fairyland",
                    "region": "QLD",
                    "country": "AU",
                    "postcode": "4110",
                    "email": "someone@somewhere.com",
                    "purchaseOrderNo": null,
                    "notes": null
                },
                "costs": {
                    "credits": 1.0
                },
                "timings": {
                    "paid": "2019-12-17 15:03:57",
                    "created": "2019-12-17 15:03:56",
                    "updated": "2019-12-17 15:03:57"
                },
                "items": [
                    {
                        "id": "5651b520-5565-9a55-0045-c20ca338b114",
                        "type": "card",
                        "label": "Test Artwork",
                        "quantity": 1,
                        "costs": {
                            "credits": 1.0
                        },
                        ...
                    }
                ]
            },
            ...
        ]
    }
}

Get Order

Retrieve information on a specific order.

Return
(Data Body)
Order Object

An order object representing the requested order information.

/v2/orders/{id}
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "id": "cdb75194-c03b-1bab-e390-47853b1dba08",
        "status": "Paid",
        "origin": "api",
        "description": null,
        "customer": {
            "firstName": "John",
            "lastName": "Doe",
            "address": "10 Somewhere Place",
            "address2": null,
            "city": "Fairyland",
            "region": "QLD",
            "country": "AU",
            "postcode": "4110",
            "email": "someone@somewhere.com",
            "purchaseOrderNo": null,
            "notes": null
        },
        "costs": {
            "credits": 1.0
        },
        "timings": {
            "paid": "2019-12-17 15:03:57",
            "created": "2019-12-17 15:03:56",
            "updated": "2019-12-17 15:03:57"
        },
        "items": [
            {
                "id": "5651b520-5565-9a55-0045-c20ca338b114",
                "type": "card",
                "label": "Test Artwork",
                "quantity": 1,
                "costs": {
                    "credits": 1.0
                },
                "shipTo": "D",
                "shipMethod": "express",
                "scheduledDate": null,
                "recipient": {
                    "name": "Jane Doe",
                    "address": "20 Somewhere Drive",
                    "address2": null,
                    "city": "Fairyland",
                    "region": "",
                    "country": "AU",
                    "postcode": "4110"
                },
                "sender": {
                    "name": "John Doe",
                    "address": "10 Somewhere Place",
                    "address2": null,
                    "city": "Fairyland",
                    "region": "QLD",
                    "country": "AU",
                    "postcode": "4110"
                },
                "timings": {
                    "lodgeAfter": "2019-12-17 15:03:56",
                    "shipped": null,
                    "lodged": null,
                    "held": null
                },
                "delivery": {
                    "requested": null,
                    "dispatch": "2019-12-17",
                    "estimatedMinArrival": "2019-12-20",
                    "estimatedMaxArrival": "2019-12-30"
                },
                "media": "1708fe20-ad4e-11ea-9da9-04d4c4254e1b",
                "artwork": "b6623a6c-36c7-af45-e0d9-c90d6e0f0333",
                "template": "19ecf6e6-d2e2-59cb-bce0-fa980241db73",
                "related": [],
                "tracking": {
                    "carrier": "Australia Post",
                    "code": "123456789",
                    "link": "https://auspost.com.au/mypost/track/#/details/123456789"
                }
            }
        ]
    }
}

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 Place Order function to facilitate testing and a quick migration to ordering. The main difference between these calls is a Place Order request permits multiple line items with differing data and settings, while the Generate Preview deals with only a single card at a time.

Request Parameters
artwork
string

The unique artwork ID to use for this card. This may be the UUID or slug for a given piece of artwork under your organisation.

template
string

The template ID to use top populate this card. If no template is specified, only the main text panels on the card will be utilised and no variable substitutions will occur.

style
Style Object

Styles to apply to act as defaults for the whole card. This does not need to define all style object elements, only those you wish to override from a used template or default styles.

Please note: If you have specified a template, the style element will override any properties the template has set as defaults.

messages.pages[].page
integer

Numeric identifier for the page the rest of this element's settings apply to. This is a one-based numbering of card pages - front cover is 1, inside left is 2, etc.

messages.pages[].style
Style Object

Styles to apply to the main text block on this page. This does not need to define all style object elements, only those you wish to override from a used template or default styles.

Please note: If you have specified a template, the style element will override any properties the template has set for this page. Currently, only align and verticalAlign properties have an effect at a page level.

messages.pages[].text
string

The main panel text to use for a given page. Note that this will only be utilised if the media supports placing text on this page. Most four page cards will restrict front/back panels to artwork only, while postcards typically accept only content for the back panel.

Please note: If you have specified a template, the messages element will be ignored entirely in favor of the template's text.

variables[].(property)
string

Zero or more variables to inject into a template, based on the variables supported by that template. This is a key => value mapped object based on the variables to use in the template.

recipient.firstName
string

The recipient's first name, as it should appear on the envelope.

recipient.lastName
string

The recipient's last name, as it should appear on the envelope.

recipient.company
string

The recipient's company, if required, as it should appear below their name on the envelope.

recipient.address
string

The recipient's street number, name and type, ie. 10 Somewhere Lane

recipient.address2
string

Unit, floor, apartment etc. additional information for the recipient's address.

recipient.city
string

Suburb or city for the recipient.

recipient.region
string

State / province / region for the recipient, if required. UK and NZ currently do not require a region specified.

recipient.postcode
string

Postcode for the recipient.

recipient.country
string

2-character ISO code for the country to ship to.

sender.firstName
string

The sender's first name, as it should appear on the envelope.

Please note: the entire sender section is optional and will default to your organisation's return details if not completed. If any sender element is specified, all must be specified.

sender.lastName
string

The sender's last name, as it should appear on the envelope.

sender.address
string

The sender's street number, name and type, ie. 10 Somewhere Lane

sender.address2
string

Unit, floor, apartment etc. additional information for the sender's address.

sender.city
string

Suburb or city for the sender.

sender.region
string

State / province / region for the sender, if required. UK and NZ currently do not require a region specified.

sender.postcode
string

Postcode for the sender.

sender.country
string

2-character ISO code for the country to use for the return address..

sender.omitAddress
boolean

If true, the sender's address will not appear on envelopes.

shippingMethod
string

The shipping method to use. Note that shipping method support is on a per-region basis, but all regions will at minimum support the standard shipping method.

Currently, only Australia supports the additional priority shipping method.

shipToMe
boolean

If set to true, denotes that the recipient of this card is also the sender and to include an additional, blank envelope. Note that this incurs a small additional credit cost.

requestedArrival
date

A future requested arrival date for this card. In a preview request, this will provide a basis for shipping window estimates to be returned. If not specified, immediate dispatch is assumed and dates will be calculated based on the current date.

purchaseOrderNumber
string

A purchase order or other identifier to store against the order. Note that this has no bearing on a preview, unless there is an template variable that accepts this value.

Return
balance
float

Your organisation's current credit balance. Note that this may not be a whole number.

giftCredit
object

Your organisation's current gift credit balance.

order.creditCost
float

The number of credits this order costs based on the selected media size, post option and any additional options such as 'send to me' requiring additional envelopes.

order.giftCreditCost
float

The amount of gift credit this order costs based on any included gifts.

order.delivery.requested
date

The arrival date requested, if applicable. This will be null where you did not specify a requested delivery date.

order.delivery.dispatch
date

The date an order will be sent to print, either today if no requested delivery date is specified, or a date calculated from the maximum delivery window time for your selected shipping method.

order.delivery.estimatedMinArrival
date

The estimated earliest date an order should be received. Note that this is subject to end postal carriers and beyond the control of Cardly directly.

order.delivery.estimatedMaxArrival
date

The estimated latest date an order should be received. Note that this is subject to end postal carriers and beyond the control of Cardly directly.

preview.expires
datetime

Timestamp of when this preview will be removed from Cardly's systems. Ensure the preview URLs are accessed prior to this time.

preview.format
string

The file format for the preview. Currently only PDF previews are generated.

preview.urls.format
string

URL to the card artwork preview document. This URL does not require authentication and can be retrieved with a standard GET request.

preview.urls.envelope
string

URL to the envelope artwork preview, if applicable. Some products such as postcards do not require envelopes, so this value will be null in those cases. This URL does not require authentication and can be retrieved with a standard GET request.

/v2/orders/preview
{
    "artwork": "happy-birthday",
    "template": "happy-birthday-promo",
    "messages": {
        "pages": [
            {
                "page": 1,
                "text": ""
            },
            {
                "page": 2,
                "text": ""
            },
            {
                "page": 3,
                "text": "",
                "style": {
                    "color": "1144a7",
                    "verticalAlign": "center"
                }
            }
        ]
    },
    "variables": {
        "firstName": "John",
        "message": "Happy birthday from the Cardly team, we hope you have a great one!",
    },
    "recipient": {
        "firstName": "John",
        "lastName": "Doe",
        "address": "10 Somewhere Place",
        "address2": "",
        "city": "Fairyland",
        "region": "QLD",
        "postcode": "4110",
        "country": "AU"
    },
    "sender": {
        "firstName": "Cardly Pty Ltd",
        "lastName": "",
        "address": "10 Another Lane",
        "city": "Brisbane",
        "region": "QLD",
        "postcode": "4000",
        "country": "AU"
    },
    "shippingMethod": "standard",
    "shipToMe": false,
    "requestedArrival": "2019-12-25",
    "purchaseOrderNumber": "123ABC"
}
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "balance": 123,
        "giftCredit": {
            "balance": 2064.1,
            "currency": "AUD"
        },
        "order": {
            "creditCost": 0.5,
            "giftCreditCost": 50,
            "delivery": [
                {
                    "requested": "2019-12-25",
                    "dispatch": "2019-12-12",
                    "estimatedMinArrival": "2019-12-17",
                    "estimatedMaxArrival": "2019-12-20"
                }
            ]
        },
        "preview": {
            "expires": "2019-12-10 23:11:38",
            "format": "pdf",
            "urls": {
                "card": "http://api.card.ly/v2/preview/4e898074-6a2e-e3fb-9778-518596c36c2a/card/pdf",
                "envelope": null
            }
        }
    }
}

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 Parameters
purchaseOrderNumber
string

A reference number to place against this order - useful to tie back to your existing systems for auditing.

lines
array

A list of one or more of the below Order Item structures to include into the overall order.

Order Item Structure
artwork
string

The unique artwork ID to use for this card. This may be the UUID or slug for a given piece of artwork under your organisation.

template
string

The template ID to use top populate this card. If no template is specified, only the main text panels on the card will be utilised and no variable substitutions will occur.

style
Style Object

Styles to apply to act as defaults for the whole card. This does not need to define all style object elements, only those you wish to override from a used template or default styles.

Please note: If you have specified a template, the style element will override any properties the template has set as defaults.

messages.pages[].page
integer

Numeric identifier for the page the rest of this element's settings apply to. This is a one-based numbering of card pages - front cover is 1, inside left is 2, etc.

messages.pages[].style
Style Object

Styles to apply to the main text block on this page. This does not need to define all style object elements, only those you wish to override from a used template or default styles.

Please note: If you have specified a template, the style element will override any properties the template has set for this page. Currently, only align and verticalAlign properties have an effect at a page level.

messages.pages[].text
string

The main panel text to use for a given page. Note that this will only be utilised if the media supports placing text on this page. Most four page cards will restrict front/back panels to artwork only, while postcards typically accept only content for the back panel.

Please note: If you have specified a template, the messages element will be ignored entirely in favor of the template's text.

variables[].(property)
string

Zero or more variables to inject into a template, based on the variables supported by that template. This is a key => value mapped object based on the variables to use in the template.

recipient.firstName
string

The recipient's first name, as it should appear on the envelope.

recipient.lastName
string

The recipient's last name, as it should appear on the envelope.

recipient.company
string

The recipient's company, if required, as it should appear below their name on the envelope.

recipient.address
string

The recipient's street number, name and type, ie. 10 Somewhere Lane

recipient.address2
string

Unit, floor, apartment etc. additional information for the recipient's address.

recipient.city
string

Suburb or city for the recipient.

recipient.region
string

State / province / region for the recipient, if required. UK and NZ currently do not require a region specified.

recipient.postcode
string

Postcode for the recipient.

recipient.country
string

2-character ISO code for the country to ship to.

sender.firstName
string

The sender's first name, as it should appear on the envelope.

Please note: the entire sender section is optional and will default to your organisation's return details if not completed. If any sender element is specified, all must be specified.

sender.lastName
string

The sender's last name, as it should appear on the envelope.

sender.address
string

The sender's street number, name and type, ie. 10 Somewhere Lane

sender.address2
string

Unit, floor, apartment etc. additional information for the sender's address.

sender.city
string

Suburb or city for the sender.

sender.region
string

State / province / region for the sender, if required. UK and NZ currently do not require a region specified.

sender.postcode
string

Postcode for the sender.

sender.country
string

2-character ISO code for the country to use for the return address.

sender.omitAddress
boolean

If true, the sender's address will not appear on envelopes.

shippingMethod
string

The shipping method to use. Note that shipping method support is on a per-region basis, but all regions will at minimum support the standard shipping method.

Currently, only Australia supports the additional priority and express shipping methods. Note that both of these methods have additional credit costs associated with their use.

Please note: Australia Post has suspended use of priority post effective 1st June 2020 until further notice. For expedited shipping within Australia, please utilise express post as an interim measure. This also has the added advantage of providing tracking for your order.

shipToMe
boolean

If set to true, denotes that the recipient of this card is also the sender and to include an additional, blank envelope. Note that this incurs a small additional credit cost.

requestedArrival
date

A future requested arrival date for this card. In a preview request, this will provide a basis for shipping window estimates to be returned. If not specified, immediate dispatch is assumed and dates will be calculated based on the current date.

Return
balance
float

Your organisation's current credit balance after this order has been charged.

giftCredit
object

Your organisation's current gift credit balance and currency.

order
Order Object

An Order object representing the order you just placed.

/v2/orders/place
{
    "lines": [
        {
            "artwork": "happy-birthday",
            "template": "happy-birthday-promo",
            "quantity": 1,
            "messages": {
                "pages": [
                    {
                        "page":    1,
                        "text": ""
                    },
                    {
                        "page":    2,
                        "text": ""
                    },
                    {
                        "page": 3,
                        "text": "",
                        "style": {
                            "color": "1144a7",
                            "verticalAlign": "center"
                        }
                    }
                ]
            },
            "variables": {
                "firstName": "John",
                "message": "Happy birthday, we hope you have a great day!"
            },
            "recipient": {
                "firstName": "John",
                "lastName": "Doe",
                "address": "10 Somewhere Place",
                "address2": "",
                "city": "Fairyland",
                "region": "QLD",
                "postcode": "4110",
                "country": "AU"
            },
            "sender": {
                "firstName": "Cardly Pty Ltd",
                "lastName": null,
                "address": "10 Another Lane",
                "address2": null,
                "city": "Brisbane",
                "region": "QLD",
                "postcode": "4000",
                "country": "AU"
            },
            "shippingMethod": "standard",
            "shipToMe": false,
            "requestedArrival": "2019-12-25"
        }
    ],
    "purchaseOrderNumber": "12345a"
}
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "balance": 99.73,
        "giftCredit": {
            "balance": 2064.1,
            "currency": "AUD"
        },
        "order": {
            "id": "c988c0c0-f6a3-4e90-bbd5-759497a82607",
            "status": "paid",
            "origin": "api",
            "description": null,
            "customer": {
                "firstName": "Cardly Pty Ltd",
                "lastName": null,
                "address": "10 Another Lane",
                "address2": null,
                "city": "Brisbane",
                "region": "QLD",
                "postcode": "4000",
                "country": "AU"
            },
            "currency": "AUD",
            "pricing": {
                "credits": 2.8,
                "giftCredit": 50
            },
            "timings": {
                "paid": "2019-12-04 12:06:46",
                "created": "2019-12-04 12:06:46",
                "updated": "2019-12-04 12:06:46"
            },
            "items": [
                {
                    "id": "60051a2c-86af-45bb-a34f-febf37d9070c",
                    "type": "card",
                    "label": "Cardly - Happy Birthday",
                    "quantity": 1,
                    "costs": {
                        "credits": 0.5,
                        "giftCredit": 0
                    },
                    "shipTo": "S",
                    "shipMethod": "standard",
                    "scheduledDate": "2019-12-25 00:00:00",
                    "recipient": {
                        "address": "10 Somewhere Place",
                        "address2": "",
                        "city": "Fairyland",
                        "region": "QLD",
                        "postcode": "4110",
                        "country": "AU"
                    },
                    "sender": {
                        "name": "Cardly",
                        "address": "10 Another Lane",
                        "address2": null,
                        "city": "Brisbane",
                        "region": "QLD",
                        "postcode": "4000",
                        "country": "AU"
                    },
                    "timings": {
                        "lodgeAfter": "2019-12-04 12:06:46",
                        "shipped": null,
                        "lodged": null,
                        "held": null
                    },
                    "delivery": {
                        "requested": "2019-12-25",
                        "dispatch": "2019-12-12",
                        "estimatedMinArrival": "2019-12-17",
                        "estimatedMaxArrival": "2019-12-20"
                    },
                    "media": 3,
                    "artwork": "5c40d96b-b7c3-4980-9bdc-14306104ebd4",
                    "template": "73bf3d63-5bca-45dc-86f6-d5c01946d78b",
                    "related": [
                        {
                            "id": "3ae265f0-0f63-4018-a0a1-c26d31a3179f",
                            "type": "envelope",
                            "label": "Additional envelope",
                            "quantity": 1,
                            "costs": {
                                "credits": 0.03,
                                "giftCredit": 0
                            },
                            "related": []
                        },
                        {
                            "id": "51897b27-81d6-e82b-dcfe-36f748d516e9",
                            "type": "gift-card",
                            "label": "Gift Card: Amazon Gift Card Card for $50",
                            "quantity": 1,
                            "costs": {
                                "credits": 0,
                                "giftCredit": 50
                            },
                            "related": []
                        }
                    ]
                }
            ]
        }
    },
    "testMode": true
}

Invitations

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

These allow you to programatically 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.

Endpoints

/v2/invitations

/v2/invitations

/v2/invitations/{id}

/v2/invitations/find

/v2/invitations/resend

/v2/invitations/{id}

Invitation Object

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

Attributes
id
UUID

Unique identifier for this invitation.

firstName
string

The invited user's first name, if known.

lastName
string

The invited user's last name, if known.

email
string

The invited user's email address.

status
string

The current status of this invitation.

permissions
object

Permission-keyed list of permissions available once this invitation is accepted.

invited
datetime

When the invitation was created.

inviteSent
datetime

When the user's email invitation was sent.

accepted
datetime

When the invitation was accepted, if at all.

expires
datetime

When the invitation expires.

links.accept
url

The acceptance URL for this invitation.

Invitation Example
{
	"id": "8d207658-12fc-6068-23fe-09135f7b31f1",
	"firstName": "Thor",
	"lastName": "Odinson",
	"email": "thor@avengers.com",
	"status": "invited",
	"permissions": {
		"lists": true,
		"orders": true,
		"templates": 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"
	}
}

Invitation Listing

Retrieve active invitations for your organisation.

Request Parameters
expiredOnly
boolean

If truthy, only return expired invitations.

acceptedOnly
boolean

If truthy, only return accepted invitations.

includeAccepted
boolean

If truthy, includes accepted invitations in the response.

Return
results
array

A paginated array of zero or more Invitation objects.

/v2/invitations
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 1,
            "lastRecord": 8,
            "limit": 25,
            "offset": 0,
            "totalRecords": 8
        },
        "results": [
            {
                "id": "8d207658-12fc-6068-23fe-09135f7b31f1",
                "firstName": "Thor",
                "lastName": "Odinson",
                "email": "thor@avengers.com",
                "status": "invited",
                "permissions": {
                    "lists": true,
                    "orders": true,
                    "templates": 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 Invitation

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

Return
(Data Body)
Invitation Object

An invitation object representing the requested information.

/v2/invitations/{id}
(No body required)
Response
{
	"id": "8d207658-12fc-6068-23fe-09135f7b31f1",
	"firstName": "Thor",
	"lastName": "Odinson",
	"email": "thor@avengers.com",
	"status": "invited",
	"permissions": {
		"lists": true,
		"orders": true,
		"templates": 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"
	}
}

Find Invitation

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

Request Parameters
email
string

The email address to search for.

Return
(Data Body)
Invitation Object

An invitation object representing the requested information.

/v2/invitations/find
(No body required)
Response
{
	"id": "8d207658-12fc-6068-23fe-09135f7b31f1",
	"firstName": "Thor",
	"lastName": "Odinson",
	"email": "thor@avengers.com",
	"status": "invited",
	"permissions": {
		"lists": true,
		"orders": true,
		"templates": 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"
	}
}

Add Invitation

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

Request Parameters
firstName
string

The first name of the user.

lastName
string

The last name of the user.

email
string

An email address for this user.

permissions
array

Zero or more permission identifiers from the following list, denoting the privileges to grant the user once they accept your invitation: administrator artwork billing campaigns developer lists moderate moderate-history orders templates users use-credits use-saved-card

Return
(Data Body)
Invitation Object

An object representing the invitation that was just created. Use the ID property from this to feed into further requests as needed.

/v2/invitations
{
    "firstName": "Thor",
    "lastName": "Odinson",
    "email": "thor@avengers.com",
	"permissions": ["users", "templates", "orders"]
}
Response
{
	"id": "8d207658-12fc-6068-23fe-09135f7b31f1",
	"firstName": "Thor",
	"lastName": "Odinson",
	"email": "thor@avengers.com",
	"status": "invited",
	"permissions": {
		"lists": true,
		"orders": true,
		"templates": 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"
	}
}

Resend Invitation

Resend an invitation if that invitation has not been accepted.

Note that one of email or ID is required to uniquely find an invitation to resend.

Request Parameters
id
string

The ID unique to the invitation to resend.

email
string

The email address to search for.

Return
(Data Body)
Invitation Object

The invitation object representing the invitation that was resent.

/v2/resend/{id?}
{
    "email": "thor@avengers.com"
}
Response
{
	"id": "8d207658-12fc-6068-23fe-09135f7b31f1",
	"firstName": "Thor",
	"lastName": "Odinson",
	"email": "thor@avengers.com",
	"status": "invited",
	"permissions": {
		"lists": true,
		"orders": true,
		"templates": 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 Invitation

Delete an invitation, immediately invalidating it for acceptance.

Note that one of email or ID is required to uniquely find an invitation to remove.

Request Parameters
id
string

The ID unique to the invitation to revoke.

email
string

The email address to search for.

Return
(Data Body)
Invitation Object

The invitation object representing the invitation that was deleted.

/v2/invitations/{id?}
{
    "email": "thor@avengers.com"
}
Response
{
	"id": "8d207658-12fc-6068-23fe-09135f7b31f1",
	"firstName": "Thor",
	"lastName": "Odinson",
	"email": "thor@avengers.com",
	"status": "invited",
	"permissions": {
		"lists": true,
		"orders": true,
		"templates": 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 programatically 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.

Endpoints

/v2/users

/v2/users/{id}

/v2/users/find

/v2/{id}

User Object

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

Attributes
id
UUID

Unique identifier for this user.

firstName
string

The user's first name, if known.

lastName
string

The user's last name, if known.

email
string

The user's email address.

status
string

The current status of this user.

permissions
object

Permission-keyed list of permissions available to this user.

User Example
{
	"id": "8d207658-12fc-6068-23fe-09135f7b31f1",
	"firstName": "Thor",
	"lastName": "Odinson",
	"email": "thor@avengers.com",
	"status": "active",
	"permissions": {
		"lists": true,
		"orders": true,
		"templates": true
	}
}

User Listing

Retrieve active users for your organisation.

Return
results
array

A paginated array of zero or more User objects.

/v2/users
(No body required)
Response
{
    "state": {
        "status": "OK",
        "messages": []
    },
    "data": {
        "meta": {
            "startRecord": 1,
            "lastRecord": 8,
            "limit": 25,
            "offset": 0,
            "totalRecords": 8
        },
        "results": [
            {
                "id": "8d207658-12fc-6068-23fe-09135f7b31f1",
                "firstName": "Thor",
                "lastName": "Odinson",
                "email": "thor@avengers.com",
                "status": "invited",
                "permissions": {
                    "lists": true,
                    "orders": true,
                    "templates": true
                }
            },
            ...
        ]
    }
}

Get User

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

Return
(Data Body)
User Object

A user object representing the requested information.

/v2/users/{id}
(No body required)
Response
{
	"id": "8d207658-12fc-6068-23fe-09135f7b31f1",
	"firstName": "Thor",
	"lastName": "Odinson",
	"email": "thor@avengers.com",
	"status": "active",
	"permissions": {
		"lists": true,
		"orders": true,
		"templates": true
	}
}

Find User

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

Request Parameters
email
string

The email address to search for.

Return
(Data Body)
User Object

A user object representing the requested information.

/v2/users/find
(No body required)
Response
{
	"id": "8d207658-12fc-6068-23fe-09135f7b31f1",
	"firstName": "Thor",
	"lastName": "Odinson",
	"email": "thor@avengers.com",
	"status": "active",
	"permissions": {
		"lists": true,
		"orders": true,
		"templates": true
	}
}

Delete User

Remove a user's access from your account immediately.

Note that one of email or ID is required to uniquely find a user to remove.

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
id
string

The ID unique to the user to revoke.

email
string

The email address to search for.

Return
(Data Body)
User Object

The user object representing the user that was deleted.

/v2/users/{id?}
{
    "email": "thor@avengers.com"
}
Response
{
	"id": "8d207658-12fc-6068-23fe-09135f7b31f1",
	"firstName": "Thor",
	"lastName": "Odinson",
	"email": "thor@avengers.com",
	"status": "active",
	"permissions": {
		"lists": true,
		"orders": true,
		"templates": true
	}
}