### GET /templates

Source: https://api.card.ly/openapi/en-AU/2.2.0/json

Retrieve your currently available templates.


```markdown
### Responses

#### 200 - A paginated array of zero or more `Template` objects.

- **state** (object): Provides a standard status identifier to indicate overall success, along with messages and the current API build version.
  - **status** (string (OK|WARN|ERROR)): Whether or not the request succeeeded without errors or warnings. (example: "OK") ("OK"|"WARN"|"ERROR")
  - **messages** (array (string)): Any notifications, warnings or error messages relevant to the response. (example: [])
  - **version** (integer): The current build version of Cardly (example: 1181)
- **data** (object)
  - **meta** (object): Provides a standard description of a listing result set and the records that were retrieved.
    - **orderBy** (string): The current field that results are ordered by. (example: "name")
    - **orderDirection** (string (asc|desc)): The direction results are ordered by, ascending or descending. (example: "asc") ("asc"|"desc")
    - **startRecord** (integer): The 1-based number of the first record in this result set, relative to the whole result set. (example: 1)
    - **lastRecord** (integer): The 1-based number of the last record in this result set, relative to the whole result set. (example: 25)
    - **limit** (integer): The maximum number of results per page. (example: 25)
    - **page** (integer): The calculated page number for these results, based on supplied offset and limit values. (example: 2)
    - **offset** (integer): The current number of records to offset the start of the result set by. (example: 0)
    - **totalRecords** (integer): The total number of results in the entire set based on your query parameters. (example: 123)
  - **results** (array (Template)): A paginated array of zero or more `Template` objects.
    Array items:
      - **id** (string): Unique identifier for this template option. (example: "18ecf6e6-d2e2-49cb-bae0-fa980241db73")
      - **name** (string): The human-readable description for this template. (example: "Happy Birthday")
      - **slug** (string): A human-readable identifier for this template unique within your organisation. (example: "happy-birthday")
      - **generic** (boolean): Whether or not there are any active variables within your template design. `true` if no variables are active. (example: false)
      - **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.
        - **id** (string): Unique identifier for this piece of artwork. To be passed through to `Place Order` and similar calls requiring artwork IDs. (example: "8cdcfaed-ae1c-11ea-8ee1-021187248360")
        - **name** (string): A localised, human-readable name for this product. (example: "Standard Postcard")
        - **description** (string): A longer description of the product, along with any restrictions or important information. (example: "Standard postcard for all locales.")
        - **creditCost** (number (float)): The number of credits that would be consumed when ordering this media type. (example: 0.6)
        - **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). (example: 2)
        - **dimensions** (object): Dimensions of this product in millimeters, exclusive of bleed.
          - **mm** (object)
            - **height** (integer): Height of this product, in millimeters, exclusive of bleed. (example: 105)
            - **width** (integer): Width of this product, in millimeters, exclusive of bleed. (example: 148)
        - **bleed** (object): DimensionsBleed 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** (object)
          - **px** (object)
            - **innerHeight** (integer): Height of the artwork inner area for this product, in pixels, exclusive of bleed zones. (example: 1653)
            - **innerWidth** (integer): Width of the artwork inner area for this product, in pixels, exclusive of bleed zones. (example: 2330)
            - **height** (integer): Height of the artwork required for this product, in pixels, inclusive of bleed zones. (example: 1811)
            - **width** (integer): Width of the artwork required for this product, in pixels, inclusive of bleed zones. (example: 2488)
      - **giftCard** (object): If this template contains a gift card, describes the type of card selected and the value of the card.
        - **id** (string): The unique ID of the gift card that has been included. (example: "4b458510-5b7f-0bdc-7e21-891ce658a935")
        - **region** (string): The country code this gift card applies to. (example: "AU")
        - **currency** (string): The currency this card is provided in. (example: "AUD")
        - **amount** (number (float)): The amount of funds provided on this gift card. (example: 50)
        - **canChange** (boolean): Whether or not the recipient can swap this card for another. (example: true)
      - **definition** (object): An object describing this template's layout.
        - **version** (number (float)): The version of the Cardly editor this template was created by. (example: 2.2)
        - **style** (object): The default styles to filter through to pages in this template, if no styles are defined at the page level.
          - **align** (string) (example: "left")
          - **color** (string) (example: "1144a7")
          - **size** (integer) (example: 25)
          - **writing** (string) (example: "987d50c7-25e1-3b1c-aa78-6f60b1411fe5")
          - **font** (string) (example: "0d372503-c81b-987d-7636-bd6321290528")
        - **pages** (array (object)): 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. (example: [])
        - **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.
          - **firstName** (object)
            - **description** (string) (example: "Customer's first name to display in card front and salutation.")
            - **example** (string) (example: "John")
      - **createdAt** (string (date-time)): `YYYY-MM-DDTHH:ii:ss+00:00` formatted string to denote when this template was created.
 (example: "2020-06-13T23:40:09.000Z")
      - **updatedAt** (string (date-time)): `YYYY-MM-DDTHH:ii:ss+00:00` formatted string to denote when this template was last updated.
 (example: "2020-06-14T04:39:35.000Z")

### Example Usage

```bash
curl -X GET "https://api.card.ly/v2/templates"
```

```

