openapi: 3.1.0 servers: - description: Cardly v2 Primary Endpoint url: https://api.card.ly/v2 info: version: 2.2.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. When you're set up on the Cardly API, you'll be provided with two API keys - one for test mode, the other for live calls. Your test mode key will allow you to make all the calls available in the API, however won't mutate any data. So, you can test your integration and make sure everything works, get back (generally!) the same response as you would for a live call, then switch out your keys when you're ready to move to live ordering. Currently the API accepts only JSON-encoded bodies for POST requests. As such, please ensure you provide the appropriate `Content-type: text/json` header when forming your requests. Other content types will likely fail as the request body will not be interpreted correctly. As we release new products and features, the Cardly API will evolve to include access to these where possible. This documentation will also evolve to cover these new features as they're released. While we do our best to avoid it, in the event we release a breaking change, we'll let you know well in advance so you have time to plan, test and release any updates necessary to accommodate the change. 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. This endpoint is special in that it will accept **any** HTTP verb and still provide an output to the caller. **Please note:** you must still authenticate to this endpoint and you'll receive appropriate error responses if your API key is invalid or not supplied. 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. Where relevant, API calls which consume or have the potential to consume balance will return your organisation's balance in the return structure for convenience. This will allow you to easily determine if additional balance should be added to your account if not utilising the automatic account topup feature. 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. This request accepts standard pagination options `limit, offset` along with the following additional filters: parameters: - in: query name: effectiveTime.lt description: > `YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *before* this time. 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. schema: type: string - in: query name: effectiveTime.gt description: > `YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *after* this time. 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. 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. This request accepts standard pagination options `limit, offset` along with the following additional filters: parameters: - in: query name: effectiveTime.lt description: > `YYYY-MM-DD HH:ii:ss` formatted string to retrieve only results *before* this time. 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. 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. 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. 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. This request accepts standard pagination options `limit, offset` along with the following additional filters: 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. **Required** if adding a new field. description: type: string description: A longer description of this field, if required. type: type: string description: > The type of data this field models, one of text, date, number or url. **Required** if adding a new field. **Ignored** if updating an existing field. enum: - text - date - number - url remove: type: boolean description: If set to true, removes this field from the list. 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. 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. 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. **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. 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. **Conditionally required** based on the country supplied. 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. **Conditionally required** based on the country supplied. example: 12345 fields: type: object description: > Additional custom fields based on field codes for extended data on this contact record. For each custom field in your list, fields may be specified based on the unique field ID created by Cardly. Fields will be subject to data type checking where appropriate: **URL Fields** require full, complete URLs supplied, if used. **Number Fields** require any numeric string, free of any human readable formatting (ie, commas for thousands separators). example: birthday: '1052-04-01T00:00:00.000Z' 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. Contact matching is performed in order of matching external ID or email address. At least one of these details must be provided. 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. 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. 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. **Conditionally required** based on the country supplied. 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. **Conditionally required** based on the country supplied. example: 12345 fields: type: object description: > Additional custom fields based on field codes for extended data on this contact record. For each custom field in your list, fields may be specified based on the unique field ID created by Cardly. Fields will be subject to data type checking where appropriate: **URL Fields** require full, complete URLs supplied, if used. **Number Fields** require any numeric string, free of any human readable formatting (ie, commas for thousands separators). example: birthday: '1052-04-01T00:00:00.000Z' 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. 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. 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. Contact matching is performed in order of matching external ID or email address. At least one of these details must be provided, and the first matching contact (if found) is used for update operations. 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. **Conditionally required:** At least one of `externalId` or `email` is required for a sync operation. example: thor1234 firstName: type: string description: The first name of a contact. example: Thor lastName: type: string description: The last name of a contact, if known / applicable. example: Odinson email: type: string description: > An email address for this contact, if supplied, which can be used to uniquely identify this contact for subsequent actions. **Conditionally required:** At least one of `externalId` or `email` is required for a sync operation. example: thor@avengers.com company: type: string description: The company a contact belongs to, if required. example: Avengers Inc. address: type: string description: >- The primary address line, including street number, name and type. example: 1 Main Street address2: type: string description: >- A secondary address line, typically containing a unit, apartment, suite number etc. example: Suite 1451 locality: type: string description: A suburb or city for the contact. example: Brooklyn region: type: string description: | The state or province for this address. **Conditionally required** based on the country supplied. 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. **Conditionally required** based on the country supplied. example: 12345 fields: type: object description: > Additional custom fields based on field codes for extended data on this contact record. For each custom field in your list, fields may be specified based on the unique field ID created by Cardly. Fields will be subject to data type checking where appropriate: **URL Fields** require full, complete URLs supplied, if used. **Number Fields** require any numeric string, free of any human readable formatting (ie, commas for thousands separators). example: birthday: '1052-04-01T00:00:00.000Z' 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. This request accepts standard pagination options `limit, offset` along with the following additional filters: parameters: - in: query name: organisationOnly description: > If truthy, only return doodles that are exclusive to your organisation. 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. This request accepts standard pagination options `limit, offset` along with the following additional filters: parameters: - in: query name: organisationOnly description: > If truthy, only return fonts that are exclusive to your organisation. 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. This request accepts standard pagination options `limit, offset` along with the following additional filters: parameters: - in: query name: acceptedOnly description: | If truthy, only return accepted invitations. schema: type: boolean - in: query name: expiredOnly description: | If truthy, only return expired invitations. 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. 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. 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. items: type: string enum: - administrator - artwork - billing - campaigns - developer - lists - moderate - moderate-history - orders - templates - users - use-credits - use-saved-card example: - use-credits - use-gift-credits - use-saved-card 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. 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. 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. 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. 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. 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. 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. This request accepts standard pagination options `limit, offset` along with the following additional filters: parameters: - in: query name: organisationOnly description: > If truthy, only return media items that are exclusive to your organisation. 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. 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. 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. This call is intentionally nearly identical to the `PlaceOrder` function to facilitate testing and a quick migration to ordering. The main difference between these calls is a `PlaceOrder` request permits multiple line items with differing data and settings, while `Preview` deals with only a single card at a time. 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. **Please note:** If you have specified a template, the `style` element will override any properties the template has set as defaults. We suggest using this feature with care. allOf: - $ref: '#/components/schemas/Style' messages: 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. **Please note:** This should be used with care and thoroughly tested before you deploy your application to production. Cardly accepts no responsiblity for poorly designed cards when using this feature. allOf: - $ref: '#/components/schemas/Style' 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. **Conditionally required** based on the country supplied. example: NY postcode: type: string description: > The postcode for this recipient. Note that this may be empty for countries that do not utilise postcodes. **Conditionally required** based on the country supplied. example: 12345 country: type: string description: >- The 2-character ISO code for the country relating to this recipient. example: US required: - firstName - address - city - region - postcode - country sender: type: object description: > Details of the sender for this order. **Please note:** the entire sender section is optional and will default to your organisation's return details if not completed. If any sender element is specified, all must be specified. properties: firstName: type: string description: >- The sender's first name, as it should appear on the envelope. example: Bruce lastName: type: string description: >- The sender's last name, as it should appear on the envelope example: Banner company: type: string description: >- The sender's company, if required, as it should appear below their name on the envelope. example: Avengers Inc address: type: string description: The sender's street number, name and type. example: 1 Main Street address2: type: string description: >- Unit, floor, apartment etc. additional information for the sender's address. example: Suite 1054 city: type: string description: Suburb or city for the sender. example: Brooklyn region: type: string description: > State / province / region for the sender, if required. UK and NZ currently do not require a region specified. **Conditionally required** based on the country supplied. example: NY postcode: type: string description: > The postcode for this sender. Note that this may be empty for countries that do not utilise postcodes. **Conditionally required** based on the country supplied. example: 12345 country: type: string description: >- The 2-character ISO code for the country relating to this sender. example: US omitAddress: type: boolean description: > `true` to omit the return address entirely from a generated envelope. 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. Currently, only Australia supports the `tracked` shipping method. Currently, only Australia and the United States support the `express` shipping method. 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. 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-25T00:00:00.000Z' 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. Note that you must have sufficient credit on your account to place your order. If you have insufficient credit, a `402` response will be returned with detail on the required credit cost and your current balance. 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. 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. **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. 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. **Please note:** If you have specified a template, the `style` element will override any properties the template has set as defaults. We suggest using this feature with care. allOf: - $ref: '#/components/schemas/Style' messages: 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. **Please note:** This should be used with care and thoroughly tested before you deploy your application to production. Cardly accepts no responsiblity for poorly designed cards when using this feature. allOf: - $ref: '#/components/schemas/Style' 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. **Conditionally required** based on the country supplied. example: NY postcode: type: string description: > The postcode for this recipient. Note that this may be empty for countries that do not utilise postcodes. **Conditionally required** based on the country supplied. example: 12345 country: type: string description: >- The 2-character ISO code for the country relating to this recipient. example: US required: - firstName - address - city - country x-conditionallyRequired: - region - postcode sender: type: object description: > Details of the sender for this order. **Please note:** the entire sender section is optional and will default to your organisation's return details if not completed. If any sender element is specified, all must be specified. properties: firstName: type: string description: >- The sender's first name, as it should appear on the envelope. example: Bruce lastName: type: string description: >- The sender's last name, as it should appear on the envelope example: Banner company: type: string description: >- The sender's company, if required, as it should appear below their name on the envelope. example: Avengers Inc address: type: string description: The sender's street number, name and type. example: 1 Main Street address2: type: string description: >- Unit, floor, apartment etc. additional information for the sender's address. example: Suite 1054 city: type: string description: Suburb or city for the sender. example: Brooklyn region: type: string description: > State / province / region for the sender, if required. UK and NZ currently do not require a region specified. **Conditionally required** based on the country supplied. example: NY postcode: type: string description: > The postcode for this sender. Note that this may be empty for countries that do not utilise postcodes. **Conditionally required** based on the country supplied. example: 12345 country: type: string description: >- The 2-character ISO code for the country relating to this sender. example: US omitAddress: type: boolean description: > `true` to omit the return address entirely from a generated envelope. 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. Currently, only Australia supports the `tracked` shipping method. Currently, only Australia and the United States support the `express` shipping method. 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. 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-25T00:00:00.000Z' 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. 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. 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. **Please note:** Access can not be removed for users with `administrator` privileges on your account. These must be removed via your portal directly. 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. 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. **Please note:** Access can not be removed for users with `administrator` privileges on your account. These must be removed via your portal directly. 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. 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' /webhooks: get: tags: - Webhooks operationId: getWebhookListing summary: List Webhooks description: | Retrieve any active or disabled webhooks set up for your organisation. responses: '200': description: A paginated array of zero or more `Webhook` 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 `Webhook` objects. items: $ref: '#/components/schemas/Webhook' post: tags: - Webhooks operationId: postWebhookCreate summary: Create Webhook description: > Create a new webhook for the specified targetUrl. Webhooks allow for near-realtime notifications of events within your Cardly account. requestBody: content: application/json: schema: type: object properties: targetUrl: type: string description: >- The URL this webhook will send POST requests to once one of its subscribed events is triggered. example: https://www.stark-industries.com/postbacks/inbound events: type: array items: type: string enum: - contact.order.created - contact.order.sent - contact.order.refunded - giftCard.redeemed - qrCode.scanned - contact.undeliverable - contact.changeOfAddress - consignment.undeliverable - consignment.changeOfAddress description: >- The events this webhook is subscribed to. You will only receive notifications for these events. example: - contact.order.created - contact.order.sent - contact.undeliverable - contact.changeOfAddress description: type: string description: >- A free text description of what this webhook is for, or any notes related to the webhook. example: >- Aid with feeding send data and change-of-address information back into our CRM. metadata: type: object description: >- A set of key-value pairs that you can attach to this webhook. This can be useful for storing additional information about the webhook in a structured format. required: - targetUrl - events responses: '200': description: > A `Webhook` representing the webhook that was just created. Use the ID property from this to feed into further requests as needed. This Webhook object will also contain a *secret* property. This is the only time we'll provide this secret to you. You should store it securely and use it to verify the signature any postbacks received via this webhook. Further details can be found in the Webhooks section of this documentation. content: application/json: schema: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/Webhook' '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' /webhooks/{id}: get: tags: - Webhooks operationId: getWebhook summary: Get Webhook Details description: | Get details on an existing webhook. parameters: - in: path name: id description: The unique ID of the webhook to retrieve. schema: type: string required: true responses: '200': description: > A `Webhook` representing the object that was requested. Note that the *secret* property will be obfuscated. content: application/json: schema: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/Webhook' '404': description: A status indicating that the specified webhook could not be found. content: application/json: schema: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/ValidationStatus' post: tags: - Webhooks operationId: postWebhookUpdate summary: Update Webhook description: > Update a webhook with one or more changes based on the passed properties. Note that changes to the targetUrl or status are immediate, and will update where postbacks are sent for any postbacks queued for retry, or cease sending postbacks if *disabled* is true. parameters: - in: path name: id description: The unique ID of the webhook to update. schema: type: string required: true requestBody: content: application/json: schema: type: object properties: targetUrl: type: string description: >- The URL this webhook will send POST requests to once one of its subscribed events is triggered. example: https://www.stark-industries.com/postbacks/inbound events: type: array items: type: string enum: - contact.order.created - contact.order.sent - contact.order.refunded - giftCard.redeemed - qrCode.scanned - contact.undeliverable - contact.changeOfAddress - consignment.undeliverable - consignment.changeOfAddress description: >- The events this webhook is subscribed to. You will only receive notifications for these events. example: - contact.order.created - contact.order.sent - contact.undeliverable - contact.changeOfAddress description: type: string description: >- A free text description of what this webhook is for, or any notes related to the webhook. example: >- Aid with feeding send data and change-of-address information back into our CRM. disabled: type: boolean description: >- If supplied and truthy, disables the webhook. If supplied and falsey, enables it instead. metadata: type: object description: >- A set of key-value pairs that you can attach to this webhook. This can be useful for storing additional information about the webhook in a structured format. responses: '200': description: > A `Webhook` representing the object that was updated. Note that the *secret* property will be obfuscated. content: application/json: schema: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/Webhook' '404': description: A status indicating that the specified webhook could not be found. content: application/json: schema: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/ValidationStatus' '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: - Webhooks operationId: postWebhookDelete summary: Delete Webhook description: > Delete a given webhook and cease all activity and event subscriptions immediately. parameters: - in: path name: id description: The unique ID of the webhook to delete. schema: type: string required: true responses: '200': description: > A `Webhook` representing the webhook that was deleted. This webhook will cease any further callbacks, including those queued for retry. content: application/json: schema: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/Webhook' '404': description: A status indicating that the specified webhook could not be found. content: application/json: schema: type: object properties: state: $ref: '#/components/schemas/ResponseStatus' data: $ref: '#/components/schemas/ValidationStatus' /writing-styles: get: tags: - Writing Styles operationId: getWritingStyleListing summary: List Writing Styles description: | Retrieve your currently available writing styles. 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. Each set of API keys provides both test and live mode keys. Test mode keys are prefixed with `test_` and can perform all the functions that live keys can, however they will not perform any mutations. That is, if a test mode key calls the Place Order endpoint, the request will be validated and provide a mostly-identical response as though you'd used a live key, however no actual order will be placed. Test mode responses will always contain a `testMode: true` element as part of the main return body. Live mode keys are prefixed with `live_` and have none of the restrictions of test mode keys. Authentication to the API is performed via the `API-Key` header, as per the provided example. API keys permit many functions to be performed against your organisation, including billable requests. You must keep your keys secure and if you believe them to be compromised, invalidate and re-issue your keys via your organisation portal. **All API requests must be performed over HTTPS.** Calls made over plain HTTP will be rejected, as will requests without authentication. 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. example: '2020-06-13T23:40:09.000Z' 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. example: '2020-06-14T04:39:35.000Z' 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-01T00:00:00.000Z' 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`. 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-23T12:10:54.000Z' 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`. 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. **Note:** currently, no region involves taxed gift card payments. 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-23T12:10:54.000Z' 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-14T12:34:27.000Z' inviteSent: type: string x-subtype: datetime description: When the user's email invitation was sent. example: '2021-03-14T12:35:53.000Z' 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-17T12:35:01.000Z' 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. Using the provided example, this would be a 115x158mm product for the purposes of artwork dimensions. 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-04T11:11:41.000Z' paid: type: string x-subtype: datetime description: When this order was paid - if currently marked as paid. example: '2024-12-04T11:11:41.000Z' updated: type: string x-subtype: datetime description: When this order was last updated. example: '2024-12-04T12:11:46.000Z' 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-25T00:00:00.000Z' 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-25T00:00:00.000Z' 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-12T00:00:00.000Z' estimatedMinArrival: type: string x-subtype: date description: > The estimated earliest date an order should be received. **Note that this is subject to end postal carriers** and beyond the control of Cardly directly. example: '2024-12-17T00:00:00.000Z' estimatedMaxArrival: type: string x-subtype: date description: > The estimated latest date an order should be received. **Note that this is subject to end postal carriers** and beyond the control of Cardly directly. example: '2024-12-20T00:00:00.000Z' 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-04T11:12:00.000Z' lodged: type: string x-subtype: datetime description: When this item was sent to print. example: '2024-12-04T11:24:41.000Z' shipped: type: string x-subtype: datetime description: > When this item was shipped. **Please note:** We rely on external data to populate this and it may not always be immediately available. example: '2024-12-04T12:11:46.000Z' held: type: string x-subtype: datetime description: >- If this item is being held, the time the item was marked for holding. example: '2024-12-04T12:06:46.000Z' 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: 56116819325 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. **Note:** This feature is experimental and should be used with caution. 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. example: '2020-06-13T23:40:09.000Z' updatedAt: type: string format: date-time description: > `YYYY-MM-DDTHH:ii:ss+00:00` formatted string to denote when this template was last updated. example: '2020-06-14T04:39:35.000Z' 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 Webhook: type: object title: Webhook Object description: >- The webhook object provides detail on a REST webhook you or a third party platform such as Zapier has set up to provide near-realtime notifications of events within your Cardly business account. properties: id: type: string x-subtype: uuid description: Unique identifier for this webhook. example: d2e2f6e6-9802-bae0-bae0-fa980241db73 secret: type: string description: >- The webhook's secret key which can be used to verify postbacks. The full secret is only supplied once at creation time. You should note this secret if you intend to verify postback signatures, which we highly recommend. example: 30f34805d37595098a54b3123b4357f7 status: type: string description: The status of this webhook, typically one of `active` or `disabled`. example: active protected: type: boolean description: >- Whether or not this webhook was created by a third party platform such as Zapier and care should be taken with updating or deleting it to not break other integrations you may have. targetUrl: type: string description: >- The URL this webhook will send POST requests to once one of its subscribed events is triggered. example: https://www.stark-industries.com/postbacks/inbound description: type: string description: >- A free text description of what this webhook is for, or any notes related to the webhook. example: >- Aid with feeding send data and change-of-address information back into our CRM. metadata: type: object description: >- A structure of key:value pairs that you've supplied to provide additional detail for this webhook, if required. events: type: array items: type: object description: >- The events this webhook is subscribed to. You will only receive notifications for these events. example: - contact.order.created - contact.order.sent - contact.undeliverable - contact.changeOfAddress createdAt: type: string format: date-time description: > `YYYY-MM-DDTHH:ii:ss+00:00` formatted string to denote when this webhook was created. example: '2020-06-14T09:40:09.000Z' updatedAt: type: string format: date-time description: > `YYYY-MM-DDTHH:ii:ss+00:00` formatted string to denote when this webhook was last updated. example: '2020-06-14T14:39:35.000Z' 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