--- openapi: 3.0.0 info: title: Cardly API description: | 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. version: 2.1.0 servers: - url: https://api.card.ly/v2 description: Cardly v2 Primary Endpoint security: - ApiKeyAuth: [] paths: /echo: post: tags: - Testing & Development summary: Echo Request description: | 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. operationId: anyEcho parameters: - name: test in: query description: An example parameter which will be returned to you. required: false style: form explode: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/echo_body' responses: "200": description: A description of all data passed in the request. content: application/json: schema: $ref: '#/components/schemas/inline_response_200' x-verb: any /account/balance: get: tags: - Account summary: Retrieve Account Balance description: | 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. operationId: getBalance responses: "200": description: Your account's current credit and gift credit balances. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_1' /account/credit-history: get: tags: - Account summary: List Credit History description: | 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: operationId: getCreditHistory parameters: - name: effectiveTime.lt in: query description: | `YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *before* this time. required: false style: form explode: true schema: type: string - name: effectiveTime.lte in: query description: | `YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *before or equal* to this time. required: false style: form explode: true schema: type: string - name: effectiveTime.gt in: query description: | `YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *after* this time. required: false style: form explode: true schema: type: string - name: effectiveTime.gte in: query description: | `YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *after or equal* to this time. required: false style: form explode: true schema: type: string responses: "200": description: A paginated array of zero or more `CreditHistory` objects. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_2' /account/gift-credit-history: get: tags: - Account summary: List Gift Credit History description: | 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: operationId: getGiftCreditHistory parameters: - name: effectiveTime.lt in: query description: | `YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *before* this time. required: false style: form explode: true schema: type: string x-subtype: datetime - name: effectiveTime.lte in: query description: | `YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *before or equal* to this time. required: false style: form explode: true schema: type: string x-subtype: datetime - name: effectiveTime.gt in: query description: | `YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *after* this time. required: false style: form explode: true schema: type: string x-subtype: datetime - name: effectiveTime.gte in: query description: | `YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *after or equal* to this time. required: false style: form explode: true schema: type: string x-subtype: datetime responses: "200": description: A paginated array of zero or more `GiftCreditHistory` objects. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_3' /art: get: tags: - Artwork summary: List Artwork description: | Retrieve the currently available artwork for your organisation. This request accepts standard pagination options `limit, offset` along with the following additional filters: operationId: getArtworkListing parameters: - name: ownOnly in: query description: | 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. required: false style: form explode: true schema: type: boolean responses: "200": description: A paginated array of zero or more `Artwork` objects. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_4' post: tags: - Artwork summary: Create Artwork description: | Add a new piece of artwork. operationId: postArtworkCreate requestBody: content: application/json: schema: $ref: '#/components/schemas/art_body' responses: "200": description: An `Artwork` representing the artwork that was just created. Use the ID property from this to feed into order/preview requests as needed. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_5' "422": description: A status indicating validation failures with the submission. content: application/json: schema: $ref: '#/components/schemas/inline_response_422' /art/{id}: get: tags: - Artwork summary: Retrieve Artwork description: | Retrieve information on a specific piece of artwork. operationId: getArtwork parameters: - name: id in: path description: The unique ID of the artwork you wish to retrieve. required: true style: simple explode: false schema: type: string x-subtype: uuid responses: "200": description: An `Artwork` representing the requested piece of artwork. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_5' "404": description: A status indicating the artwork could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' post: tags: - Artwork summary: Edit Artwork description: | Update a piece of artwork with new descriptors or images. All parameters are optional, and only supplied parameters will be updated. operationId: postArtworkEdit parameters: - name: id in: path description: The unique ID of the artwork you wish to update. required: true style: simple explode: false schema: type: string x-subtype: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/art_id_body' responses: "200": description: An `Artwork` representing the updated piece of artwork. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_5' "404": description: A status indicating the artwork could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' "422": description: A status indicating validation failures with the submission. content: application/json: schema: $ref: '#/components/schemas/inline_response_422' delete: tags: - Artwork summary: Delete Artwork description: | Delete a piece of artwork owned by your organisation. operationId: deleteArtwork parameters: - name: id in: path description: The unique ID of the artwork you wish to delete. required: true style: simple explode: false schema: type: string x-subtype: uuid responses: "200": description: An `Artwork` representing the artwork that was deleted. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_5' "404": description: A status indicating the artwork could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' /contact-lists: get: tags: - Contact Lists summary: List Contact Lists description: | Retrieve active contact lists for your organisation. operationId: getContactLists responses: "200": description: A paginated array of zero or more `ContactList` objects. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_6' post: tags: - Contact Lists summary: Create Contact List description: | Add a new contact list, optionally with custom fields. operationId: createContactList requestBody: content: application/json: schema: $ref: '#/components/schemas/contactlists_body' responses: "200": description: A `ContactList` representing the list that was just created. Use the ID property from this to feed into further requests as needed. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_7' "422": description: A status indicating validation failures with the submission. content: application/json: schema: $ref: '#/components/schemas/inline_response_422' /contact-lists/{id}: get: tags: - Contact Lists summary: Retrieve Contact List description: | Retrieve information on a specific contact list. operationId: getContactList parameters: - name: id in: path description: The unique ID of the contact list you wish to retrieve. required: true style: simple explode: false schema: type: string x-subtype: uuid responses: "200": description: A `ContactList` representing the requested contact list. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_7' "404": description: A status indicating the contact list could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' post: tags: - Contact Lists summary: Create Contact List description: | Add a new contact list, optionally with custom fields. operationId: postContactList parameters: - name: id in: path description: The unique ID of the contact list you wish to update. required: true style: simple explode: false schema: type: string x-subtype: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/contactlists_id_body' responses: "200": description: A `ContactList` representing the list that was updated. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_7' "404": description: A status indicating the contact list could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' "422": description: A status indicating validation failures with the submission. content: application/json: schema: $ref: '#/components/schemas/inline_response_422' delete: tags: - Contact Lists summary: Delete Contact List description: | Delete a contact list, disabling any automations linked to it. operationId: deleteContactList parameters: - name: id in: path description: The unique ID of the contact list you wish to delete. required: true style: simple explode: false schema: type: string x-subtype: uuid responses: "200": description: A `ContactList` representing the contact list that was deleted. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_7' "404": description: A status indicating the contact list could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' /contact-lists/{listId}/contacts: get: tags: - Contacts summary: List Contacts description: | Retrieve active contacts in a given list. operationId: getContactsListing parameters: - name: listId in: path description: The unique ID of the contact list you wish to retrieve contacts for. required: true style: simple explode: false schema: type: string x-subtype: uuid responses: "200": description: A paginated array of zero or more `Contact` records. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_8' "404": description: A status indicating the contact list could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' post: tags: - Contacts summary: Create Contact description: | 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. operationId: createContact parameters: - name: listId in: path description: The unique ID of the contact list you wish to add this contact to. required: true style: simple explode: false schema: type: string x-subtype: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/listId_contacts_body' responses: "200": description: A `Contact` representing the contact that was created. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_9' "404": description: A status indicating the requested contact list could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' "422": description: A status indicating validation failures with the submission. content: application/json: schema: $ref: '#/components/schemas/inline_response_422' delete: tags: - Contacts summary: Delete Contact description: | Delete a contact, disabling any automations linked to it. Contact matching is performed in order of matching external ID or email address. At least one of these details must be provided. operationId: deleteContactByIdentifier parameters: - name: listId in: path description: The unique ID of the contact list you wish to search contacts for to delete. required: true style: simple explode: false schema: type: string x-subtype: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/listId_contacts_body_1' responses: "200": description: A `Contact` representing the contact that was deleted. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_9' "404": description: A status indicating a matching contact or underlying contact list could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' /contact-lists/{listId}/contacts/{id}: get: tags: - Contacts summary: Retrieve Contact description: | Retrieve information on a specific contact from a given list, identified by Cardly's unique identifier for the record. operationId: getContact parameters: - name: listId in: path description: The unique ID of the contact list this contact belongs to. required: true style: simple explode: false schema: type: string x-subtype: uuid - name: id in: path description: The unique ID of the contact you wish to retrieve. required: true style: simple explode: false schema: type: string x-subtype: uuid responses: "200": description: A `Contact` representing the requested contact. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_9' "404": description: A status indicating the contact list or contact could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' post: tags: - Contacts summary: Edit Contact description: | Edit an existing contact, providing updated information for the contact record. operationId: postContact parameters: - name: listId in: path description: The unique ID of the contact list the contact you're updating belongs to. required: true style: simple explode: false schema: type: string x-subtype: uuid - name: id in: path description: The unique ID of the contact you wish to update. required: true style: simple explode: false schema: type: string x-subtype: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/contacts_id_body' responses: "200": description: A `Contact` representing the contact that was updated. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_9' "404": description: A status indicating the requested contact list or contact could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' "422": description: A status indicating validation failures with the submission. content: application/json: schema: $ref: '#/components/schemas/inline_response_422' delete: tags: - Contacts summary: Delete Contact description: | Delete a contact, disabling any automations linked to it. operationId: deleteContact parameters: - name: listId in: path description: The unique ID of the contact list the contact you're deleting belongs to. required: true style: simple explode: false schema: type: string x-subtype: uuid - name: id in: path description: The unique ID of the contact you wish to delete. required: true style: simple explode: false schema: type: string x-subtype: uuid responses: "200": description: A `Contact` representing the contact that was deleted. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_9' "404": description: A status indicating a matching contact or underlying contact list could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' /contact-lists/{listId}/contacts/find: get: tags: - Contacts summary: Search Contacts description: | Retrieve information on a specific contact from a given list, searching for the contact by an email address or previously supplied external identifier. operationId: searchContacts parameters: - name: listId in: path description: The unique ID of the contact list to search within. required: true style: simple explode: false schema: type: string x-subtype: uuid - name: query in: query description: An email address or external identifier to locate a contact by within the given list. required: true style: form explode: true schema: type: string responses: "200": description: A `Contact` representing the requested contact. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_9' "404": description: A status indicating the contact list or contact could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' /contact-lists/{listId}/contacts/sync: post: tags: - Contacts summary: Sync Contact description: | Sync a contact based on an external ID or email address. If a matching contact does not exist, a new one is created, otherwise existing contact records are updated. Previously removed contacts will be reactivated if they match provided details. Contact matching is performed in order of matching external ID or email address. At least one of these details must be provided, and the first matching contact (if found) is used for update operations. operationId: postContactSync parameters: - name: listId in: path description: The unique ID of the contact list you wish to add this contact to. required: true style: simple explode: false schema: type: string x-subtype: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/contacts_sync_body' responses: "200": description: A `Contact` representing the contact that was updated or created. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_9' "404": description: A status indicating the requested contact list could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' "422": description: A status indicating validation failures with the submission. content: application/json: schema: $ref: '#/components/schemas/inline_response_422' /doodles: get: tags: - Doodles summary: List Doodles description: | Retrieve your currently available doodles. This request accepts standard pagination options `limit, offset` along with the following additional filters: operationId: getDoodleListing parameters: - name: organisationOnly in: query description: | If truthy, only return doodles that are exclusive to your organisation. required: false style: form explode: true schema: type: boolean responses: "200": description: A paginated array of zero or more `Doodle` objects. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_10' /fonts: get: tags: - Fonts summary: List Fonts description: | Retrieve your currently available fonts. This request accepts standard pagination options `limit, offset` along with the following additional filters: operationId: getFontListing parameters: - name: organisationOnly in: query description: | If truthy, only return fonts that are exclusive to your organisation. required: false style: form explode: true schema: type: boolean responses: "200": description: A paginated array of zero or more `Font` objects. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_11' /invitations: get: tags: - Invitations summary: List Invitations description: | Retrieve active invitations for your organisation. This request accepts standard pagination options `limit, offset` along with the following additional filters: operationId: getInvitationListing parameters: - name: acceptedOnly in: query description: | If truthy, only return accepted invitations. required: false style: form explode: true schema: type: boolean - name: expiredOnly in: query description: | If truthy, only return expired invitations. required: false style: form explode: true schema: type: boolean - name: includeAccepted in: query description: | If truthy, includes accepted invitations in the response. By default, accepted invitations are filtered out of listings. required: false style: form explode: true schema: type: boolean responses: "200": description: A paginated array of zero or more `Invitation` objects. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_12' post: tags: - Invitations summary: Create Invitation description: | Send an invitation to use your organisation portal, if the provided email address doesn't already have access. operationId: postInvitation requestBody: content: application/json: schema: $ref: '#/components/schemas/invitations_body' responses: "200": description: An `Invitation` representing the invitation that was created. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_13' "422": description: A status indicating validation failures with the submission. content: application/json: schema: $ref: '#/components/schemas/inline_response_422' delete: tags: - Invitations summary: Delete Invitation by Email description: | Delete an invitation by email address, immediately invalidating it for acceptance. operationId: deleteInvitationByEmail requestBody: content: application/json: schema: $ref: '#/components/schemas/invitations_body_1' responses: "200": description: An `Invitation` representing the invitation that was deleted. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_13' "404": description: A status indicating a matching invitation could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' /invitations/{id}: get: tags: - Invitations summary: Retrieve Invitation description: | Retrieve information on a specific invitation, identified by Cardly's unique identifier for the record. operationId: getInvitationById parameters: - name: id in: path description: The unique ID of the invitation to retrieve. required: true style: simple explode: false schema: type: string responses: "200": description: An `Invitation` representing the invitation that was located. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_13' "404": description: A status indicating the invitation could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' delete: tags: - Invitations summary: Delete Invitation description: | Delete an invitation by unique ID address, immediately invalidating it for acceptance. operationId: deleteInvitationById parameters: - name: id in: path description: The unique ID of the invitation to revoke. required: true style: simple explode: false schema: type: string responses: "200": description: An `Invitation` representing the invitation that was deleted. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_13' "404": description: A status indicating the invitation could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' /invitations/find: get: tags: - Invitations summary: Find Invitation description: | Retrieve information on a specific invitation, searching by a provided email address. operationId: findInvitation parameters: - name: email in: query description: The email address to search for. required: true style: form explode: true schema: type: string responses: "200": description: An `Invitation` representing the invitation that was located. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_13' "404": description: A status indicating the invitation could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' /invitations/resend: post: tags: - Invitations summary: Resend Invitation by Email description: | Resend an invitation to a specified email address if that invitation has not yet been accepted. operationId: postResendInvitationByEmail requestBody: content: application/json: schema: $ref: '#/components/schemas/invitations_resend_body' responses: "200": description: An `Invitation` representing the invitation that was resent. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_13' "404": description: A status indicating the invitation could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' "422": description: A status indicating validation failures with the submission. content: application/json: schema: $ref: '#/components/schemas/inline_response_422' /invitations/resend/{id}: post: tags: - Invitations summary: Resend Invitation description: | Resend an invitation identified by Cardly's unique ID. operationId: postResendInvitationById parameters: - name: id in: path description: The unique ID to the invitation to resend. required: true style: simple explode: false schema: type: string responses: "200": description: An `Invitation` representing the invitation that was resent. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_13' "404": description: A status indicating the invitation could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' /media: get: tags: - Media summary: List Media description: | Retrieve the currently available media sizes for product artwork. This request accepts standard pagination options `limit, offset` along with the following additional filters: operationId: getMediaListing parameters: - name: organisationOnly in: query description: | If truthy, only return media items that are exclusive to your organisation. required: false style: form explode: true schema: type: boolean responses: "200": description: A paginated array of zero or more `Media` objects. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_14' /orders: get: tags: - Orders summary: List Orders description: | Retrieve orders placed by your organisation. operationId: getOrderListing responses: "200": description: A paginated array of zero or more `Order` objects. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_15' /orders/{id}: get: tags: - Orders summary: Retrieve Order description: | Retrieve information on a specific order. operationId: getOrderById parameters: - name: id in: path description: The unique ID of the order to retrieve. required: true style: simple explode: false schema: type: string responses: "200": description: An `Order` representing the order that was requested. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_16' "404": description: A status indicating the order could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' /orders/preview: post: tags: - Orders summary: Generate Preview description: | 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. operationId: postOrderPreview requestBody: content: application/json: schema: $ref: '#/components/schemas/orders_preview_body' responses: "200": description: A description of your current account credit and gift credit balances, along with links to the relevant preview documents for your request. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_17' "422": description: A status indicating validation failures with the submission. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' /orders/place: post: tags: - Orders summary: Place Order description: | 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. operationId: postOrderPlace requestBody: content: application/json: schema: $ref: '#/components/schemas/orders_place_body' responses: "200": description: An `Order` representing the order that was created. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_18' "402": description: A status indicating that your account requires additional credit to place this order. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' "422": description: A status indicating validation failures with the submission. content: application/json: schema: $ref: '#/components/schemas/inline_response_422' /templates: get: tags: - Templates summary: List Templates description: | Retrieve your currently available templates. operationId: getTemplateListing responses: "200": description: A paginated array of zero or more `Template` objects. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_19' /users: get: tags: - Users summary: List Users description: | Retrieve active users for your organisation. operationId: getUserListing responses: "200": description: A paginated array of zero or more `User` objects. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_20' delete: tags: - Users summary: Delete User by Email description: | Delete a user by email address, immediately revoking their access to your organisation portal. **Please note:** Access can not be removed for users with `administrator` privileges on your account. These must be removed via your portal directly. operationId: deleteUserByEmail requestBody: content: application/json: schema: $ref: '#/components/schemas/users_body' responses: "200": description: An `User` representing the user that was deleted. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_21' "404": description: A status indicating a matching user could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' /users/{id}: get: tags: - Users summary: Retrieve User description: | Retrieve information on a specific user, identified by Cardly's unique identifier for the record. operationId: getUserById parameters: - name: id in: path description: The unique ID of the user to retrieve. required: true style: simple explode: false schema: type: string responses: "200": description: An `User` representing the user that was located. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_21' "404": description: A status indicating the user could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' delete: tags: - Users summary: Delete user description: | Delete a user by unique ID address, immediately revoking their access to your organisation portal. **Please note:** Access can not be removed for users with `administrator` privileges on your account. These must be removed via your portal directly. operationId: deleteUserById parameters: - name: id in: path description: The unique ID of the user to revoke. required: true style: simple explode: false schema: type: string responses: "200": description: A `User` representing the invitation that was deleted. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_21' "404": description: A status indicating the user could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' /users/find: get: tags: - Users summary: Find User description: | Retrieve information on a specific user, searching by a provided email address. operationId: findUser parameters: - name: email in: query description: The email address to search for. required: true style: form explode: true schema: type: string responses: "200": description: An `User` representing the user that was located. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_21' "404": description: A status indicating the user could not be found. content: application/json: schema: $ref: '#/components/schemas/inline_response_404' /writing-styles: get: tags: - Writing Styles summary: List Writing Styles description: | Retrieve your currently available writing styles. operationId: getWritingStyleListing responses: "200": description: A paginated array of zero or more `WritingStyle` objects. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_22' components: schemas: ResponseStatus: title: Response Status Object type: object properties: status: type: string description: Whether or not the request succeeeded without errors or warnings. example: OK enum: - OK - WARN - ERROR messages: type: array description: Any notifications, warnings or error messages relevant to the response. example: [] items: type: string version: type: integer description: The current build version of Cardly example: 1181 description: Provides a standard status identifier to indicate overall success, along with messages and the current API build version. ResponsePaginationMeta: title: Pagination Metadata Object type: object properties: orderBy: type: string description: The current field that results are ordered by. example: name orderDirection: type: string description: The direction results are ordered by, ascending or descending. example: asc enum: - asc - desc startRecord: type: integer description: The 1-based number of the first record in this result set, relative to the whole result set. example: 1 lastRecord: type: integer description: The 1-based number of the last record in this result set, relative to the whole result set. example: 25 limit: type: integer description: The maximum number of results per page. example: 25 page: type: integer description: The calculated page number for these results, based on supplied offset and limit values. example: 2 offset: type: integer description: The current number of records to offset the start of the result set by. example: 0 totalRecords: type: integer description: The total number of results in the entire set based on your query parameters. example: 123 description: Provides a standard description of a listing result set and the records that were retrieved. ValidationStatus: title: Validation Status Object type: object properties: email: type: string description: A reason the identified key's value has failed validation. example: This value should be a valid email address. description: One or more elements denoting validations failures with the named field(s), and the reason for failure. Artwork: title: Artwork Object type: object properties: id: type: string description: Unique identifier for this piece of artwork. To be passed through to `Place Order` and similar calls requiring artwork IDs. example: 484ed6af-416e-1f76-7807-c88104734f09 x-subtype: uuid revision: type: integer description: The revision number of this piece of artwork. Revision increases when artwork descriptors or image assets change. example: 8 name: type: string description: The title of this piece of artwork. example: API Artwork Upload slug: type: string description: 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`. example: api-artwork-upload fullPath: type: string description: The full SEO path to this artwork, which can be used as an alternate identifier when placing orders, generating previews etc. example: /pied-piper/api-artwork-upload description: type: string description: A longer description of the artwork. example: Testing adding a 4p card via API call. artwork: type: array description: A list of URLs for preview images of each page in the artwork document, without customisations. Any pages without artwork will return `null`. example: - 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 items: type: string x-subtype: url media: description: The media size associated with this piece of artwork. allOf: - $ref: '#/components/schemas/Media' createdAt: type: string description: | `YYYY-MM-DDTHH:ii:ss+00:00` formatted string to denote when this piece of artwork was created. format: date-time example: 2020-06-14T09:40:09+10:00 updatedAt: type: string description: | `YYYY-MM-DDTHH:ii:ss+00:00` formatted string to denote when this piece of artwork was last updated. format: date-time example: 2020-06-14T14:39:35+10:00 description: The artwork object represents a product at a given media size and provides preview images for each page capable of hosting artwork imagery. Contact: title: Contact Object type: object properties: id: type: string description: Unique identifier for this contact. example: 23fb4b1c-f127-eeea-9f68-6f0a7945da43 x-subtype: uuid externalId: type: string description: Any external identifier you have supplied for this contact which can be used to update this contact in future calls. example: thor1234 contactListId: type: string description: Identifier for the contact list this contact belongs to. example: b905e966-ecdf-9656-2564-049c334a4db3 x-subtype: uuid status: type: string description: Current state of this contact. example: active firstName: type: string description: The first name of a contact. example: Thor lastName: type: string description: The last name of a contact, if supplied. example: Odinson fullName: type: string description: The contact's full name, a combination of firstName & lastName. example: Thor Odinson email: type: string description: An email address for this contact, if supplied, which can be used to uniquely identify this contact for subsequent actions. example: thor@avengers.com company: type: string description: The company a contact belongs to, if supplied. example: Avengers Inc. address: type: string description: The primary address line. example: 1 Main Street address2: type: string description: A secondary address line, typically containing a unit, apartment, suite number etc. locality: type: string description: A suburb or city for the contact. example: Brooklyn adminAreaLevel1: type: string description: The state or province for this contact. example: NY country: type: string description: A 2-character ISO code identifying the contact's country. example: US postcode: type: string description: A postal code or ZIP code for this contact, where required by local addressing formats. example: "12345" latitude: type: number description: Geo coordinates for this address, if it has been resolved with address lookups. format: float example: 40.761635 longitude: type: number description: Geo coordinates for this address, if it has been resolved with address lookups. format: float example: -73.971802 rawAddress: type: string description: If a full, raw address was supplied for this contact, the original address as supplied by spreadsheet upload or application. example: 1 Main Street, Brooklyn, New York, USA requiresAction: type: boolean description: If this contact was subject to address validation, whether this record requires manual intervention to resolve. example: false fields: type: object description: Additional custom fields based on field codes for extended data on this contact record. example: birthday: 1052-04-01 homepage: https://www.avengers.com/profile/thor description: 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. ContactList: title: Contact List Object type: object properties: id: type: string description: Unique identifier for this contact list. example: 6d7c260b-f39f-e822-6aa5-612014047d20 x-subtype: uuid name: type: string description: The human-readable name for this list. example: Online Sales description: type: string description: An extended description on what this list is for or related notes, if required. example: All customers purchased since 2017-01-01 status: type: string description: The current status of this contact list. example: active contacts: type: integer description: The number of unique contacts currently in this list. example: 154 automations: type: integer description: The number of automation rules (active or disabled) currently applied to this list. example: 3 fields: type: array description: List of `ContactListField` items that define additional information to store for each contact in the list. items: $ref: '#/components/schemas/ContactListField' rules: type: array description: List of `ContactListRule` items that define rules to automatically send cards at specified intervals or based on triggers set up in the Cardly platform. items: $ref: '#/components/schemas/ContactListRule' validation: $ref: '#/components/schemas/ContactList_validation' description: The contact list object provides detail on a given list on your account, along with currently set up custom fields and automation details. ContactListField: title: Contact List Field type: object properties: id: type: string description: A unique identifier for this field which never changes. example: 9da307a4-1c37-f69a-c6ec-1ba002165d57 x-subtype: uuid code: type: string description: 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. example: dateField name: type: string description: A human-readable label for this field. example: Date Field description: type: string description: Extended information about this field, if required. type: type: string description: The type of field this is, currently one of `text`, `date` or `number`. example: date enum: - text - date - number status: type: string description: The status of this field - currently always `active`. example: active description: The contact list field object defines additional, custom fields to be applied to all contacts within a list. ContactListRule: title: Contact List Rule type: object properties: id: type: string description: A unique identifier for this rule which never changes. example: 45702de2-dee0-2b14-ed52-ae63886f28f1 x-subtype: uuid fieldId: type: string description: The field ID linked to this validation rule as a trigger. example: b9763d1b-e0fd-77a3-7afb-6edbf07fe087 cardArt: type: array description: A list of `Artwork` entries to use for sends. items: $ref: '#/components/schemas/Artwork' templateId: type: string description: The template to use for this rule. example: cddf4ba9-747c-aee9-5373-6d985cbfb198 enabled: type: boolean description: Whether or not this automation is currently enabled for sending. example: true name: type: string description: A human-readable name for this automation rule. example: Trigger When Number Field Zero description: type: string description: Extended information on this rule, if required. operator: type: string description: The type of comparison (eq, db, da, etc) to apply to the trigger field. example: eq value: type: number description: The value to compare to in order to evaluate whether the trigger has succeeded or not. example: 0 annual: type: boolean description: If true and linked to a `date` field, this automation will trigger yearly (ie, for birthday or anniversary type events). example: true bindings: $ref: '#/components/schemas/ContactListRule_bindings' description: A contact list rule object describes tasks be performed automatically at specified intervals or based on triggers set up in the Cardly platform. CreditHistory: title: Credit History Object type: object properties: id: type: string description: Unique identifier for this credit history entry. example: 484ed6af-416e-1f76-7807-c88104734f09 x-subtype: uuid orderId: type: string description: Identifier for an order that triggered this credit history entry. Generally used whenever paid transactions take place. example: 7807d6af-484e-c881-1f76-416e04734f09 x-subtype: uuid transactionId: type: string description: Identifier for a transaction that triggered this credit history entry, typically related to the purchase of credits. example: f47b838a-304d-f88c-4d2c-a8709cacfdc8 x-subtype: uuid type: type: string description: | A human-readable, brief description of what this entry is for, ie; `Credit Purchase`, `Order Placement`. example: Signup Bonus typeCode: type: string description: A short code to denote the type of change this was. example: C enum: - A - C - D - E - P - R - S change: type: number description: Value that was either credited or debited from the organisation in this action. format: float example: 3 newBalance: type: number description: The current account credit balance at the time this change was effected. format: float example: 15.5 effectiveTime: type: string description: Timestamp of when this credit history entry occurred. example: 2019-11-23 12:10:54 notes: type: string description: An extended description of what effected this balance change. example: Payment for order 1bb30e7f-afde-b822-762a-ecd5c2dc1c40 lodged at 21/11/2022 10:31:36 description: The credit history object models an entry - positive or negative - for the organisation's credit purchase and spends. Doodle: title: Doodle Object type: object properties: id: type: string description: Unique identifier for this doodle. example: 31035c6a-9311-15aa-638e-6894acb0e668 x-subtype: uuid name: type: string description: The human-readable name for this doodle. example: 4WD Car slug: type: string description: A human-readable identifier for this doodle. example: 4wd-car description: type: string description: An optional description of this doodle. image: type: string description: A URL to a preview image of this doodle. example: https://www.cardly.net/doodle/preview/31035c6a-9311-15aa-638e-6894acb0e668 x-subtype: url dimensions: $ref: '#/components/schemas/Doodle_dimensions' restricted: type: boolean description: Whether or not this doodle is exclusive to your organisation, or freely available across the Cardly platform. example: false description: The doodle object represents a vector-based image which can be included within card artwork. Font: title: Font Object type: object properties: id: type: string description: Unique identifier for this font option. example: 461910d8-ff8c-ee8d-efe5-d5feb3f9113a x-subtype: uuid name: type: string description: A localised, human-readable name for this font. example: Brad category: type: string description: The category of writing this font falls into, one of `cursive`, `hand`, `serif`, `sans` or `mono`. example: hand enum: - cursive - hand - serif - sans - mono familyVariants: type: integer description: The number of font variants this family contains for each character. example: 3 canHumanise: type: boolean description: Whether or not this font is marked for being eligible for humanisation techniques. Typically, screen or machine-readable fonts have this flagged off. example: true restricted: type: boolean description: Whether or not this font is exclusive to your organisation, or freely available across the Cardly platform. example: false description: The font object models a style of writing available within Cardly, either from our shared library or your exclusive handwriting conversions. GiftCreditHistory: title: Gift Credit History Object type: object properties: id: type: string description: Unique identifier for this gift credit history entry. example: 484ed6af-416e-1f76-7807-c88104734f09 x-subtype: uuid orderId: type: string description: Identifier for an order that triggered this gift credit history entry. Generally used whenever paid transactions take place. example: 7807d6af-484e-c881-1f76-416e04734f09 x-subtype: uuid transactionId: type: string description: Identifier for a transaction that triggered this gift credit history entry, typically related to the purchase of credit. example: f47b838a-304d-f88c-4d2c-a8709cacfdc8 x-subtype: uuid type: type: string description: | A human-readable, brief description of what this entry is for, ie; `Credit Purchase`, `Order Placement`. example: Signup Bonus typeCode: type: string description: A short code to denote the type of change this was. example: C enum: - A - C - D - E - P - R - S change: type: number description: Value that was either credited or debited from the organisation in this action. format: float example: 33 changeNet: type: number description: Value that was either credited or debited from the organisation in this action, exclusive of tax. format: float example: 30 changeTax: type: number description: "Tax component for this transaction, were relevant. \n\n**Note:** currently, no region involves taxed gift card payments.\n" format: float example: 3 newBalance: type: number description: The current account gift credit balance at the time this change was effected. format: float example: 15.5 effectiveTime: type: string description: Timestamp of when this gift credit history entry occurred. example: 2019-11-23 12:10:54 x-subtype: datetime notes: type: string description: An extended description of what effected this balance change. example: Payment for order 1bb30e7f-afde-b822-762a-ecd5c2dc1c40 lodged at 21/11/2022 10:31:36 description: The gift credit history object models an entry - positive or negative - for the organisation's gift credit purchase and spends. Invitation: title: Invitation Object type: object properties: id: type: string description: Unique identifier for this invitation. example: 8d207658-12fc-6068-23fe-09135f7b31f1 x-subtype: uuid firstName: type: string description: The invited user's first name, if known. example: Thor lastName: type: string description: The invited user's last name, if known. example: Odinson email: type: string description: The invited user's email address. example: thor@avengers.com status: type: string description: The current status of this invitation. example: invited permissions: $ref: '#/components/schemas/Invitation_permissions' invited: type: string description: When the invitation was created. example: 2022-03-14 12:34:27 x-subtype: datetime inviteSent: type: string description: When the user's email invitation was sent. example: 2021-03-14 12:35:53 x-subtype: datetime accepted: type: string description: When the invitation was accepted, if at all. x-subtype: datetime expires: type: string description: When the invitation expires. example: 2021-03-17 12:35:01 x-subtype: datetime links: $ref: '#/components/schemas/Invitation_links' description: The invitation object provides detail on user that's been invited to your account and the status of that invitation. Media: title: Media Object type: object properties: id: type: string description: 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 x-subtype: uuid name: type: string description: A localised, human-readable name for this product. example: Standard Postcard description: type: string description: A longer description of the product, along with any restrictions or important information. example: Standard postcard for all locales. creditCost: type: number description: The number of credits that would be consumed when ordering this media type. format: float example: 0.6 pages: type: integer description: 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: $ref: '#/components/schemas/Media_dimensions' bleed: $ref: '#/components/schemas/Media_bleed' art: $ref: '#/components/schemas/Media_art' description: 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. Order: title: Order Object type: object properties: id: type: string description: Unique identifier for this order. example: c988c0c0-f6a3-4e90-bbd5-759497a82607 x-subtype: uuid status: type: string description: The current status of this order. example: paid origin: type: string description: Where the order originated - via the API, your organisation portal, etc. example: api customer: description: Details about the organisation or user that placed this order. For API-originating orders, this will be your organisation details. allOf: - $ref: '#/components/schemas/OrderCustomer' costs: description: Contains details of the overall order costs. allOf: - $ref: '#/components/schemas/OrderCosts' timings: description: Contains details of the overall order creation, update and payment times. allOf: - $ref: '#/components/schemas/OrderTimings' items: type: array description: List of `OrderItem` records that comprise this order. items: $ref: '#/components/schemas/OrderItem' description: The order object provides detail on a given order on your account, along with individual line item recipient, sender, cost and timing information. OrderCosts: title: Order Costs Object type: object properties: credits: type: number description: The total credits this order consumed, if paid by credits. format: float example: 0.5 giftCredit: type: number description: TheThe total gift credits this order consumed, if paid by credits. format: float example: 45.67 gross: type: number description: The gross cost of this order, exclusive of tax. format: float example: 6.58 discount: type: number description: The discount amount for this order overall. format: float example: 0.98 tax: type: number description: The total amount of tax on this order, exclusive of shipping. format: float example: 0.69 shipping: type: number description: The total tax-exclusive cost of shipping for this order. format: float example: 1.54 shippingTax: type: number description: The total amount of tax applied to shipping. format: float example: 0.15 total: type: number description: The total cost of this order. format: float example: 7.98 currency: type: string description: The currency this order was priced in. example: USD description: Describes the costs of the order as a whole, whether paid by credits or real currency. Note that only credit/giftCredit elements are only present and other fields (gross, discount, etc) are omitted if paid for via credits. The reverse is also true if paid for via real currency - credits/giftCredit fields will be omitted, while the others will be present. OrderCustomer: title: Order Customer Details Object type: object properties: firstName: type: string description: The customer's first name. example: Thor lastName: type: string description: The customer's last name. example: Thor address: type: string description: The primary address line example: 1 Main Street address2: type: string description: The sub-premises level of the address, where required. example: Suite 1054 city: type: string description: The suburb/city level of an address. example: Brooklyn region: type: string description: The state/province/region level abbreviation such as NY, QC, QLD for US, Canadian or Australian addresses, or the full region name for other countries. Note that this may be empty for countries which do not utilise the region level for addressing. example: NY postcode: type: string description: The postcode for this address. Note that this may be empty for countries that do not utilise postcodes. example: "12345" country: type: string description: The 2-character ISO code for the country relating to this address. example: US email: type: string description: The contact email address fro the customer. example: thor@avengers.com purchaseOrderNo: type: string description: A customer supplied purchase order number, if relevant. example: AVG01145 notes: type: string description: Any additional notes for this order to pass on to the production team. example: Please pack carefully! description: Details about the organisation or user that placed this order. For API-originating orders, this will be your organisation details. OrderTimings: title: Order Timings Object type: object properties: created: type: string description: When this order was first raised. example: 2024-12-04 11:11:41 x-subtype: datetime paid: type: string description: When this order was paid - if currently marked as paid. example: 2024-12-04 11:11:41 x-subtype: datetime updated: type: string description: When this order was last updated. example: 2024-12-04 12:11:46 x-subtype: datetime description: Contains details of the overall order creation, update and payment times. OrderItem: title: Order Item Object type: object properties: id: type: string description: Unique identifier for this order item. example: 60051a2c-86af-45bb-a34f-febf37d9070c x-subtype: uuid type: type: string description: The type of item this is - typically `card`. example: card media: type: string description: The media ID relevant to this item, if a printed card/letter. example: 51897b27-81d6-e82b-dcfe-36f748d516e9 x-subtype: uuid artwork: type: string description: The artwork ID relevant to this item, if a printed card/letter. example: 5c40d96b-b7c3-4980-9bdc-14306104ebd4 x-subtype: uuid template: type: string description: The template ID relevant to this item, if a printed card/letter. example: 73bf3d63-5bca-45dc-86f6-d5c01946d78b x-subtype: uuid label: type: string description: A description of this item, typically the card artwork title. example: Cardly - Happy Birthday quantity: type: integer description: The number of units of this item that were ordered. example: 1 costs: description: The total cost of this item, whether paid by credits or real currency. allOf: - $ref: '#/components/schemas/OrderItemCosts' shipTo: type: string description: Either `S` for shipping back to the sender, or `D` for shipping direct to the customer. example: D shipMethod: type: string description: The shipping method used, one of `standard`, `tracked` or `express`. example: standard enum: - standard - tracked - express scheduledDate: type: string description: If requested at order time, the date this item was requested to arrive by. example: 2024-12-25 recipient: description: The recipient's address details for this item. allOf: - $ref: '#/components/schemas/OrderItemAddress' sender: description: The sender's address details for this item. allOf: - $ref: '#/components/schemas/OrderItemAddress' delivery: description: Requested delivery timings and estimated delivery windows for this item. allOf: - $ref: '#/components/schemas/OrderItemDelivery' timings: description: Lodgement, production and shipping timing information for this item. allOf: - $ref: '#/components/schemas/OrderItemTimings' tracking: description: Tracking information related to this item, if relevant to the shipping method. allOf: - $ref: '#/components/schemas/OrderItemTracking' related: type: array description: A list of related items for this one, such as gift cards and additional envelopes where required. items: $ref: '#/components/schemas/OrderItemRelated' description: 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). OrderItemRelated: title: Related Item Object type: object properties: id: type: string description: Unique identifier for this order item. example: 60051a2c-86af-45bb-a34f-febf37d9070c x-subtype: uuid type: type: string description: The type of item this is - typically `gift-card` or `envelope`. example: card enum: - gift-card - envelope label: type: string description: A description of this item, typically the card artwork title. example: Cardly - Happy Birthday quantity: type: integer description: The number of units of this item that were ordered. example: 1 costs: description: The total cost of this item, whether paid by credits or real currency. allOf: - $ref: '#/components/schemas/OrderItemCosts' description: A component of a parent OrderItem, such as an additional envelope or gift card. OrderItemAddress: title: Order Item Address Object type: object properties: name: type: string description: The primary addressee's name. example: Thor Odinson company: type: string description: An optional company line, where relevant. May be blank. example: Avengers Inc address: type: string description: The primary address line example: 1 Main Street address2: type: string description: The sub-premises level of the address, where required. example: Suite 1054 city: type: string description: The suburb/city level of an address. example: Brooklyn region: type: string description: The state/province/region level abbreviation such as NY, QC, QLD for US, Canadian or Australian addresses, or the full region name for other countries. Note that this may be empty for countries which do not utilise the region level for addressing. example: NY postcode: type: string description: The postcode for this address. Note that this may be empty for countries that do not utilise postcodes. example: "12345" country: type: string description: The 2-character ISO code for the country relating to this address. example: US omitAddress: type: boolean description: Conditionally present if this address should be omitted from envelopes. Only used for sender addresses. example: false description: Describes an addressing element such as sender or recipient or for a given order item. OrderItemCosts: title: Order Item Costs Object type: object properties: credits: type: number description: The total credits this item consumed, if paid by credits. format: float example: 0.5 giftCredit: type: number description: The amount of gift credit used for this item in the order's currency, if relevant. format: float example: 45.67 gross: type: number description: The gross unit cost of this item, exclusive of tax. format: float example: 6.58 discount: type: number description: The discount amount per unit for this item. format: float example: 0.98 tax: type: number description: The amount of tax per unit on this item, exclusive of shipping. format: float example: 0.69 shipping: type: number description: The per-unit tax-exclusive cost of shipping for this item. format: float example: 1.54 shippingTax: type: number description: The amount per unit of tax applied to shipping. format: float example: 0.15 total: type: number description: The final per unit cost, inclusive of tax, shipping and discounts for this item. format: float example: 7.98 currency: type: string description: The currency this item was priced in. example: USD description: Describes the costs of an individual line item within an order, whether paid by credits or real currency. Note that only credit/giftCredit elements are only present and other fields (gross, discount, etc) are omitted if paid for via credits. The reverse is also true if paid for via real currency - credits/giftCredit fields will be omitted, while the others will be present. OrderItemDelivery: title: Order Item Delivery Details type: object properties: requested: type: string description: The arrival date requested, if applicable. This will be null where you did not specify a requested delivery date. example: 2024-12-25 x-subtype: date dispatch: type: string description: 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-12 x-subtype: date estimatedMinArrival: type: string description: "The estimated earliest date an order should be received. \n\n**Note that this is subject to end postal carriers** and beyond the control of Cardly directly.\n" example: 2024-12-17 x-subtype: date estimatedMaxArrival: type: string description: "The estimated latest date an order should be received. \n\n**Note that this is subject to end postal carriers** and beyond the control of Cardly directly.\n" example: 2024-12-20 x-subtype: date description: Describes requested and estimated delivery windows for a given item. OrderItemTimings: title: Order Item Timings Object type: object properties: lodgeAfter: type: string description: The scheduled time for sending this item to print. Lodgement will always occur after this time. example: 2024-12-04 11:12:00 x-subtype: datetime lodged: type: string description: When this item was sent to print. example: 2024-12-04 11:24:41 x-subtype: datetime shipped: type: string description: "When this item was shipped. \n\n**Please note:** We rely on external data to populate this and it may not always be immediately available.\n" example: 2024-12-04 12:11:46 x-subtype: datetime held: type: string description: If this item is being held, the time the item was marked for holding. example: 2024-12-04 12:06:46 x-subtype: datetime description: Describes various timings within an card's lifecycle, from request to lodgement, production and dispatch. OrderItemTracking: title: Order Item Tracking Object type: object properties: carrier: type: string description: The name of the carrier for orders with tracking. example: USPS code: type: string description: The tracking code provided by the carrier for a given consignment. example: "056116819325" link: type: string description: Carrier's URL where applicable to view tracking information for this consignment. example: http://tracking.usps.com/consigment/056116819325 description: Describes requested and estimated delivery windows for a given item. Style: title: Style Object type: object properties: align: type: string description: One of `left` (default) or `center` to denote text flow behaviour. example: left enum: - left - center color: type: string description: RRGGBB hex code (without the hash mark) denoting the colour to use for text or doodle elements. example: 1144a7 font: type: string description: 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: type: integer description: 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: type: string description: | 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 enum: - top - center - bottom writing: type: string description: 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 description: 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. Template: title: Template Object type: object properties: id: type: string description: Unique identifier for this template option. example: 18ecf6e6-d2e2-49cb-bae0-fa980241db73 x-subtype: uuid name: type: string description: The human-readable description for this template. example: Happy Birthday slug: type: string description: A human-readable identifier for this template unique within your organisation. example: happy-birthday generic: type: boolean description: Whether or not there are any active variables within your template design. `true` if no variables are active. example: false media: description: The media object that represents the media size associated with this template. allOf: - $ref: '#/components/schemas/Media' giftCard: $ref: '#/components/schemas/Template_giftCard' definition: $ref: '#/components/schemas/Template_definition' createdAt: type: string description: | `YYYY-MM-DDTHH:ii:ss+00:00` formatted string to denote when this template was created. format: date-time example: 2020-06-14T09:40:09+10:00 updatedAt: type: string description: | `YYYY-MM-DDTHH:ii:ss+00:00` formatted string to denote when this template was last updated. format: date-time example: 2020-06-14T14:39:35+10:00 description: The template object denotes styling and structure to be applied to a given media size card. User: title: User Object type: object properties: id: type: string description: Unique identifier for this user. example: 8d207658-12fc-6068-23fe-09135f7b31f1 x-subtype: uuid firstName: type: string description: The user's first name, if known. example: Thor lastName: type: string description: The user's last name, if known. example: Odinson email: type: string description: The user's email address. example: thor@avengers.com status: type: string description: The current status of this user. example: active permissions: $ref: '#/components/schemas/User_permissions' description: The user object provides detail on user has accepted an invitation to use your to your account. WritingStyle: title: Writing Style Object type: object properties: id: type: string description: Unique identifier for this writing style option. example: 18ecf6e6-d2e2-49cb-bae0-fa980241db73 x-subtype: uuid name: type: string description: A human-readable name for this writing style. example: Perfection description: type: string description: A description of this writing style. example: No humanisation applied at all, absolutely perfect writing. order: type: string description: Unique identifier for this template option. example: "0" description: The writing object denotes a messiness level applied to our algorithmic handwriting generation. echo_body: required: - none type: object properties: foo: type: string description: A body parameter which will be returned to you example: bar bar: type: array description: A body parameter which will be returned to you example: - A - B - C items: type: string inline_response_200: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_data' inline_response_200_1: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_1_data' inline_response_200_2: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_2_data' inline_response_200_3: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_3_data' inline_response_200_4: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_4_data' art_artwork: type: object properties: page: type: integer description: 1-based identifier for the page this artwork file relates to. 1 identifies the front page, each subsequent page is identified in reading order. image: type: string description: Base64 encoded string containing the content of the image file. art_body: required: - artwork - media - name type: object properties: media: type: string description: UUID for the media this artwork will use. example: fd7368b0-ad4d-11ea-9da9-04d4c4254e1b x-subtype: uuid name: type: string description: A short description for this artwork. example: API Artwork Upload description: type: string description: A longer human-readable description of the artwork. example: Testing adding a 4p card via API call. artwork: type: array description: A list of pages and associated images to attach to this artwork. example: - page: 1 image: iVBORw0KGg... - page: 3 image: iVBORw0KGg... items: $ref: '#/components/schemas/art_artwork' inline_response_200_5: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/Artwork' inline_response_422: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/ValidationStatus' inline_response_404: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' art_id_body: type: object properties: name: type: string description: A short description for this artwork. example: API Artwork Update description: type: string description: A longer human-readable description of the artwork. example: Testing updating a 4p card via API call. artwork: type: array description: A list of pages and associated images to attach to this artwork. example: - page: 1 image: iVBORw0KGg... - page: 3 image: iVBORw0KGg... items: $ref: '#/components/schemas/art_artwork' x-conditionallyRequired: - name - description - artwork inline_response_200_6: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_6_data' contactlists_fields: type: object properties: name: type: string description: A short name for this field, which will be used to create a unique field identifier if this field doesn't already exist. description: type: string description: A longer description of this field, if required. type: type: string description: The type of data this field models, one of `text`, `date`, `number` or `url`. enum: - text - date - number - url contactlists_body: required: - name type: object properties: name: type: string description: A short description for this contact list to allow it to be identified. example: Employee Birthdays description: type: string description: A free-text description of this list to store whatever additional information might be necesssary. example: Current employee birthdays for all staff. fields: type: array description: 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. example: - name: Birthday type: date image: iVBORw0KGg... - name: Preferred Name type: text description: The customer's preferred name when we address them. items: $ref: '#/components/schemas/contactlists_fields' inline_response_200_7: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/ContactList' contactlistsid_fields: type: object properties: id: type: string description: The identifier of an existing field to update or remove. x-subtype: uuid name: type: string description: | A short name for this field, which will be used to create a unique field identifier if this field doesn't already exist. **Required** if adding a new field. description: type: string description: A longer description of this field, if required. type: type: string description: | The type of data this field models, one of text, date, number or url. **Required** if adding a new field. **Ignored** if updating an existing field. enum: - text - date - number - url remove: type: boolean description: If set to true, removes this field from the list. contactlists_id_body: required: - name type: object properties: name: type: string description: A short description for this contact list to allow it to be identified. example: Employee Birthdays description: type: string description: A free-text description of this list to store whatever additional information might be necesssary. example: Current employee birthdays for all staff. fields: type: array description: 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. example: - id: 58255904-7cbf-4421-9af7-c2dac50e4a91 remove: true - name: Birthday type: date - name: Preferred Name type: text description: The customer's preferred name when we address them. items: $ref: '#/components/schemas/contactlistsid_fields' inline_response_200_8: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_8_data' listId_contacts_body: required: - address - country - firstName - locality - postcode - region type: object properties: externalId: type: string description: Any external identifier you have supplied for this contact which can be used to update this contact in future calls. example: thor1234 firstName: type: string description: The first name of a contact. example: Thor lastName: type: string description: The last name of a contact, if known / applicable. example: Odinson email: type: string description: An email address for this contact, if supplied, which can be used to uniquely identify this contact for subsequent actions. example: thor@avengers.com company: type: string description: The company a contact belongs to, if required. example: Avengers Inc. address: type: string description: The primary address line, including street number, name and type. example: 1 Main Street address2: type: string description: A secondary address line, typically containing a unit, apartment, suite number etc. example: Suite 1451 locality: type: string description: A suburb or city for the contact. example: Brooklyn region: type: string description: "The state or province for this address. \n\n**Conditionally required** based on the country supplied.\n" example: NY country: type: string description: A 2-character ISO code identifying the contact's country. example: US postcode: type: string description: "A postal code or ZIP code for this contact, where required by local addressing formats. \n\n**Conditionally required** based on the country supplied.\n" example: "12345" fields: type: object description: | Additional custom fields based on field codes for extended data on this contact record. 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). example: birthday: 1052-04-01 homepage: https://www.avengers.com/profile/thor inline_response_200_9: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/Contact' listId_contacts_body_1: type: object properties: email: type: string description: An email address to identify the contact to delete, if no external ID is supplied. example: thor@avengers.com externalId: type: string description: Any external identifier to identify the contact to delete, if no email address is supplied. example: thor1234 contacts_id_body: required: - address - country - firstName - locality - postcode - region type: object properties: externalId: type: string description: Any external identifier you have supplied for this contact which can be used to update this contact in future calls. example: thor1234 firstName: type: string description: The first name of a contact. example: Thor lastName: type: string description: The last name of a contact, if known / applicable. example: Odinson email: type: string description: An email address for this contact, if supplied, which can be used to uniquely identify this contact for subsequent actions. example: thor@avengers.com company: type: string description: The company a contact belongs to, if required. example: Avengers Inc. address: type: string description: The primary address line, including street number, name and type. example: 1 Main Street address2: type: string description: A secondary address line, typically containing a unit, apartment, suite number etc. example: Suite 1451 locality: type: string description: A suburb or city for the contact. example: Brooklyn region: type: string description: "The state or province for this address. \n\n**Conditionally required** based on the country supplied.\n" example: NY country: type: string description: A 2-character ISO code identifying the contact's country. example: US postcode: type: string description: "A postal code or ZIP code for this contact, where required by local addressing formats. \n\n**Conditionally required** based on the country supplied.\n" example: "12345" fields: type: object description: | Additional custom fields based on field codes for extended data on this contact record. 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). example: birthday: 1052-04-01 homepage: https://www.avengers.com/profile/thor contacts_sync_body: required: - address - country - firstName - locality - postcode - region type: object properties: externalId: type: string description: | Any external identifier you have supplied for this contact which can be used to update this contact in future calls. **Conditionally required:** At least one of `externalId` or `email` is required for a sync operation. example: thor1234 firstName: type: string description: The first name of a contact. example: Thor lastName: type: string description: The last name of a contact, if known / applicable. example: Odinson email: type: string description: | An email address for this contact, if supplied, which can be used to uniquely identify this contact for subsequent actions. **Conditionally required:** At least one of `externalId` or `email` is required for a sync operation. example: thor@avengers.com company: type: string description: The company a contact belongs to, if required. example: Avengers Inc. address: type: string description: The primary address line, including street number, name and type. example: 1 Main Street address2: type: string description: A secondary address line, typically containing a unit, apartment, suite number etc. example: Suite 1451 locality: type: string description: A suburb or city for the contact. example: Brooklyn region: type: string description: "The state or province for this address. \n\n**Conditionally required** based on the country supplied.\n" example: NY country: type: string description: A 2-character ISO code identifying the contact's country. example: US postcode: type: string description: "A postal code or ZIP code for this contact, where required by local addressing formats. \n\n**Conditionally required** based on the country supplied.\n" example: "12345" fields: type: object description: | Additional custom fields based on field codes for extended data on this contact record. 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). example: birthday: 1052-04-01 homepage: https://www.avengers.com/profile/thor inline_response_200_10: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_10_data' inline_response_200_11: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_11_data' inline_response_200_12: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_12_data' invitations_body: required: - email type: object properties: firstName: type: string description: The first name of the user. example: Thor lastName: type: string description: The last name of the user. example: Odinson email: type: string description: An email address for this user. example: thor@avengers.com permissions: type: array description: | 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` example: - use-credits - use-gift-credits - use-saved-card items: type: string inline_response_200_13: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/Invitation' invitations_body_1: type: object properties: email: type: string description: The email address to search for. example: thor@avengers.com invitations_resend_body: type: object properties: email: type: string description: The email address to search for. example: thor@avengers.com inline_response_200_14: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_14_data' inline_response_200_15: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_15_data' inline_response_200_16: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/Order' orderspreview_messages_pages: type: object properties: page: type: integer description: 1-based identifier for the page these settings relate to. 1 identifies the front page, each subsequent page is identified in reading order. text: type: string description: 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: description: | Page-level overrides for styling, if required. **Please note:** This should be used with care and thoroughly tested before you deploy your application to production. Cardly accepts no responsiblity for poorly designed cards when using this feature. allOf: - $ref: '#/components/schemas/Style' orderspreview_messages: type: object properties: pages: type: array 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 items: $ref: '#/components/schemas/orderspreview_messages_pages' description: Message data to inject when not utilising pre-built templates from your account. orderspreview_recipient: required: - address - city - country - firstName - postcode - region type: object properties: firstName: type: string description: The recipient's first name, as it should appear on the envelope. example: Thor lastName: type: string description: The recipient's last name, as it should appear on the envelope example: Thor company: type: string description: The recipient's company, if required, as it should appear below their name on the envelope. example: Avengers Inc address: type: string description: The recipient's street number, name and type. example: 1 Main Street address2: type: string description: Unit, floor, apartment etc. additional information for the recipient's address. example: Suite 1054 city: type: string description: Suburb or city for the recipient. example: Brooklyn region: type: string description: | 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: type: string description: | 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: type: string description: The 2-character ISO code for the country relating to this recipient. example: US description: The recipient's addressing details, as they should appear on the envelope. orderspreview_sender: required: - address - city - country - firstName - postcode - region type: object properties: firstName: type: string description: The sender's first name, as it should appear on the envelope. example: Bruce lastName: type: string description: The sender's last name, as it should appear on the envelope example: Banner company: type: string description: The sender's company, if required, as it should appear below their name on the envelope. example: Avengers Inc address: type: string description: The sender's street number, name and type. example: 1 Main Street address2: type: string description: Unit, floor, apartment etc. additional information for the sender's address. example: Suite 1054 city: type: string description: Suburb or city for the sender. example: Brooklyn region: type: string description: | State / province / region for the sender, if required. UK and NZ currently do not require a region specified. **Conditionally required** based on the country supplied. example: NY postcode: type: string description: | The postcode for this sender. Note that this may be empty for countries that do not utilise postcodes. **Conditionally required** based on the country supplied. example: "12345" country: type: string description: The 2-character ISO code for the country relating to this sender. example: US omitAddress: type: boolean description: | `true` to omit the return address entirely from a generated envelope. description: | 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. orders_preview_body: required: - artwork - recipient type: object properties: artwork: type: string description: 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: type: string description: 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: description: | 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. We suggest using this feature with care. allOf: - $ref: '#/components/schemas/Style' messages: $ref: '#/components/schemas/orderspreview_messages' variables: type: object description: 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: $ref: '#/components/schemas/orderspreview_recipient' sender: $ref: '#/components/schemas/orderspreview_sender' shippingMethod: type: string description: | 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 enum: - standard - tracked - express shipToMe: type: boolean description: | 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: type: string description: 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 x-subtype: date purchaseOrderNumber: type: string description: 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 inline_response_200_17: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_17_data' ordersplace_recipient: required: - address - city - country - firstName type: object properties: firstName: type: string description: The recipient's first name, as it should appear on the envelope. example: Thor lastName: type: string description: The recipient's last name, as it should appear on the envelope example: Thor company: type: string description: The recipient's company, if required, as it should appear below their name on the envelope. example: Avengers Inc address: type: string description: The recipient's street number, name and type. example: 1 Main Street address2: type: string description: Unit, floor, apartment etc. additional information for the recipient's address. example: Suite 1054 city: type: string description: Suburb or city for the recipient. example: Brooklyn region: type: string description: | 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: type: string description: | 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: type: string description: The 2-character ISO code for the country relating to this recipient. example: US description: The recipient's addressing details, as they should appear on the envelope. ordersplace_lines: type: object properties: artwork: type: string description: 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: type: string description: 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 quantity: minimum: 1 type: integer description: "The number of copies of this item to request. \n\n**Please note:** that all copies will use the same template, variables etc specified in this order item so this should *not* be used where personalised cards are expected.\n" example: 1 default: 1 style: description: | 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. We suggest using this feature with care. allOf: - $ref: '#/components/schemas/Style' messages: $ref: '#/components/schemas/orderspreview_messages' variables: type: object description: 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: $ref: '#/components/schemas/ordersplace_recipient' sender: $ref: '#/components/schemas/orderspreview_sender' shippingMethod: type: string description: | 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 enum: - standard - tracked - express shipToMe: type: boolean description: | 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: type: string description: 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 x-subtype: date orders_place_body: required: - lines type: object properties: lines: required: - artwork - recipient type: array description: | A list of one or more of the below `OrderItem` structures to include into the overall order. items: $ref: '#/components/schemas/ordersplace_lines' purchaseOrderNumber: type: string description: A reference number to place against this order - useful to tie back to your existing systems for auditing. example: PO1234 inline_response_200_18: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_18_data' inline_response_200_19: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_19_data' inline_response_200_20: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_20_data' users_body: type: object properties: email: type: string description: The email address to search for. example: thor@avengers.com inline_response_200_21: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/User' inline_response_200_22: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/inline_response_200_22_data' ContactList_validation: type: object properties: pending: type: integer description: The total number of contacts pending address validation. example: 11 requireAction: type: integer description: The total number of contacts requiring manual review of their address data. example: 6 validated: type: integer description: The total number of contacts that have completed address validation. example: 4 description: High-level stats around the number of contacts pending / completed validation or requiring manual intervention. ContactListRule_bindings: type: object properties: name: type: string description: The custom field ID or contact field name to map this template variable to. example: birthday format: type: string description: Additional formatting to apply to the bound value, such as a number of years difference to the target send date. description: Key-value mapped object of template variable code to contact list field for injecting data into the final card template. Doodle_dimensions: type: object properties: height: type: number description: Natural height of this doodle, in pixels. format: float example: 105 width: type: number description: Natural width of this doodle, in pixels. format: float example: 148 description: Dimensions of this product in millimeters, exclusive of bleed. Invitation_permissions: type: object properties: useCredits: type: boolean example: true useGiftCredit: type: boolean example: true useSavedCard: type: boolean example: true description: Permission-keyed list of permissions available once this invitation is accepted. Invitation_links: type: object properties: accept: type: string description: The acceptance URL for this invitation. example: https://avengers.cardly.net/invitations/accept/8d207658-12fc-6068-23fe-09135f7b31f1/e167ed69-a05f-1b1c-2bb9-0cf8b73fb57c x-subtype: url Media_dimensions_mm: type: object properties: height: type: integer description: Height of this product, in millimeters, exclusive of bleed. example: 105 width: type: integer description: Width of this product, in millimeters, exclusive of bleed. example: 148 Media_dimensions: type: object properties: mm: $ref: '#/components/schemas/Media_dimensions_mm' description: Dimensions of this product in millimeters, exclusive of bleed. Media_bleed_mm: type: object properties: x: type: integer description: Left and right bleed zone measurements, in millimeters. example: 5 y: type: integer description: Top and bottom bleed zone measurements, in millimeters. example: 5 Media_bleed: type: object properties: mm: $ref: '#/components/schemas/Media_bleed_mm' description: | 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. Media_art_px: type: object properties: innerHeight: type: integer description: Height of the artwork inner area for this product, in pixels, exclusive of bleed zones. example: 1653 innerWidth: type: integer description: Width of the artwork inner area for this product, in pixels, exclusive of bleed zones. example: 2330 height: type: integer description: Height of the artwork required for this product, in pixels, inclusive of bleed zones. example: 1811 width: type: integer description: Width of the artwork required for this product, in pixels, inclusive of bleed zones. example: 2488 Media_art: type: object properties: px: $ref: '#/components/schemas/Media_art_px' Template_giftCard: type: object properties: id: type: string description: The unique ID of the gift card that has been included. example: 4b458510-5b7f-0bdc-7e21-891ce658a935 x-subtype: uuid region: type: string description: The country code this gift card applies to. example: AU currency: type: string description: The currency this card is provided in. example: AUD amount: type: number description: The amount of funds provided on this gift card. format: float example: 50 canChange: type: boolean description: Whether or not the recipient can swap this card for another. example: true description: If this template contains a gift card, describes the type of card selected and the value of the card. Template_definition_style: type: object properties: align: type: string example: left color: type: string example: 1144a7 size: type: integer example: 25 writing: type: string example: 987d50c7-25e1-3b1c-aa78-6f60b1411fe5 font: type: string example: 0d372503-c81b-987d-7636-bd6321290528 description: The default styles to filter through to pages in this template, if no styles are defined at the page level. Template_definition_variables_firstName: type: object properties: description: type: string example: Customer's first name to display in card front and salutation. example: type: string example: John Template_definition_variables: type: object properties: firstName: $ref: '#/components/schemas/Template_definition_variables_firstName' description: 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_definition: type: object properties: version: type: number description: The version of the Cardly editor this template was created by. format: float example: 2.2 style: $ref: '#/components/schemas/Template_definition_style' pages: type: array description: 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: [] items: type: object variables: $ref: '#/components/schemas/Template_definition_variables' description: An object describing this template's layout. User_permissions: type: object properties: administrator: type: boolean example: true artwork: type: boolean example: true billing: type: boolean example: true campaigns: type: boolean example: true developer: type: boolean example: true lists: type: boolean example: true moderate: type: boolean example: false moderateHistory: type: boolean example: false orders: type: boolean example: true templates: type: boolean example: true users: type: boolean example: true useCredits: type: boolean example: true useGiftCredit: type: boolean example: true useSavedCard: type: boolean example: true description: Permission-keyed list of permissions available to this user. inline_response_200_data: type: object properties: method: type: string description: The HTTP verb that was used for this call. example: POST url: type: string description: The full endpoint URL tht was called, including query string. example: https://api.card.ly/v2/echo headers: type: object description: 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: type: object description: All client-supplied query parameters supplied in the call, keyed by parameter name. example: test: foo body: type: object description: The request body for the call, if applicable. example: foo: bar bar: - A - B - C inline_response_200_1_data_giftCredit: type: object properties: balance: type: number description: Your organisation's current gift credit balance. Note that this may not be a whole number. format: float example: 145.43 currency: type: string description: The currency your organisation's gift balance is held in. example: USD inline_response_200_1_data: type: object properties: balance: type: number description: Your organisation's current card credit balance. Note that this may not be a whole number. format: float example: 123.21 giftCredit: $ref: '#/components/schemas/inline_response_200_1_data_giftCredit' inline_response_200_2_data: type: object properties: meta: $ref: '#/components/schemas/ResponsePaginationMeta' results: type: array description: A paginated array of zero or more `CreditHistory` objects. items: $ref: '#/components/schemas/CreditHistory' inline_response_200_3_data: type: object properties: meta: $ref: '#/components/schemas/ResponsePaginationMeta' results: type: array description: A paginated array of zero or more `GiftCreditHistory` objects. items: $ref: '#/components/schemas/GiftCreditHistory' inline_response_200_4_data: type: object properties: meta: $ref: '#/components/schemas/ResponsePaginationMeta' results: type: array description: A paginated array of zero or more `Artwork` objects. items: $ref: '#/components/schemas/Artwork' inline_response_200_6_data: type: object properties: meta: $ref: '#/components/schemas/ResponsePaginationMeta' results: type: array description: A paginated array of zero or more `ContactList` objects. items: $ref: '#/components/schemas/ContactList' inline_response_200_8_data: type: object properties: meta: $ref: '#/components/schemas/ResponsePaginationMeta' results: type: array description: A paginated array of zero or more `Contact` objects. items: $ref: '#/components/schemas/Contact' inline_response_200_10_data: type: object properties: meta: $ref: '#/components/schemas/ResponsePaginationMeta' results: type: array description: A paginated array of zero or more `Doodle` objects. items: $ref: '#/components/schemas/Doodle' inline_response_200_11_data: type: object properties: meta: $ref: '#/components/schemas/ResponsePaginationMeta' results: type: array description: A paginated array of zero or more `Font` objects. items: $ref: '#/components/schemas/Font' inline_response_200_12_data: type: object properties: meta: $ref: '#/components/schemas/ResponsePaginationMeta' results: type: array description: A paginated array of zero or more `Invitation` objects. items: $ref: '#/components/schemas/Invitation' inline_response_200_14_data: type: object properties: meta: $ref: '#/components/schemas/ResponsePaginationMeta' results: type: array description: A paginated array of zero or more `Media` objects. items: $ref: '#/components/schemas/Media' inline_response_200_15_data: type: object properties: meta: $ref: '#/components/schemas/ResponsePaginationMeta' results: type: array description: A paginated array of zero or more `Order` objects. items: $ref: '#/components/schemas/Order' inline_response_200_17_data_giftBalance: type: object properties: balance: type: number description: Your gift credit balance *after* this order has been charged. format: float example: 2064.1 currency: type: string description: The currency your gift credit is displayed in. example: USD inline_response_200_17_data_order: type: object properties: creditCost: type: number description: The total card credit cost for this preview item, if it were placed as an order line item. format: float example: 22.1 giftCreditCost: type: number description: The total gift credit required for a line item if it was placed as an order line item. format: float example: 56.21 delivery: description: Requested and estimated delivery windows based on either your requestedArrival date or the current time. allOf: - $ref: '#/components/schemas/OrderItemDelivery' description: Describes credit costs and shipping windows based on the requested preview data. inline_response_200_17_data_preview_urls: type: object properties: card: type: string description: A URL to retrieve the card preview document. format: uri example: http://api.card.ly/v2/preview/4e898074-6a2e-e3fb-9778-518596c36c2a/card/pdf envelope: type: string description: A URL to retrieve the envelope preview document. Note that this will not exist for postcards. format: uri example: http://api.card.ly/v2/preview/4e898074-6a2e-e3fb-9778-518596c36c2a/envelope/pdf description: URLs for the card and envelope artwork for this preview. inline_response_200_17_data_preview: type: object properties: expires: type: string description: When this preview's generated documents will be deleted. These documents should be retrieved prior to this time. x-subtype: datetime format: type: string description: The file format this preview was generated in. Currently only `pdf` is supported. example: pdf urls: $ref: '#/components/schemas/inline_response_200_17_data_preview_urls' inline_response_200_17_data: type: object properties: balance: type: number description: Your organisation's current credit balance after this order has been charged. format: float example: 203 giftBalance: $ref: '#/components/schemas/inline_response_200_17_data_giftBalance' order: $ref: '#/components/schemas/inline_response_200_17_data_order' preview: $ref: '#/components/schemas/inline_response_200_17_data_preview' inline_response_200_18_data: type: object properties: balance: type: number description: Your organisation's current credit balance after this order has been charged. format: float example: 203 giftBalance: $ref: '#/components/schemas/inline_response_200_17_data_giftBalance' order: description: An `Order` object representing the order you just placed. allOf: - $ref: '#/components/schemas/Order' inline_response_200_19_data: type: object properties: meta: $ref: '#/components/schemas/ResponsePaginationMeta' results: type: array description: A paginated array of zero or more `Template` objects. items: $ref: '#/components/schemas/Template' inline_response_200_20_data: type: object properties: meta: $ref: '#/components/schemas/ResponsePaginationMeta' results: type: array description: A paginated array of zero or more `User` objects. items: $ref: '#/components/schemas/User' inline_response_200_22_data: type: object properties: meta: $ref: '#/components/schemas/ResponsePaginationMeta' results: type: array description: A paginated array of zero or more `WritingStyle` objects. items: $ref: '#/components/schemas/WritingStyle' securitySchemes: ApiKeyAuth: type: apiKey description: | 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. name: API-Key in: header