--------------------------------

### GET /writing-styles

Source: https://api.card.ly/openapi/en-AU/2.2.0/json

Retrieve your currently available writing styles.


```markdown
### Responses

#### 200 - A paginated array of zero or more `WritingStyle` objects.

- **state** (object): Provides a standard status identifier to indicate overall success, along with messages and the current API build version.
  - **status** (string (OK|WARN|ERROR)): Whether or not the request succeeeded without errors or warnings. (example: "OK") ("OK"|"WARN"|"ERROR")
  - **messages** (array (string)): Any notifications, warnings or error messages relevant to the response. (example: [])
  - **version** (integer): The current build version of Cardly (example: 1181)
- **data** (object)
  - **meta** (object): Provides a standard description of a listing result set and the records that were retrieved.
    - **orderBy** (string): The current field that results are ordered by. (example: "name")
    - **orderDirection** (string (asc|desc)): The direction results are ordered by, ascending or descending. (example: "asc") ("asc"|"desc")
    - **startRecord** (integer): The 1-based number of the first record in this result set, relative to the whole result set. (example: 1)
    - **lastRecord** (integer): The 1-based number of the last record in this result set, relative to the whole result set. (example: 25)
    - **limit** (integer): The maximum number of results per page. (example: 25)
    - **page** (integer): The calculated page number for these results, based on supplied offset and limit values. (example: 2)
    - **offset** (integer): The current number of records to offset the start of the result set by. (example: 0)
    - **totalRecords** (integer): The total number of results in the entire set based on your query parameters. (example: 123)
  - **results** (array (WritingStyle)): A paginated array of zero or more `WritingStyle` objects.
    Array items:
      - **id** (string): Unique identifier for this writing style option. (example: "18ecf6e6-d2e2-49cb-bae0-fa980241db73")
      - **name** (string): A human-readable name for this writing style. (example: "Perfection")
      - **description** (string): A description of this writing style. (example: "No humanisation applied at all, absolutely perfect writing.")
      - **order** (string): Unique identifier for this template option. (example: 0)

### Example Usage

```bash
curl -X GET "https://api.card.ly/v2/writing-styles"
```

```

--------------------------------

### POST /orders/preview

Source: https://api.card.ly/openapi/en-AU/2.2.0/json

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

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


