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.

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

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

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

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

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

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

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

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

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.

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

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

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

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.

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.

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.

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.