{ "openapi" : "3.0.0", "servers" : [ { "description" : "Cardly v2 Primary Endpoint", "url" : "https://api.card.ly/v2" } ], "info" : { "version" : "2.1.0", "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.\n\nWhen 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.\n\nCurrently 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.\n\nAs 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.\n\nWhile 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.\n" }, "security" : [ { "ApiKeyAuth" : [ ] } ], "paths" : { "/echo" : { "post" : { "tags" : [ "Testing & Development" ], "x-verb" : "any", "operationId" : "anyEcho", "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.\n\nThis endpoint is special in that it will accept **any** HTTP verb and still provide an output to the caller.\n\n**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.\n", "parameters" : [ { "in" : "query", "name" : "test", "description" : "An example parameter which will be returned to you.", "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "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", "items" : { "type" : "string" }, "example" : [ "A", "B", "C" ] } }, "required" : [ "none" ] } } } }, "responses" : { "200" : { "description" : "A description of all data passed in the request.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "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" ] } } } } } } } } } } } }, "/account/balance" : { "get" : { "tags" : [ "Account" ], "operationId" : "getBalance", "summary" : "Retrieve Account Balance", "description" : "This endpoint allows you to quickly query the current balance for your organisation.\n\nWhere 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.\n", "responses" : { "200" : { "description" : "Your account's current credit and gift credit balances.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "type" : "object", "properties" : { "balance" : { "type" : "number", "format" : "float", "description" : "Your organisation's current card credit balance. Note that this may not be a whole number.", "example" : 123.21 }, "giftCredit" : { "type" : "object", "properties" : { "balance" : { "type" : "number", "format" : "float", "description" : "Your organisation's current gift credit balance. Note that this may not be a whole number.", "example" : 145.43 }, "currency" : { "type" : "string", "description" : "The currency your organisation's gift balance is held in.", "example" : "USD" } } } } } } } } } } } } }, "/account/credit-history" : { "get" : { "tags" : [ "Account" ], "operationId" : "getCreditHistory", "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.\n\nThis request accepts standard pagination options `limit, offset` along with the following additional filters:\n", "parameters" : [ { "in" : "query", "name" : "effectiveTime.lt", "description" : "`YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *before* this time.\n", "schema" : { "type" : "string" } }, { "in" : "query", "name" : "effectiveTime.lte", "description" : "`YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *before or equal* to this time.\n", "schema" : { "type" : "string" } }, { "in" : "query", "name" : "effectiveTime.gt", "description" : "`YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *after* this time.\n", "schema" : { "type" : "string" } }, { "in" : "query", "name" : "effectiveTime.gte", "description" : "`YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *after or equal* to this time.\n", "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "A paginated array of zero or more `CreditHistory` objects.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "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" } } } } } } } } } } } }, "/account/gift-credit-history" : { "get" : { "tags" : [ "Account" ], "operationId" : "getGiftCreditHistory", "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.\n\nThis request accepts standard pagination options `limit, offset` along with the following additional filters:\n", "parameters" : [ { "in" : "query", "name" : "effectiveTime.lt", "description" : "`YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *before* this time.\n", "schema" : { "type" : "string", "x-subtype" : "datetime" } }, { "in" : "query", "name" : "effectiveTime.lte", "description" : "`YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *before or equal* to this time.\n", "schema" : { "type" : "string", "x-subtype" : "datetime" } }, { "in" : "query", "name" : "effectiveTime.gt", "description" : "`YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *after* this time.\n", "schema" : { "type" : "string", "x-subtype" : "datetime" } }, { "in" : "query", "name" : "effectiveTime.gte", "description" : "`YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *after or equal* to this time.\n", "schema" : { "type" : "string", "x-subtype" : "datetime" } } ], "responses" : { "200" : { "description" : "A paginated array of zero or more `GiftCreditHistory` objects.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "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" } } } } } } } } } } } }, "/art" : { "get" : { "tags" : [ "Artwork" ], "operationId" : "getArtworkListing", "summary" : "List Artwork", "description" : "Retrieve the currently available artwork for your organisation.\n\nThis request accepts standard pagination options `limit, offset` along with the following additional filters:\n", "parameters" : [ { "in" : "query", "name" : "ownOnly", "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.\n", "schema" : { "type" : "boolean" } } ], "responses" : { "200" : { "description" : "A paginated array of zero or more `Artwork` objects.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "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" } } } } } } } } } } }, "post" : { "tags" : [ "Artwork" ], "operationId" : "postArtworkCreate", "summary" : "Create Artwork", "description" : "Add a new piece of artwork.\n", "requestBody" : { "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "media" : { "type" : "string", "x-subtype" : "uuid", "description" : "UUID for the media this artwork will use.", "example" : "fd7368b0-ad4d-11ea-9da9-04d4c4254e1b" }, "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.", "items" : { "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." } } }, "example" : [ { "page" : 1, "image" : "iVBORw0KGg..." }, { "page" : 3, "image" : "iVBORw0KGg..." } ] } }, "required" : [ "media", "name", "artwork" ] } } } }, "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" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Artwork" } } } } } }, "422" : { "description" : "A status indicating validation failures with the submission.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/ValidationStatus" } } } } } } } } }, "/art/{id}" : { "get" : { "tags" : [ "Artwork" ], "operationId" : "getArtwork", "summary" : "Retrieve Artwork", "description" : "Retrieve information on a specific piece of artwork.\n", "parameters" : [ { "in" : "path", "name" : "id", "description" : "The unique ID of the artwork you wish to retrieve.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true } ], "responses" : { "200" : { "description" : "An `Artwork` representing the requested piece of artwork.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Artwork" } } } } } }, "404" : { "description" : "A status indicating the artwork could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } }, "post" : { "tags" : [ "Artwork" ], "operationId" : "postArtworkEdit", "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.\n", "parameters" : [ { "in" : "path", "name" : "id", "description" : "The unique ID of the artwork you wish to update.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "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.", "items" : { "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." } } }, "example" : [ { "page" : 1, "image" : "iVBORw0KGg..." }, { "page" : 3, "image" : "iVBORw0KGg..." } ] } }, "x-conditionallyRequired" : [ "name", "description", "artwork" ] } } } }, "responses" : { "200" : { "description" : "An `Artwork` representing the updated piece of artwork.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Artwork" } } } } } }, "404" : { "description" : "A status indicating the artwork could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } }, "422" : { "description" : "A status indicating validation failures with the submission.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/ValidationStatus" } } } } } } } }, "delete" : { "tags" : [ "Artwork" ], "operationId" : "deleteArtwork", "summary" : "Delete Artwork", "description" : "Delete a piece of artwork owned by your organisation.\n", "parameters" : [ { "in" : "path", "name" : "id", "description" : "The unique ID of the artwork you wish to delete.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true } ], "responses" : { "200" : { "description" : "An `Artwork` representing the artwork that was deleted.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Artwork" } } } } } }, "404" : { "description" : "A status indicating the artwork could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } } }, "/contact-lists" : { "get" : { "tags" : [ "Contact Lists" ], "operationId" : "getContactLists", "summary" : "List Contact Lists", "description" : "Retrieve active contact lists for your organisation.\n", "responses" : { "200" : { "description" : "A paginated array of zero or more `ContactList` objects.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "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" } } } } } } } } } } }, "post" : { "tags" : [ "Contact Lists" ], "operationId" : "createContactList", "summary" : "Create Contact List", "description" : "Add a new contact list, optionally with custom fields.\n", "requestBody" : { "content" : { "application/json" : { "schema" : { "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.", "items" : { "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" ] } } }, "example" : [ { "name" : "Birthday", "type" : "date", "image" : "iVBORw0KGg..." }, { "name" : "Preferred Name", "type" : "text", "description" : "The customer's preferred name when we address them." } ] } }, "required" : [ "name" ] } } } }, "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" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/ContactList" } } } } } }, "422" : { "description" : "A status indicating validation failures with the submission.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/ValidationStatus" } } } } } } } } }, "/contact-lists/{id}" : { "get" : { "tags" : [ "Contact Lists" ], "operationId" : "getContactList", "summary" : "Retrieve Contact List", "description" : "Retrieve information on a specific contact list.\n", "parameters" : [ { "in" : "path", "name" : "id", "description" : "The unique ID of the contact list you wish to retrieve.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true } ], "responses" : { "200" : { "description" : "A `ContactList` representing the requested contact list.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/ContactList" } } } } } }, "404" : { "description" : "A status indicating the contact list could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } }, "post" : { "tags" : [ "Contact Lists" ], "operationId" : "postContactList", "summary" : "Create Contact List", "description" : "Add a new contact list, optionally with custom fields.\n", "parameters" : [ { "in" : "path", "name" : "id", "description" : "The unique ID of the contact list you wish to update.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "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.", "items" : { "type" : "object", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "The identifier of an existing field to update or remove." }, "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.\n\n**Required** if adding a new field.\n" }, "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.\n\n**Required** if adding a new field.\n**Ignored** if updating an existing field.\n", "enum" : [ "text", "date", "number", "url" ] }, "remove" : { "type" : "boolean", "description" : "If set to true, removes this field from the list." } } }, "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." } ] } }, "required" : [ "name" ] } } } }, "responses" : { "200" : { "description" : "A `ContactList` representing the list that was updated.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/ContactList" } } } } } }, "404" : { "description" : "A status indicating the contact list could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } }, "422" : { "description" : "A status indicating validation failures with the submission.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/ValidationStatus" } } } } } } } }, "delete" : { "tags" : [ "Contact Lists" ], "operationId" : "deleteContactList", "summary" : "Delete Contact List", "description" : "Delete a contact list, disabling any automations linked to it.\n", "parameters" : [ { "in" : "path", "name" : "id", "description" : "The unique ID of the contact list you wish to delete.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true } ], "responses" : { "200" : { "description" : "A `ContactList` representing the contact list that was deleted.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/ContactList" } } } } } }, "404" : { "description" : "A status indicating the contact list could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } } }, "/contact-lists/{listId}/contacts" : { "get" : { "tags" : [ "Contacts" ], "operationId" : "getContactsListing", "summary" : "List Contacts", "description" : "Retrieve active contacts in a given list.\n", "parameters" : [ { "in" : "path", "name" : "listId", "description" : "The unique ID of the contact list you wish to retrieve contacts for.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true } ], "responses" : { "200" : { "description" : "A paginated array of zero or more `Contact` records.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "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" } } } } } } } } }, "404" : { "description" : "A status indicating the contact list could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } }, "post" : { "tags" : [ "Contacts" ], "operationId" : "createContact", "summary" : "Create Contact", "description" : "Add a new contact to a given list.\n\n**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.\n", "parameters" : [ { "in" : "path", "name" : "listId", "description" : "The unique ID of the contact list you wish to add this contact to.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "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.\n\nFor each custom field in your list, fields may be specified based on the unique field ID created by Cardly.\n\nFields will be subject to data type checking where appropriate:\n\n**URL Fields** require full, complete URLs supplied, if used.\n**Number Fields** require any numeric string, free of any human readable formatting (ie, commas for thousands separators).\n", "example" : { "birthday" : "1052-04-01", "homepage" : "https://www.avengers.com/profile/thor" } } }, "required" : [ "firstName", "address", "locality", "region", "country", "postcode" ] } } } }, "responses" : { "200" : { "description" : "A `Contact` representing the contact that was created.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Contact" } } } } } }, "404" : { "description" : "A status indicating the requested contact list could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } }, "422" : { "description" : "A status indicating validation failures with the submission.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/ValidationStatus" } } } } } } } }, "delete" : { "tags" : [ "Contacts" ], "operationId" : "deleteContactByIdentifier", "summary" : "Delete Contact", "description" : "Delete a contact, disabling any automations linked to it.\n\nContact matching is performed in order of matching external ID or email address. At least one of these details must be provided.\n", "parameters" : [ { "in" : "path", "name" : "listId", "description" : "The unique ID of the contact list you wish to search contacts for to delete.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "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" } } } } } }, "responses" : { "200" : { "description" : "A `Contact` representing the contact that was deleted.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Contact" } } } } } }, "404" : { "description" : "A status indicating a matching contact or underlying contact list could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } } }, "/contact-lists/{listId}/contacts/{id}" : { "get" : { "tags" : [ "Contacts" ], "operationId" : "getContact", "summary" : "Retrieve Contact", "description" : "Retrieve information on a specific contact from a given list, identified by Cardly's unique identifier for the record.\n", "parameters" : [ { "in" : "path", "name" : "listId", "description" : "The unique ID of the contact list this contact belongs to.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true }, { "in" : "path", "name" : "id", "description" : "The unique ID of the contact you wish to retrieve.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true } ], "responses" : { "200" : { "description" : "A `Contact` representing the requested contact.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Contact" } } } } } }, "404" : { "description" : "A status indicating the contact list or contact could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } }, "post" : { "tags" : [ "Contacts" ], "operationId" : "postContact", "summary" : "Edit Contact", "description" : "Edit an existing contact, providing updated information for the contact record.\n", "parameters" : [ { "in" : "path", "name" : "listId", "description" : "The unique ID of the contact list the contact you're updating belongs to.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true }, { "in" : "path", "name" : "id", "description" : "The unique ID of the contact you wish to update.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "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.\n\nFor each custom field in your list, fields may be specified based on the unique field ID created by Cardly.\n\nFields will be subject to data type checking where appropriate:\n\n**URL Fields** require full, complete URLs supplied, if used.\n**Number Fields** require any numeric string, free of any human readable formatting (ie, commas for thousands separators).\n", "example" : { "birthday" : "1052-04-01", "homepage" : "https://www.avengers.com/profile/thor" } } }, "required" : [ "firstName", "address", "locality", "region", "country", "postcode" ] } } } }, "responses" : { "200" : { "description" : "A `Contact` representing the contact that was updated.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Contact" } } } } } }, "404" : { "description" : "A status indicating the requested contact list or contact could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } }, "422" : { "description" : "A status indicating validation failures with the submission.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/ValidationStatus" } } } } } } } }, "delete" : { "tags" : [ "Contacts" ], "operationId" : "deleteContact", "summary" : "Delete Contact", "description" : "Delete a contact, disabling any automations linked to it.\n", "parameters" : [ { "in" : "path", "name" : "listId", "description" : "The unique ID of the contact list the contact you're deleting belongs to.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true }, { "in" : "path", "name" : "id", "description" : "The unique ID of the contact you wish to delete.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true } ], "responses" : { "200" : { "description" : "A `Contact` representing the contact that was deleted.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Contact" } } } } } }, "404" : { "description" : "A status indicating a matching contact or underlying contact list could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } } }, "/contact-lists/{listId}/contacts/find" : { "get" : { "tags" : [ "Contacts" ], "operationId" : "searchContacts", "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.\n", "parameters" : [ { "in" : "path", "name" : "listId", "description" : "The unique ID of the contact list to search within.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true }, { "in" : "query", "name" : "query", "description" : "An email address or external identifier to locate a contact by within the given list.", "schema" : { "type" : "string" }, "required" : true } ], "responses" : { "200" : { "description" : "A `Contact` representing the requested contact.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Contact" } } } } } }, "404" : { "description" : "A status indicating the contact list or contact could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } } }, "/contact-lists/{listId}/contacts/sync" : { "post" : { "tags" : [ "Contacts" ], "operationId" : "postContactSync", "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.\n\nContact 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.\n", "parameters" : [ { "in" : "path", "name" : "listId", "description" : "The unique ID of the contact list you wish to add this contact to.", "schema" : { "type" : "string", "x-subtype" : "uuid" }, "required" : true } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "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.\n\n**Conditionally required:** At least one of `externalId` or `email` is required for a sync operation.\n", "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.\n\n**Conditionally required:** At least one of `externalId` or `email` is required for a sync operation.\n", "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.\n\nFor each custom field in your list, fields may be specified based on the unique field ID created by Cardly.\n\nFields will be subject to data type checking where appropriate:\n\n**URL Fields** require full, complete URLs supplied, if used.\n**Number Fields** require any numeric string, free of any human readable formatting (ie, commas for thousands separators).\n", "example" : { "birthday" : "1052-04-01", "homepage" : "https://www.avengers.com/profile/thor" } } }, "required" : [ "firstName", "address", "locality", "region", "country", "postcode" ] } } } }, "responses" : { "200" : { "description" : "A `Contact` representing the contact that was updated or created.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Contact" } } } } } }, "404" : { "description" : "A status indicating the requested contact list could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } }, "422" : { "description" : "A status indicating validation failures with the submission.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/ValidationStatus" } } } } } } } } }, "/doodles" : { "get" : { "tags" : [ "Doodles" ], "operationId" : "getDoodleListing", "summary" : "List Doodles", "description" : "Retrieve your currently available doodles.\n\nThis request accepts standard pagination options `limit, offset` along with the following additional filters:\n", "parameters" : [ { "in" : "query", "name" : "organisationOnly", "description" : "If truthy, only return doodles that are exclusive to your organisation.\n", "schema" : { "type" : "boolean" } } ], "responses" : { "200" : { "description" : "A paginated array of zero or more `Doodle` objects.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "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" } } } } } } } } } } } }, "/fonts" : { "get" : { "tags" : [ "Fonts" ], "operationId" : "getFontListing", "summary" : "List Fonts", "description" : "Retrieve your currently available fonts.\n\nThis request accepts standard pagination options `limit, offset` along with the following additional filters:\n", "parameters" : [ { "in" : "query", "name" : "organisationOnly", "description" : "If truthy, only return fonts that are exclusive to your organisation.\n", "schema" : { "type" : "boolean" } } ], "responses" : { "200" : { "description" : "A paginated array of zero or more `Font` objects.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "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" } } } } } } } } } } } }, "/invitations" : { "get" : { "tags" : [ "Invitations" ], "operationId" : "getInvitationListing", "summary" : "List Invitations", "description" : "Retrieve active invitations for your organisation.\n\nThis request accepts standard pagination options `limit, offset` along with the following additional filters:\n", "parameters" : [ { "in" : "query", "name" : "acceptedOnly", "description" : "If truthy, only return accepted invitations.\n", "schema" : { "type" : "boolean" } }, { "in" : "query", "name" : "expiredOnly", "description" : "If truthy, only return expired invitations.\n", "schema" : { "type" : "boolean" } }, { "in" : "query", "name" : "includeAccepted", "description" : "If truthy, includes accepted invitations in the response. By default, accepted invitations are filtered out of listings.\n", "schema" : { "type" : "boolean" } } ], "responses" : { "200" : { "description" : "A paginated array of zero or more `Invitation` objects.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "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" } } } } } } } } } } }, "post" : { "tags" : [ "Invitations" ], "operationId" : "postInvitation", "summary" : "Create Invitation", "description" : "Send an invitation to use your organisation portal, if the provided email address doesn't already have access.\n", "requestBody" : { "content" : { "application/json" : { "schema" : { "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`\n", "items" : { "type" : "string" }, "example" : [ "use-credits", "use-gift-credits", "use-saved-card" ] } }, "required" : [ "email" ] } } } }, "responses" : { "200" : { "description" : "An `Invitation` representing the invitation that was created.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Invitation" } } } } } }, "422" : { "description" : "A status indicating validation failures with the submission.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/ValidationStatus" } } } } } } } }, "delete" : { "tags" : [ "Invitations" ], "operationId" : "deleteInvitationByEmail", "summary" : "Delete Invitation by Email", "description" : "Delete an invitation by email address, immediately invalidating it for acceptance.\n", "requestBody" : { "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "email" : { "type" : "string", "description" : "The email address to search for.", "example" : "thor@avengers.com" } } } } } }, "responses" : { "200" : { "description" : "An `Invitation` representing the invitation that was deleted.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Invitation" } } } } } }, "404" : { "description" : "A status indicating a matching invitation could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } } }, "/invitations/{id}" : { "get" : { "tags" : [ "Invitations" ], "operationId" : "getInvitationById", "summary" : "Retrieve Invitation", "description" : "Retrieve information on a specific invitation, identified by Cardly's unique identifier for the record.\n", "parameters" : [ { "in" : "path", "name" : "id", "description" : "The unique ID of the invitation to retrieve.", "schema" : { "type" : "string" }, "required" : true } ], "responses" : { "200" : { "description" : "An `Invitation` representing the invitation that was located.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Invitation" } } } } } }, "404" : { "description" : "A status indicating the invitation could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } }, "delete" : { "tags" : [ "Invitations" ], "operationId" : "deleteInvitationById", "summary" : "Delete Invitation", "description" : "Delete an invitation by unique ID address, immediately invalidating it for acceptance.\n", "parameters" : [ { "in" : "path", "name" : "id", "description" : "The unique ID of the invitation to revoke.", "schema" : { "type" : "string" }, "required" : true } ], "responses" : { "200" : { "description" : "An `Invitation` representing the invitation that was deleted.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Invitation" } } } } } }, "404" : { "description" : "A status indicating the invitation could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } } }, "/invitations/find" : { "get" : { "tags" : [ "Invitations" ], "operationId" : "findInvitation", "summary" : "Find Invitation", "description" : "Retrieve information on a specific invitation, searching by a provided email address.\n", "parameters" : [ { "in" : "query", "name" : "email", "description" : "The email address to search for.", "schema" : { "type" : "string" }, "required" : true } ], "responses" : { "200" : { "description" : "An `Invitation` representing the invitation that was located.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Invitation" } } } } } }, "404" : { "description" : "A status indicating the invitation could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } } }, "/invitations/resend" : { "post" : { "tags" : [ "Invitations" ], "operationId" : "postResendInvitationByEmail", "summary" : "Resend Invitation by Email", "description" : "Resend an invitation to a specified email address if that invitation has not yet been accepted.\n", "requestBody" : { "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "email" : { "type" : "string", "description" : "The email address to search for.", "example" : "thor@avengers.com" } } } } } }, "responses" : { "200" : { "description" : "An `Invitation` representing the invitation that was resent.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Invitation" } } } } } }, "404" : { "description" : "A status indicating the invitation could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } }, "422" : { "description" : "A status indicating validation failures with the submission.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/ValidationStatus" } } } } } } } } }, "/invitations/resend/{id}" : { "post" : { "tags" : [ "Invitations" ], "operationId" : "postResendInvitationById", "summary" : "Resend Invitation", "description" : "Resend an invitation identified by Cardly's unique ID.\n", "parameters" : [ { "in" : "path", "name" : "id", "description" : "The unique ID to the invitation to resend.", "schema" : { "type" : "string" }, "required" : true } ], "responses" : { "200" : { "description" : "An `Invitation` representing the invitation that was resent.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Invitation" } } } } } }, "404" : { "description" : "A status indicating the invitation could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } } }, "/media" : { "get" : { "tags" : [ "Media" ], "operationId" : "getMediaListing", "summary" : "List Media", "description" : "Retrieve the currently available media sizes for product artwork.\n\nThis request accepts standard pagination options `limit, offset` along with the following additional filters:\n", "parameters" : [ { "in" : "query", "name" : "organisationOnly", "description" : "If truthy, only return media items that are exclusive to your organisation.\n", "schema" : { "type" : "boolean" } } ], "responses" : { "200" : { "description" : "A paginated array of zero or more `Media` objects.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "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" } } } } } } } } } } } }, "/orders" : { "get" : { "tags" : [ "Orders" ], "operationId" : "getOrderListing", "summary" : "List Orders", "description" : "Retrieve orders placed by your organisation.\n", "responses" : { "200" : { "description" : "A paginated array of zero or more `Order` objects.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "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" } } } } } } } } } } } }, "/orders/{id}" : { "get" : { "tags" : [ "Orders" ], "operationId" : "getOrderById", "summary" : "Retrieve Order", "description" : "Retrieve information on a specific order.\n", "parameters" : [ { "in" : "path", "name" : "id", "description" : "The unique ID of the order to retrieve.", "schema" : { "type" : "string" }, "required" : true } ], "responses" : { "200" : { "description" : "An `Order` representing the order that was requested.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/Order" } } } } } }, "404" : { "description" : "A status indicating the order could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } } }, "/orders/preview" : { "post" : { "tags" : [ "Orders" ], "operationId" : "postOrderPreview", "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.\n\nThis 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.\n", "requestBody" : { "content" : { "application/json" : { "schema" : { "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.\n\n**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.\n", "allOf" : [ { "$ref" : "#/components/schemas/Style" } ] }, "messages" : { "type" : "object", "description" : "Message data to inject when not utilising pre-built templates from your account.", "properties" : { "pages" : { "type" : "array", "items" : { "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.\n\n**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.\n", "allOf" : [ { "$ref" : "#/components/schemas/Style" } ] } } }, "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" } } ] } } }, "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" : { "type" : "object", "description" : "The recipient's addressing details, as they should appear on the envelope.", "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.\n**Conditionally required** based on the country supplied.\n", "example" : "NY" }, "postcode" : { "type" : "string", "description" : "The postcode for this recipient. Note that this may be empty for countries that do not utilise postcodes.\n\n**Conditionally required** based on the country supplied.\n", "example" : 12345 }, "country" : { "type" : "string", "description" : "The 2-character ISO code for the country relating to this recipient.", "example" : "US" } }, "required" : [ "firstName", "address", "city", "region", "postcode", "country" ] }, "sender" : { "type" : "object", "description" : "Details of the sender for this order.\n\n**Please note:** the entire sender section is optional and will default to your organisation's return details if not completed.\n\nIf any sender element is specified, all must be specified.\n", "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.\n\n**Conditionally required** based on the country supplied.\n", "example" : "NY" }, "postcode" : { "type" : "string", "description" : "The postcode for this sender. Note that this may be empty for countries that do not utilise postcodes.\n\n**Conditionally required** based on the country supplied.\n", "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.\n" } }, "required" : [ "firstName", "address", "city", "region", "postcode", "country" ] }, "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.\n\nCurrently, only Australia supports the `tracked` shipping method.\n\nCurrently, only Australia and the United States support the `express` shipping method.\n", "enum" : [ "standard", "tracked", "express" ], "example" : "standard" }, "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.\n", "example" : false }, "requestedArrival" : { "type" : "string", "x-subtype" : "date", "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" }, "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" } }, "required" : [ "artwork", "recipient" ] } } } }, "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" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "type" : "object", "properties" : { "balance" : { "type" : "number", "format" : "float", "description" : "Your organisation's current credit balance after this order has been charged.", "example" : 203 }, "giftBalance" : { "type" : "object", "properties" : { "balance" : { "type" : "number", "format" : "float", "description" : "Your gift credit balance *after* this order has been charged.", "example" : 2064.1 }, "currency" : { "type" : "string", "description" : "The currency your gift credit is displayed in.", "example" : "USD" } } }, "order" : { "type" : "object", "description" : "Describes credit costs and shipping windows based on the requested preview data.", "properties" : { "creditCost" : { "type" : "number", "format" : "float", "description" : "The total card credit cost for this preview item, if it were placed as an order line item.", "example" : 22.1 }, "giftCreditCost" : { "type" : "number", "format" : "float", "description" : "The total gift credit required for a line item if it was placed as an order line item.", "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" } ] } } }, "preview" : { "type" : "object", "properties" : { "expires" : { "type" : "string", "x-subtype" : "datetime", "description" : "When this preview's generated documents will be deleted. These documents should be retrieved prior to this time.", "example" : null }, "format" : { "type" : "string", "description" : "The file format this preview was generated in. Currently only `pdf` is supported.", "example" : "pdf" }, "urls" : { "type" : "object", "description" : "URLs for the card and envelope artwork for this preview.", "properties" : { "card" : { "type" : "string", "format" : "uri", "description" : "A URL to retrieve the card preview document.", "example" : "http://api.card.ly/v2/preview/4e898074-6a2e-e3fb-9778-518596c36c2a/card/pdf" }, "envelope" : { "type" : "string", "format" : "uri", "description" : "A URL to retrieve the envelope preview document. Note that this will not exist for postcards.", "example" : "http://api.card.ly/v2/preview/4e898074-6a2e-e3fb-9778-518596c36c2a/envelope/pdf" } } } } } } } } } } } }, "422" : { "description" : "A status indicating validation failures with the submission.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } } }, "/orders/place" : { "post" : { "tags" : [ "Orders" ], "operationId" : "postOrderPlace", "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.\n\nNote 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.\n", "requestBody" : { "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "lines" : { "type" : "array", "description" : "A list of one or more of the below `OrderItem` structures to include into the overall order.\n", "items" : { "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" : { "type" : "integer", "minimum" : 1, "default" : 1, "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 }, "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.\n\n**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.\n", "allOf" : [ { "$ref" : "#/components/schemas/Style" } ] }, "messages" : { "type" : "object", "description" : "Message data to inject when not utilising pre-built templates from your account.", "properties" : { "pages" : { "type" : "array", "items" : { "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.\n\n**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.\n", "allOf" : [ { "$ref" : "#/components/schemas/Style" } ] } } }, "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" } } ] } } }, "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" : { "type" : "object", "description" : "The recipient's addressing details, as they should appear on the envelope.", "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.\n\n**Conditionally required** based on the country supplied.\n", "example" : "NY" }, "postcode" : { "type" : "string", "description" : "The postcode for this recipient. Note that this may be empty for countries that do not utilise postcodes.\n\n**Conditionally required** based on the country supplied.\n", "example" : 12345 }, "country" : { "type" : "string", "description" : "The 2-character ISO code for the country relating to this recipient.", "example" : "US" } }, "required" : [ "firstName", "address", "city", "country" ], "x-conditionallyRequired" : [ "region", "postcode" ] }, "sender" : { "type" : "object", "description" : "Details of the sender for this order.\n\n**Please note:** the entire sender section is optional and will default to your organisation's return details if not completed.\n\nIf any sender element is specified, all must be specified.\n", "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.\n\n**Conditionally required** based on the country supplied.\n", "example" : "NY" }, "postcode" : { "type" : "string", "description" : "The postcode for this sender. Note that this may be empty for countries that do not utilise postcodes.\n\n**Conditionally required** based on the country supplied.\n", "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.\n" } }, "required" : [ "firstName", "address", "city", "region", "postcode", "country" ], "x-conditionallyRequired" : [ "region", "postcode" ] }, "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.\n\nCurrently, only Australia supports the `tracked` shipping method.\n\nCurrently, only Australia and the United States support the `express` shipping method.\n", "enum" : [ "standard", "tracked", "express" ], "example" : "standard" }, "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.\n", "example" : false }, "requestedArrival" : { "type" : "string", "x-subtype" : "date", "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" } } }, "required" : [ "artwork", "recipient" ] }, "purchaseOrderNumber" : { "type" : "string", "description" : "A reference number to place against this order - useful to tie back to your existing systems for auditing.", "example" : "PO1234" } }, "required" : [ "lines" ] } } } }, "responses" : { "200" : { "description" : "An `Order` representing the order that was created.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "type" : "object", "properties" : { "balance" : { "type" : "number", "format" : "float", "description" : "Your organisation's current credit balance after this order has been charged.", "example" : 203 }, "giftBalance" : { "type" : "object", "properties" : { "balance" : { "type" : "number", "format" : "float", "description" : "Your gift credit balance *after* this order has been charged.", "example" : 2064.1 }, "currency" : { "type" : "string", "description" : "The currency your gift credit is displayed in.", "example" : "USD" } } }, "order" : { "description" : "An `Order` object representing the order you just placed.", "allOf" : [ { "$ref" : "#/components/schemas/Order" } ] } } } } } } } }, "402" : { "description" : "A status indicating that your account requires additional credit to place this order.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } }, "422" : { "description" : "A status indicating validation failures with the submission.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/ValidationStatus" } } } } } } } } }, "/templates" : { "get" : { "tags" : [ "Templates" ], "operationId" : "getTemplateListing", "summary" : "List Templates", "description" : "Retrieve your currently available templates.\n", "responses" : { "200" : { "description" : "A paginated array of zero or more `Template` objects.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "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" } } } } } } } } } } } }, "/users" : { "get" : { "tags" : [ "Users" ], "operationId" : "getUserListing", "summary" : "List Users", "description" : "Retrieve active users for your organisation.\n", "responses" : { "200" : { "description" : "A paginated array of zero or more `User` objects.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "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" } } } } } } } } } } }, "delete" : { "tags" : [ "Users" ], "operationId" : "deleteUserByEmail", "summary" : "Delete User by Email", "description" : "Delete a user by email address, immediately revoking their access to your organisation portal.\n\n**Please note:** Access can not be removed for users with `administrator` privileges on your account. These must be removed via your portal directly.\n", "requestBody" : { "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "email" : { "type" : "string", "description" : "The email address to search for.", "example" : "thor@avengers.com" } } } } } }, "responses" : { "200" : { "description" : "An `User` representing the user that was deleted.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/User" } } } } } }, "404" : { "description" : "A status indicating a matching user could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } } }, "/users/{id}" : { "get" : { "tags" : [ "Users" ], "operationId" : "getUserById", "summary" : "Retrieve User", "description" : "Retrieve information on a specific user, identified by Cardly's unique identifier for the record.\n", "parameters" : [ { "in" : "path", "name" : "id", "description" : "The unique ID of the user to retrieve.", "schema" : { "type" : "string" }, "required" : true } ], "responses" : { "200" : { "description" : "An `User` representing the user that was located.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/User" } } } } } }, "404" : { "description" : "A status indicating the user could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } }, "delete" : { "tags" : [ "Users" ], "operationId" : "deleteUserById", "summary" : "Delete user", "description" : "Delete a user by unique ID address, immediately revoking their access to your organisation portal.\n\n**Please note:** Access can not be removed for users with `administrator` privileges on your account. These must be removed via your portal directly.\n", "parameters" : [ { "in" : "path", "name" : "id", "description" : "The unique ID of the user to revoke.", "schema" : { "type" : "string" }, "required" : true } ], "responses" : { "200" : { "description" : "A `User` representing the invitation that was deleted.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/User" } } } } } }, "404" : { "description" : "A status indicating the user could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } } }, "/users/find" : { "get" : { "tags" : [ "Users" ], "operationId" : "findUser", "summary" : "Find User", "description" : "Retrieve information on a specific user, searching by a provided email address.\n", "parameters" : [ { "in" : "query", "name" : "email", "description" : "The email address to search for.", "schema" : { "type" : "string" }, "required" : true } ], "responses" : { "200" : { "description" : "An `User` representing the user that was located.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "data" : { "$ref" : "#/components/schemas/User" } } } } } }, "404" : { "description" : "A status indicating the user could not be found.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" } } } } } } } } }, "/writing-styles" : { "get" : { "tags" : [ "Writing Styles" ], "operationId" : "getWritingStyleListing", "summary" : "List Writing Styles", "description" : "Retrieve your currently available writing styles.\n", "responses" : { "200" : { "description" : "A paginated array of zero or more `WritingStyle` objects.", "content" : { "application/json" : { "schema" : { "type" : "object", "properties" : { "state" : { "$ref" : "#/components/schemas/ResponseStatus" }, "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" } } } } } } } } } } } } }, "components" : { "securitySchemes" : { "ApiKeyAuth" : { "type" : "apiKey", "in" : "header", "name" : "API-Key", "description" : "The Cardly API uses API keys to authenticate requests. Your API keys can be obtained and managed from your organisation portal.\n\nEach 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.\n\nLive mode keys are prefixed with `live_` and have none of the restrictions of test mode keys.\n\nAuthentication to the API is performed via the `API-Key` header, as per the provided example.\n\nAPI 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.\n\n**All API requests must be performed over HTTPS.** Calls made over plain HTTP will be rejected, as will requests without authentication.\n" } }, "schemas" : { "ResponseStatus" : { "type" : "object", "title" : "Response Status Object", "description" : "Provides a standard status identifier to indicate overall success, along with messages and the current API build version.", "properties" : { "status" : { "type" : "string", "description" : "Whether or not the request succeeeded without errors or warnings.", "enum" : [ "OK", "WARN", "ERROR" ], "example" : "OK" }, "messages" : { "type" : "array", "items" : { "type" : "string" }, "description" : "Any notifications, warnings or error messages relevant to the response.", "example" : [ ] }, "version" : { "type" : "integer", "description" : "The current build version of Cardly", "example" : 1181 } } }, "ResponsePaginationMeta" : { "type" : "object", "title" : "Pagination Metadata Object", "description" : "Provides a standard description of a listing result set and the records that were retrieved.", "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.", "enum" : [ "asc", "desc" ], "example" : "asc" }, "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 } } }, "ValidationStatus" : { "type" : "object", "title" : "Validation Status Object", "description" : "One or more elements denoting validations failures with the named field(s), and the reason for failure.", "properties" : { "email" : { "type" : "string", "description" : "A reason the identified key's value has failed validation.", "example" : "This value should be a valid email address." } } }, "Artwork" : { "type" : "object", "title" : "Artwork Object", "description" : "The artwork object represents a product at a given media size and provides preview images for each page capable of hosting artwork imagery.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "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" }, "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", "items" : { "type" : "string", "x-subtype" : "url" }, "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 ] }, "media" : { "description" : "The media size associated with this piece of artwork.", "allOf" : [ { "$ref" : "#/components/schemas/Media" } ] }, "createdAt" : { "type" : "string", "format" : "date-time", "description" : "`YYYY-MM-DDTHH:ii:ss+00:00` formatted string to denote when this piece of artwork was created.\n", "example" : "2020-06-14T09:40:09+10:00" }, "updatedAt" : { "type" : "string", "format" : "date-time", "description" : "`YYYY-MM-DDTHH:ii:ss+00:00` formatted string to denote when this piece of artwork was last updated.\n", "example" : "2020-06-14T14:39:35+10:00" } } }, "Contact" : { "type" : "object", "title" : "Contact Object", "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.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "Unique identifier for this contact.", "example" : "23fb4b1c-f127-eeea-9f68-6f0a7945da43" }, "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", "x-subtype" : "uuid", "description" : "Identifier for the contact list this contact belongs to.", "example" : "b905e966-ecdf-9656-2564-049c334a4db3" }, "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.", "example" : null }, "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", "format" : "float", "description" : "Geo coordinates for this address, if it has been resolved with address lookups.", "example" : 40.761635 }, "longitude" : { "type" : "number", "format" : "float", "description" : "Geo coordinates for this address, if it has been resolved with address lookups.", "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" } } } }, "ContactList" : { "type" : "object", "title" : "Contact List Object", "description" : "The contact list object provides detail on a given list on your account, along with currently set up custom fields and automation details.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "Unique identifier for this contact list.", "example" : "6d7c260b-f39f-e822-6aa5-612014047d20" }, "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" : { "type" : "object", "description" : "High-level stats around the number of contacts pending / completed validation or requiring manual intervention.", "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 } } } } }, "ContactListField" : { "type" : "object", "title" : "Contact List Field", "description" : "The contact list field object defines additional, custom fields to be applied to all contacts within a list.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "A unique identifier for this field which never changes.", "example" : "9da307a4-1c37-f69a-c6ec-1ba002165d57" }, "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.", "example" : null }, "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" } } }, "ContactListRule" : { "type" : "object", "title" : "Contact List Rule", "description" : "A contact list rule object describes tasks be performed automatically at specified intervals or based on triggers set up in the Cardly platform.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "A unique identifier for this rule which never changes.", "example" : "45702de2-dee0-2b14-ed52-ae63886f28f1" }, "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.", "example" : null }, "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" : { "type" : "object", "description" : "Key-value mapped object of template variable code to contact list field for injecting data into the final card template.", "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.", "example" : null } } } } }, "CreditHistory" : { "type" : "object", "title" : "Credit History Object", "description" : "The credit history object models an entry - positive or negative - for the organisation's credit purchase and spends.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "Unique identifier for this credit history entry.", "example" : "484ed6af-416e-1f76-7807-c88104734f09" }, "orderId" : { "type" : "string", "x-subtype" : "uuid", "description" : "Identifier for an order that triggered this credit history entry. Generally used whenever paid transactions take place.", "example" : "7807d6af-484e-c881-1f76-416e04734f09" }, "transactionId" : { "type" : "string", "x-subtype" : "uuid", "description" : "Identifier for a transaction that triggered this credit history entry, typically related to the purchase of credits.", "example" : "f47b838a-304d-f88c-4d2c-a8709cacfdc8" }, "type" : { "type" : "string", "description" : "A human-readable, brief description of what this entry is for, ie; `Credit Purchase`, `Order Placement`.\n", "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", "format" : "float", "description" : "Value that was either credited or debited from the organisation in this action.", "example" : 3 }, "newBalance" : { "type" : "number", "format" : "float", "description" : "The current account credit balance at the time this change was effected.", "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" } } }, "Doodle" : { "type" : "object", "title" : "Doodle Object", "description" : "The doodle object represents a vector-based image which can be included within card artwork.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "Unique identifier for this doodle.", "example" : "31035c6a-9311-15aa-638e-6894acb0e668" }, "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.", "example" : null }, "image" : { "type" : "string", "x-subtype" : "url", "description" : "A URL to a preview image of this doodle.", "example" : "https://www.cardly.net/doodle/preview/31035c6a-9311-15aa-638e-6894acb0e668" }, "dimensions" : { "type" : "object", "description" : "Dimensions of this product in millimeters, exclusive of bleed.", "properties" : { "height" : { "type" : "number", "format" : "float", "description" : "Natural height of this doodle, in pixels.", "example" : 105 }, "width" : { "type" : "number", "format" : "float", "description" : "Natural width of this doodle, in pixels.", "example" : 148 } } }, "restricted" : { "type" : "boolean", "description" : "Whether or not this doodle is exclusive to your organisation, or freely available across the Cardly platform.", "example" : false } } }, "Font" : { "type" : "object", "title" : "Font Object", "description" : "The font object models a style of writing available within Cardly, either from our shared library or your exclusive handwriting conversions.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "Unique identifier for this font option.", "example" : "461910d8-ff8c-ee8d-efe5-d5feb3f9113a" }, "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`.", "enum" : [ "cursive", "hand", "serif", "sans", "mono" ], "example" : "hand" }, "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 } } }, "GiftCreditHistory" : { "type" : "object", "title" : "Gift Credit History Object", "description" : "The gift credit history object models an entry - positive or negative - for the organisation's gift credit purchase and spends.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "Unique identifier for this gift credit history entry.", "example" : "484ed6af-416e-1f76-7807-c88104734f09" }, "orderId" : { "type" : "string", "x-subtype" : "uuid", "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" }, "transactionId" : { "type" : "string", "x-subtype" : "uuid", "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" }, "type" : { "type" : "string", "description" : "A human-readable, brief description of what this entry is for, ie; `Credit Purchase`, `Order Placement`.\n", "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", "format" : "float", "description" : "Value that was either credited or debited from the organisation in this action.", "example" : 33 }, "changeNet" : { "type" : "number", "format" : "float", "description" : "Value that was either credited or debited from the organisation in this action, exclusive of tax.", "example" : 30 }, "changeTax" : { "type" : "number", "format" : "float", "description" : "Tax component for this transaction, were relevant. \n\n**Note:** currently, no region involves taxed gift card payments.\n", "example" : 3 }, "newBalance" : { "type" : "number", "format" : "float", "description" : "The current account gift credit balance at the time this change was effected.", "example" : 15.5 }, "effectiveTime" : { "type" : "string", "x-subtype" : "datetime", "description" : "Timestamp of when this gift 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" } } }, "Invitation" : { "type" : "object", "title" : "Invitation Object", "description" : "The invitation object provides detail on user that's been invited to your account and the status of that invitation.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "Unique identifier for this invitation.", "example" : "8d207658-12fc-6068-23fe-09135f7b31f1" }, "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" : { "type" : "object", "description" : "Permission-keyed list of permissions available once this invitation is accepted.", "properties" : { "useCredits" : { "type" : "boolean", "example" : true }, "useGiftCredit" : { "type" : "boolean", "example" : true }, "useSavedCard" : { "type" : "boolean", "example" : true } } }, "invited" : { "type" : "string", "x-subtype" : "datetime", "description" : "When the invitation was created.", "example" : "2022-03-14 12:34:27" }, "inviteSent" : { "type" : "string", "x-subtype" : "datetime", "description" : "When the user's email invitation was sent.", "example" : "2021-03-14 12:35:53" }, "accepted" : { "type" : "string", "x-subtype" : "datetime", "description" : "When the invitation was accepted, if at all.", "example" : null }, "expires" : { "type" : "string", "x-subtype" : "datetime", "description" : "When the invitation expires.", "example" : "2021-03-17 12:35:01" }, "links" : { "type" : "object", "properties" : { "accept" : { "type" : "string", "x-subtype" : "url", "description" : "The acceptance URL for this invitation.", "example" : "https://avengers.cardly.net/invitations/accept/8d207658-12fc-6068-23fe-09135f7b31f1/e167ed69-a05f-1b1c-2bb9-0cf8b73fb57c" } } } } }, "Media" : { "type" : "object", "title" : "Media Object", "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.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "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" }, "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", "format" : "float", "description" : "The number of credits that would be consumed when ordering this media type.", "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" : { "type" : "object", "description" : "Dimensions of this product in millimeters, exclusive of bleed.", "properties" : { "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 } } } } }, "bleed" : { "type" : "object", "description" : "DimensionsBleed zone of this product in millimeters, added to the `dimensions` measurements for the overall page size.\nUsing the provided example, this would be a 115x158mm product for the purposes of artwork dimensions.\n", "properties" : { "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 } } } } }, "art" : { "type" : "object", "properties" : { "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 } } } } } } }, "Order" : { "type" : "object", "title" : "Order Object", "description" : "The order object provides detail on a given order on your account, along with individual line item recipient, sender, cost and timing information.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "Unique identifier for this order.", "example" : "c988c0c0-f6a3-4e90-bbd5-759497a82607" }, "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" } } } }, "OrderCosts" : { "type" : "object", "title" : "Order Costs Object", "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.", "properties" : { "credits" : { "type" : "number", "format" : "float", "description" : "The total credits this order consumed, if paid by credits.", "example" : 0.5 }, "giftCredit" : { "type" : "number", "format" : "float", "description" : "TheThe total gift credits this order consumed, if paid by credits.", "example" : 45.67 }, "gross" : { "type" : "number", "format" : "float", "description" : "The gross cost of this order, exclusive of tax.", "example" : 6.58 }, "discount" : { "type" : "number", "format" : "float", "description" : "The discount amount for this order overall.", "example" : 0.98 }, "tax" : { "type" : "number", "format" : "float", "description" : "The total amount of tax on this order, exclusive of shipping.", "example" : 0.69 }, "shipping" : { "type" : "number", "format" : "float", "description" : "The total tax-exclusive cost of shipping for this order.", "example" : 1.54 }, "shippingTax" : { "type" : "number", "format" : "float", "description" : "The total amount of tax applied to shipping.", "example" : 0.15 }, "total" : { "type" : "number", "format" : "float", "description" : "The total cost of this order.", "example" : 7.98 }, "currency" : { "type" : "string", "description" : "The currency this order was priced in.", "example" : "USD" } } }, "OrderCustomer" : { "type" : "object", "title" : "Order Customer Details Object", "description" : "Details about the organisation or user that placed this order. For API-originating orders, this will be your organisation details.", "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!" } } }, "OrderTimings" : { "type" : "object", "title" : "Order Timings Object", "description" : "Contains details of the overall order creation, update and payment times.", "properties" : { "created" : { "type" : "string", "x-subtype" : "datetime", "description" : "When this order was first raised.", "example" : "2024-12-04 11:11:41" }, "paid" : { "type" : "string", "x-subtype" : "datetime", "description" : "When this order was paid - if currently marked as paid.", "example" : "2024-12-04 11:11:41" }, "updated" : { "type" : "string", "x-subtype" : "datetime", "description" : "When this order was last updated.", "example" : "2024-12-04 12:11:46" } } }, "OrderItem" : { "type" : "object", "title" : "Order Item Object", "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).", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "Unique identifier for this order item.", "example" : "60051a2c-86af-45bb-a34f-febf37d9070c" }, "type" : { "type" : "string", "description" : "The type of item this is - typically `card`.", "example" : "card" }, "media" : { "type" : "string", "x-subtype" : "uuid", "description" : "The media ID relevant to this item, if a printed card/letter.", "example" : "51897b27-81d6-e82b-dcfe-36f748d516e9" }, "artwork" : { "type" : "string", "x-subtype" : "uuid", "description" : "The artwork ID relevant to this item, if a printed card/letter.", "example" : "5c40d96b-b7c3-4980-9bdc-14306104ebd4" }, "template" : { "type" : "string", "x-subtype" : "uuid", "description" : "The template ID relevant to this item, if a printed card/letter.", "example" : "73bf3d63-5bca-45dc-86f6-d5c01946d78b" }, "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`.", "enum" : [ "standard", "tracked", "express" ], "example" : "standard" }, "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" } } } }, "OrderItemRelated" : { "type" : "object", "title" : "Related Item Object", "description" : "A component of a parent OrderItem, such as an additional envelope or gift card.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "Unique identifier for this order item.", "example" : "60051a2c-86af-45bb-a34f-febf37d9070c" }, "type" : { "type" : "string", "description" : "The type of item this is - typically `gift-card` or `envelope`.", "enum" : [ "gift-card", "envelope" ], "example" : "card" }, "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" } ] } } }, "OrderItemAddress" : { "type" : "object", "title" : "Order Item Address Object", "description" : "Describes an addressing element such as sender or recipient or for a given order item.", "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 } } }, "OrderItemCosts" : { "type" : "object", "title" : "Order Item Costs Object", "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.", "properties" : { "credits" : { "type" : "number", "format" : "float", "description" : "The total credits this item consumed, if paid by credits.", "example" : 0.5 }, "giftCredit" : { "type" : "number", "format" : "float", "description" : "The amount of gift credit used for this item in the order's currency, if relevant.", "example" : 45.67 }, "gross" : { "type" : "number", "format" : "float", "description" : "The gross unit cost of this item, exclusive of tax.", "example" : 6.58 }, "discount" : { "type" : "number", "format" : "float", "description" : "The discount amount per unit for this item.", "example" : 0.98 }, "tax" : { "type" : "number", "format" : "float", "description" : "The amount of tax per unit on this item, exclusive of shipping.", "example" : 0.69 }, "shipping" : { "type" : "number", "format" : "float", "description" : "The per-unit tax-exclusive cost of shipping for this item.", "example" : 1.54 }, "shippingTax" : { "type" : "number", "format" : "float", "description" : "The amount per unit of tax applied to shipping.", "example" : 0.15 }, "total" : { "type" : "number", "format" : "float", "description" : "The final per unit cost, inclusive of tax, shipping and discounts for this item.", "example" : 7.98 }, "currency" : { "type" : "string", "description" : "The currency this item was priced in.", "example" : "USD" } } }, "OrderItemDelivery" : { "type" : "object", "title" : "Order Item Delivery Details", "description" : "Describes requested and estimated delivery windows for a given item.", "properties" : { "requested" : { "type" : "string", "x-subtype" : "date", "description" : "The arrival date requested, if applicable. This will be null where you did not specify a requested delivery date.", "example" : "2024-12-25" }, "dispatch" : { "type" : "string", "x-subtype" : "date", "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" }, "estimatedMinArrival" : { "type" : "string", "x-subtype" : "date", "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" }, "estimatedMaxArrival" : { "type" : "string", "x-subtype" : "date", "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" } } }, "OrderItemTimings" : { "type" : "object", "title" : "Order Item Timings Object", "description" : "Describes various timings within an card's lifecycle, from request to lodgement, production and dispatch.", "properties" : { "lodgeAfter" : { "type" : "string", "x-subtype" : "datetime", "description" : "The scheduled time for sending this item to print. Lodgement will always occur after this time.", "example" : "2024-12-04 11:12:00" }, "lodged" : { "type" : "string", "x-subtype" : "datetime", "description" : "When this item was sent to print.", "example" : "2024-12-04 11:24:41" }, "shipped" : { "type" : "string", "x-subtype" : "datetime", "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" }, "held" : { "type" : "string", "x-subtype" : "datetime", "description" : "If this item is being held, the time the item was marked for holding.", "example" : "2024-12-04 12:06:46" } } }, "OrderItemTracking" : { "type" : "object", "title" : "Order Item Tracking Object", "description" : "Describes requested and estimated delivery windows for a given item.", "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" } } }, "Style" : { "type" : "object", "title" : "Style Object", "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.", "properties" : { "align" : { "type" : "string", "description" : "One of `left` (default) or `center` to denote text flow behaviour.", "enum" : [ "left", "center" ], "example" : "left" }, "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.\n\n**Note:** This feature is experimental and should be used with caution.\n", "enum" : [ "top", "center", "bottom" ], "example" : "top" }, "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" } } }, "Template" : { "type" : "object", "title" : "Template Object", "description" : "The template object denotes styling and structure to be applied to a given media size card.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "Unique identifier for this template option.", "example" : "18ecf6e6-d2e2-49cb-bae0-fa980241db73" }, "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" : { "type" : "object", "description" : "If this template contains a gift card, describes the type of card selected and the value of the card.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "The unique ID of the gift card that has been included.", "example" : "4b458510-5b7f-0bdc-7e21-891ce658a935" }, "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", "format" : "float", "description" : "The amount of funds provided on this gift card.", "example" : 50 }, "canChange" : { "type" : "boolean", "description" : "Whether or not the recipient can swap this card for another.", "example" : true } } }, "definition" : { "type" : "object", "description" : "An object describing this template's layout.", "properties" : { "version" : { "type" : "number", "format" : "float", "description" : "The version of the Cardly editor this template was created by.", "example" : 2.2 }, "style" : { "type" : "object", "description" : "The default styles to filter through to pages in this template, if no styles are defined at the page level.", "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" } } }, "pages" : { "type" : "array", "items" : { "type" : "object" }, "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" : [ ] }, "variables" : { "type" : "object", "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.", "properties" : { "firstName" : { "type" : "object", "properties" : { "description" : { "type" : "string", "example" : "Customer's first name to display in card front and salutation." }, "example" : { "type" : "string", "example" : "John" } } } } } } }, "createdAt" : { "type" : "string", "format" : "date-time", "description" : "`YYYY-MM-DDTHH:ii:ss+00:00` formatted string to denote when this template was created.\n", "example" : "2020-06-14T09:40:09+10:00" }, "updatedAt" : { "type" : "string", "format" : "date-time", "description" : "`YYYY-MM-DDTHH:ii:ss+00:00` formatted string to denote when this template was last updated.\n", "example" : "2020-06-14T14:39:35+10:00" } } }, "User" : { "type" : "object", "title" : "User Object", "description" : "The user object provides detail on user has accepted an invitation to use your to your account.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "Unique identifier for this user.", "example" : "8d207658-12fc-6068-23fe-09135f7b31f1" }, "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" : { "type" : "object", "description" : "Permission-keyed list of permissions available to this user.", "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 } } } } }, "WritingStyle" : { "type" : "object", "title" : "Writing Style Object", "description" : "The writing object denotes a messiness level applied to our algorithmic handwriting generation.", "properties" : { "id" : { "type" : "string", "x-subtype" : "uuid", "description" : "Unique identifier for this writing style option.", "example" : "18ecf6e6-d2e2-49cb-bae0-fa980241db73" }, "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 } } } } } }