```markdown
### Request Body

**Content-Type:** application/json

- **artwork** (string) (required): 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. (example: "happy-birthday")
- **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. (example: "happy-birthday-promo")
- **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.
  - **align** (string (left|center)): One of `left` (default) or `center` to denote text flow behaviour. (example: "left") ("left"|"center")
  - **color** (string): RRGGBB hex code (without the hash mark) denoting the colour to use for text or doodle elements. (example: "1144a7")
  - **font** (string): ID of a font to apply to a text area. Must be either a publically available font or accessible by your organisation. (example: "0d372503-c81b-987d-7636-bd6321290528")
  - **size** (integer): 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. (example: 25)
  - **verticalAlign** (string (top|center|bottom)): One of `top` (default), `center`, or `bottom` to denote where rendered text should sit in relation to the editor page.

**Note:** This feature is experimental and should be used with caution.
 (example: "top") ("top"|"center"|"bottom")
  - **writing** (string): ID of a writing style to apply. Defaults to 'standard' as per the main Cardly editor if not defined. (example: "987d50c7-25e1-3b1c-aa78-6f60b1411fe5")
- **messages** (object): Message data to inject when not utilising pre-built templates from your account.
  - **pages** (array (object)) (example: [{"page":1,"text":""},{"name":2,"text":"This is the inner left content."},{"name":3,"text":"This is the inner right content.","style":{"color":"1144a7","verticalAlign":"center"}}])
    Array items:
      - **page** (integer): 1-based identifier for the page these settings relate to. 1 identifies the front page, each subsequent page is identified in reading order.
      - **text** (string): Text to override into the main panel of a card. Replaces any text that may be present from a template that's in use.
      - **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.
- **variables** (object): 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. (example: {"firstName":"Thor","company":"Avengers Inc."})
- **recipient** (object) (required): The recipient's addressing details, as they should appear on the envelope.
  - **firstName** (string) (required): The recipient's first name, as it should appear on the envelope. (example: "Thor")
  - **lastName** (string): The recipient's last name, as it should appear on the envelope (example: "Thor")
  - **company** (string): The recipient's company, if required, as it should appear below their name on the envelope. (example: "Avengers Inc")
  - **address** (string) (required): The recipient's street number, name and type. (example: "1 Main Street")
  - **address2** (string): Unit, floor, apartment etc. additional information for the recipient's address. (example: "Suite 1054")
  - **city** (string) (required): Suburb or city for the recipient. (example: "Brooklyn")
  - **region** (string) (required): State / province / region for the recipient, if required. UK and NZ currently do not require a region specified.
**Conditionally required** based on the country supplied.
 (example: "NY")
  - **postcode** (string) (required): The postcode for this recipient. Note that this may be empty for countries that do not utilise postcodes.

**Conditionally required** based on the country supplied.
 (example: 12345)
  - **country** (string) (required): The 2-character ISO code for the country relating to this recipient. (example: "US")
- **sender** (object): Details of the sender for this order.

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

- **shippingMethod** (string (standard|tracked|express)): 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 `tracked` shipping method.

Currently, only Australia and the United States support the `express` shipping method.
 (example: "standard") ("standard"|"tracked"|"express")
- **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 per card within the order.
 (example: false)
- **requestedArrival** (string): 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. (example: "2024-12-25")
- **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. (example: "PO1234")

### Responses

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

- **state** (object): Provides a standard status identifier to indicate overall success, along with messages and the current API build version.
  - **status** (string (OK|WARN|ERROR)): Whether or not the request succeeeded without errors or warnings. (example: "OK") ("OK"|"WARN"|"ERROR")
  - **messages** (array (string)): Any notifications, warnings or error messages relevant to the response. (example: [])
  - **version** (integer): The current build version of Cardly (example: 1181)
- **data** (object)
  - **balance** (number (float)): Your organisation's current credit balance after this order has been charged. (example: 203)
  - **giftBalance** (object)
    - **balance** (number (float)): Your gift credit balance *after* this order has been charged. (example: 2064.1)
    - **currency** (string): The currency your gift credit is displayed in. (example: "USD")
  - **order** (object): Describes credit costs and shipping windows based on the requested preview data.
    - **creditCost** (number (float)): The total card credit cost for this preview item, if it were placed as an order line item. (example: 22.1)
    - **giftCreditCost** (number (float)): The total gift credit required for a line item if it was placed as an order line item. (example: 56.21)
    - **delivery** (object): Describes requested and estimated delivery windows for a given item.
      - **requested** (string): The arrival date requested, if applicable. This will be null where you did not specify a requested delivery date. (example: "2024-12-25T00:00:00.000Z")
      - **dispatch** (string): 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. (example: "2024-12-12T00:00:00.000Z")
      - **estimatedMinArrival** (string): 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.
 (example: "2024-12-17T00:00:00.000Z")
      - **estimatedMaxArrival** (string): 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.
 (example: "2024-12-20T00:00:00.000Z")
  - **preview** (object)
    - **expires** (string): When this preview's generated documents will be deleted. These documents should be retrieved prior to this time. (example: null)
    - **format** (string): The file format this preview was generated in. Currently only `pdf` is supported. (example: "pdf")
    - **urls** (object): URLs for the card and envelope artwork for this preview.
      - **card** (string (uri)): A URL to retrieve the card preview document. (example: "http://api.card.ly/v2/preview/4e898074-6a2e-e3fb-9778-518596c36c2a/card/pdf")
      - **envelope** (string (uri)): A URL to retrieve the envelope preview document. Note that this will not exist for postcards. (example: "http://api.card.ly/v2/preview/4e898074-6a2e-e3fb-9778-518596c36c2a/envelope/pdf")

#### 422 - A status indicating validation failures with the submission.

- **state** (object): Provides a standard status identifier to indicate overall success, along with messages and the current API build version.
  - **status** (string (OK|WARN|ERROR)): Whether or not the request succeeeded without errors or warnings. (example: "OK") ("OK"|"WARN"|"ERROR")
  - **messages** (array (string)): Any notifications, warnings or error messages relevant to the response. (example: [])
  - **version** (integer): The current build version of Cardly (example: 1181)

### Example Usage

```bash
curl -X POST "https://api.card.ly/v2/orders/preview" \
  -H "Content-Type: application/json" \
  -d '{
  "artwork": "happy-birthday",
  "template": "happy-birthday-promo",
  "style": "value",
  "messages": {
    "pages": [
      {
        "page": 1,
        "text": ""
      },
      {
        "name": 2,
        "text": "This is the inner left content."
      },
      {
        "name": 3,
        "text": "This is the inner right content.",
        "style": {
          "color": "1144a7",
          "verticalAlign": "center"
        }
      }
    ]
  },
  "variables": {
    "firstName": "Thor",
    "company": "Avengers Inc."
  },
  "recipient": {
    "firstName": "Thor",
    "lastName": "Thor",
    "company": "Avengers Inc",
    "address": "1 Main Street",
    "address2": "Suite 1054",
    "city": "Brooklyn",
    "region": "NY",
    "postcode": 12345,
    "country": "US"
  },
  "sender": {
    "firstName": "Bruce",
    "lastName": "Banner",
    "company": "Avengers Inc",
    "address": "1 Main Street",
    "address2": "Suite 1054",
    "city": "Brooklyn",
    "region": "NY",
    "postcode": 12345,
    "country": "US",
    "omitAddress": "true"
  },
  "shippingMethod": "standard",
  "shipToMe": false,
  "requestedArrival": "2024-12-25",
  "purchaseOrderNumber": "PO1234"
}'
```

```

--------------------------------

### GET /webhooks/{id}

Source: https://api.card.ly/openapi/en-AU/2.2.0/json

Get details on an existing webhook.


```markdown
### Parameters

- **id** (string, path, required): The unique ID of the webhook to retrieve.

### Responses

#### 200 - A `Webhook` representing the object that was requested. Note that the *secret* property will be obfuscated.


- **state** (object): Provides a standard status identifier to indicate overall success, along with messages and the current API build version.
  - **status** (string (OK|WARN|ERROR)): Whether or not the request succeeeded without errors or warnings. (example: "OK") ("OK"|"WARN"|"ERROR")
  - **messages** (array (string)): Any notifications, warnings or error messages relevant to the response. (example: [])
  - **version** (integer): The current build version of Cardly (example: 1181)
- **data** (object): The webhook object provides detail on a REST webhook you or a third party platform such as Zapier has set up to provide near-realtime notifications of events within your Cardly business account.
  - **id** (string): Unique identifier for this webhook. (example: "d2e2f6e6-9802-bae0-bae0-fa980241db73")
  - **secret** (string): The webhook's secret key which can be used to verify postbacks. The full secret is only supplied once at creation time. You should note this secret if you intend to verify postback signatures, which we highly recommend. (example: "30f34805d37595098a54b3123b4357f7")
  - **status** (string): The status of this webhook, typically one of `active` or `disabled`. (example: "active")
  - **protected** (boolean): Whether or not this webhook was created by a third party platform such as Zapier and care should be taken with updating or deleting it to not break other integrations you may have.
  - **targetUrl** (string): The URL this webhook will send POST requests to once one of its subscribed events is triggered. (example: "https://www.stark-industries.com/postbacks/inbound")
  - **description** (string): A free text description of what this webhook is for, or any notes related to the webhook. (example: "Aid with feeding send data and change-of-address information back into our CRM.")
  - **metadata** (object): A structure of key:value pairs that you've supplied to provide additional detail for this webhook, if required.
  - **events** (array (object)): The events this webhook is subscribed to. You will only receive notifications for these events. (example: ["contact.order.created","contact.order.sent","contact.undeliverable","contact.changeOfAddress"])
  - **createdAt** (string (date-time)): `YYYY-MM-DDTHH:ii:ss+00:00` formatted string to denote when this webhook was created.
 (example: "2020-06-14T09:40:09.000Z")
  - **updatedAt** (string (date-time)): `YYYY-MM-DDTHH:ii:ss+00:00` formatted string to denote when this webhook was last updated.
 (example: "2020-06-14T14:39:35.000Z")

#### 404 - A status indicating that the specified webhook could not be found.

- **state** (object): Provides a standard status identifier to indicate overall success, along with messages and the current API build version.
  - **status** (string (OK|WARN|ERROR)): Whether or not the request succeeeded without errors or warnings. (example: "OK") ("OK"|"WARN"|"ERROR")
  - **messages** (array (string)): Any notifications, warnings or error messages relevant to the response. (example: [])
  - **version** (integer): The current build version of Cardly (example: 1181)
- **data** (object): One or more elements denoting validations failures with the named field(s), and the reason for failure.
  - **email** (string): A reason the identified key's value has failed validation. (example: "This value should be a valid email address.")

### Example Usage

```bash
curl -X GET "https://api.card.ly/v2/webhooks/{id}"
```

```

--------------------------------

### POST /echo

Source: https://api.card.ly/openapi/en-AU/2.2.0/json

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.


```markdown
### Parameters

- **test** (string, query, optional): An example parameter which will be returned to you.

### Request Body

**Content-Type:** application/json

- **foo** (string): A body parameter which will be returned to you (example: "bar")
- **bar** (array (string)): A body parameter which will be returned to you (example: ["A","B","C"])

### Responses

#### 200 - A description of all data passed in the request.

- **state** (object): Provides a standard status identifier to indicate overall success, along with messages and the current API build version.
  - **status** (string (OK|WARN|ERROR)): Whether or not the request succeeeded without errors or warnings. (example: "OK") ("OK"|"WARN"|"ERROR")
  - **messages** (array (string)): Any notifications, warnings or error messages relevant to the response. (example: [])
  - **version** (integer): The current build version of Cardly (example: 1181)
- **data** (object)
  - **method** (string): The HTTP verb that was used for this call. (example: "POST")
  - **url** (string): The full endpoint URL tht was called, including query string. (example: "https://api.card.ly/v2/echo")
  - **headers** (object): All client-supplied headers in the request, keyed by header. (example: {"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** (object): All client-supplied query parameters supplied in the call, keyed by parameter name. (example: {"test":"foo"})
  - **body** (object): The request body for the call, if applicable. (example: {"foo":"bar","bar":["A","B","C"]})

### Example Usage

```bash
curl -X POST "https://api.card.ly/v2/echo?test=string" \
  -H "Content-Type: application/json" \
  -d '{
  "foo": "bar",
  "bar": [
    "A",
    "B",
    "C"
  ]
}'
```

```