{ "openapi": "3.1.0", "x-mint": { "mcp": { "enabled": true } }, "x-mcp": { "enabled": true }, "info": { "title": "thanks.io API", "description": "Use the thanks.io API to send postcards, letters, notecards, windowless letters, and gift cards.", "contact": { "url": "https://thanks.io", "email": "support@thanks.io" }, "version": "1.0.0" }, "externalDocs": { "description": "Learn more about thanks.io", "url": "https://docs.thanks.io" }, "servers": [ { "url": "https://api.thanks.io/api/v2", "description": "The main API server for thanks.io" } ], "components": { "examples": { "recipient-example": { "summary": "Example Recipient", "value": { "id": 18113288, "mailing_list_id": 1, "name": "Tobias Example", "company": "thanks.io", "address": "12345 Main Street", "address2": "Apartment 1", "city": "Any Town", "province": "NY", "postal_code": "12345", "country": "US", "dob": "1981-04-23", "anniversary": "2025-07-21", "email": "tobias@example.com", "phone": "845-988-6485", "custom1": "Unique Info", "custom2": "For example a product code or customer ID", "custom3": "", "custom4": "", "created_at": "2025-06-27T14:57:11.000000Z", "updated_at": "2025-06-27T14:57:11.000000Z", "mailing_list": { "id": 1, "user_id": 2, "sub_account_id": null, "type": "manual", "description": "Sphere Contacts Mailing List", "qrcode_url": null, "total_recipients": 1, "processed": true, "is_suppression_list": false, "total_scans": 1, "unique_scans": 1, "last_scan": "2025-07-13T13:57:11.000000Z", "total_sends": 2, "last_send": "2025-07-06T13:57:11.000000Z", "created_at": "6 years ago", "updated_at": "2025-06-27T14:57:11.000000Z" } } }, "mailing-list-example": { "summary": "Example Mailing List", "value": { "id": 3020, "user_id": 2, "sub_account_id": null, "type": "manual", "description": "Birthday List", "qrcode_url": null, "total_recipients": 0, "processed": true, "is_suppression_list": false, "total_scans": 0, "unique_scans": 0, "last_scan": null, "total_sends": 0, "last_send": null, "api_key": "167ba7f0-72de-11f0-b054-6d9179a1fdb2", "created_at": "2025-08-06T15:57:43.000000Z", "created_at_diff": "18 minutes ago", "updated_at": "2025-08-06T15:57:43.000000Z" } }, "sub-account-example": { "summary": "Example Sub Account", "value": { "id": 1, "user_id": 2, "title": "My New Sub Account", "return_name": "John Smith", "return_address": "123 Smith Street 11", "return_address2": "Apt 1", "return_city": "Denver", "return_state": "CO", "return_postal_code": "12345", "message_background_url": null, "postcard6x9_background_url": null, "notecard_background_url": null, "windowedletter_background_url": null, "windowlessletter_background_url": null, "branding_fields": { "accentColor": "#5f01d1", "symbol": "", "logo": "https://s3.amazonaws.com/content.thanks.io/templates/dynamic-images/5dcb82c0-f258-11ef-9c99-e542d768ea52.png", "disclaimer": null, "headshot": null, "name": "John Gray", "email": "test@test.com", "phone": "1234567890", "company": null, "domain": null, "set": true, "first_name": "John" }, "created_at": "2020-02-14 20:50:02", "updated_at": "2025-07-16 19:03:31" } } }, "parameters": { "items_per_page": { "name": "items_per_page", "in": "query", "description": "Number of items to return per page.", "required": false, "schema": { "type": "integer", "default": 25 }, "example": 5 }, "sub_account_id": { "name": "sub_account_id", "in": "query", "description": "Filter results by Sub Account ID.", "required": false, "schema": { "type": "integer" }, "example": 1 } }, "schemas": { "webhook-type": { "type": "string", "enum": [ "order_item.status_update", "order.status_update", "order_item.delivered", "scans.scan_update", "scan_board.status_update" ], "example": "order_item.status_update" }, "webhook-data-flat": { "type": "object", "description": "Flat payload object used by webhook events. Each property is a dotted key matching the published webhook payload structure.", "properties": { "order_item.id": { "type": ["integer", "null"], "example": 2668662 }, "order_item.scans": { "type": ["integer", "null"], "example": null }, "order_item.failure": { "type": ["string", "null"], "example": null }, "recipient.name": { "type": ["string", "null"], "example": "John Doe" }, "recipient.company": { "type": ["string", "null"], "example": null }, "recipient.address": { "type": ["string", "null"], "example": "123 Fake St" }, "recipient.address2": { "type": ["string", "null"], "example": null }, "recipient.absentee_address": { "type": ["string", "null"], "example": null }, "recipient.city": { "type": ["string", "null"], "example": "Any Town" }, "recipient.province": { "type": ["string", "null"], "example": "NY" }, "recipient.postal_code": { "type": ["string", "null"], "example": "12345" }, "recipient.country": { "type": ["string", "null"], "example": "US" }, "recipient.email": { "type": ["string", "null"], "example": null }, "recipient.phone": { "type": ["string", "null"], "example": null }, "recipient.custom_1": { "type": ["string", "null"], "example": "Example Custom 1" }, "recipient.custom_2": { "type": ["string", "null"], "example": "Example Custom 2" }, "recipient.custom_3": { "type": ["string", "null"], "example": "Example Custom 3" }, "recipient.custom_4": { "type": ["string", "null"], "example": "Example Custom 4" }, "recipient.custom_5": { "type": ["string", "null"], "example": "Example Custom 5" }, "recipient.custom_6": { "type": ["string", "null"], "example": "Example Custom 6" }, "recipient.custom_7": { "type": ["string", "null"], "example": "Example Custom 7" }, "recipient.custom_8": { "type": ["string", "null"], "example": "Example Custom 8" }, "recipient.custom_9": { "type": ["string", "null"], "example": "Example Custom 9" }, "recipient.custom_10": { "type": ["string", "null"], "example": "Example Custom 10" }, "order.id": { "type": ["integer", "null"], "example": 42399 }, "order.sub_account_id": { "type": ["integer", "null"], "example": 5 }, "order.status": { "type": ["string", "null"], "example": "Printing" }, "order_item.delivery_date": { "type": ["string", "null"], "example": "2025-07-05" }, "order_item.previous_status": { "type": ["string", "null"], "example": null }, "order_item.current_status": { "type": ["string", "null"], "example": "Processing" }, "qrcode.url": { "type": ["string", "null"], "format": "uri", "example": "https://www.google.com" }, "order.metadata": { "type": ["object", "null"], "description": "The metadata object submitted with the order, returned exactly as it was sent. Null when the order was created without metadata.", "additionalProperties": true, "example": { "crm_deal_id": "D-1042" } } }, "additionalProperties": false }, "webhook-order-status-update-payload": { "type": "object", "properties": { "order.id": { "type": "integer", "example": 42401 }, "order.status": { "type": "string", "description": "The order's status after the change, in the same display form used throughout the dashboard and the order endpoints.", "example": "Printing" }, "order.previous_status": { "type": ["string", "null"], "description": "The status the order moved from, in lower case. Null if the order had no status before the change.", "example": "reviewing" }, "order.current_status": { "type": "string", "description": "The status the order moved to, in lower case. This is the same change reported by `order.status`, which gives the display form of the value.", "example": "processing" }, "order.metadata": { "type": ["object", "null"], "description": "The metadata object submitted with the order, returned exactly as it was sent. Null when the order was created without metadata.", "additionalProperties": true, "example": { "crm_deal_id": "D-1042" } } }, "additionalProperties": false }, "webhook-order-item-status-update-payload": { "$ref": "#/components/schemas/webhook-data-flat" }, "webhook-order-item-delivered-payload": { "$ref": "#/components/schemas/webhook-data-flat" }, "webhook-scan-update-payload": { "$ref": "#/components/schemas/webhook-data-flat" }, "scan-board-status": { "type": "string", "description": "A QR Scan Board stage.", "enum": ["new", "contacted", "follow_up", "done"], "example": "contacted" }, "webhook-scan-board-status-update-payload": { "allOf": [ { "$ref": "#/components/schemas/webhook-data-flat" }, { "type": "object", "properties": { "scan_board.card_id": { "type": "integer", "description": "The ID of the card on your Scan Board.", "example": 1187 }, "scan_board.previous_status": { "type": ["string", "null"], "description": "The stage the card left. null for a new card.", "enum": ["new", "contacted", "follow_up", "done", null], "example": "new" }, "scan_board.current_status": { "$ref": "#/components/schemas/scan-board-status" }, "scan_board.last_scanned_at": { "type": ["string", "null"], "description": "When the mailer was last scanned.", "example": "2025-06-24 23:19:06" } } } ] }, "order": { "type": "object", "properties": { "id": { "type": "integer", "example": 42708 }, "message": { "type": "string", "example": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" }, "size": { "type": "string", "description": "Only valid for postcards", "example": "4x6" }, "sub_account_id": { "type": ["integer", "null"], "example": null }, "type": { "type": "string", "enum": [ "postcard", "postcard6x9", "postcard6x11", "letter", "notecard", "giftcard", "windowlessletter" ], "example": "postcard" }, "display_type": { "type": "string", "example": "Postcard-4x6" }, "style": { "type": "integer", "description": "Handwriting Style ID used for this order", "example": 1 }, "front_image": { "type": "string", "example": "https://cdn.thanks.io/letter-backgrounds/bg0.png" }, "high_quality_preview": { "type": "string", "description": "PDF of the high quality preview of the order" }, "authorization_total": { "type": "integer", "example": 73 }, "grand_total": { "type": "integer", "example": 73 }, "order_total": { "type": "integer", "example": 73 }, "total_estimated_recipients": { "type": "integer", "example": 1 }, "total_recipients": { "type": "integer", "example": 1 }, "recipient_count": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "Fulfilled" }, "method": { "type": "string", "example": "Campaign" }, "cancellable": { "type": "boolean", "example": false }, "total_scans": { "type": "integer", "example": 0 }, "metadata": { "type": ["object", "null"], "description": "The metadata object submitted with the order, returned exactly as it was sent. Null when the order was created without metadata.", "additionalProperties": true, "example": { "crm_deal_id": "D-1042" } }, "created_at": { "type": "string", "format": "date-time", "example": "2025-09-08T16:05:12.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-09-08T16:06:08.000000Z" } } }, "order-item": { "type": "object", "description": "A single mail piece within an order — one recipient's postcard, letter, notecard, magnacard or gift card.", "properties": { "id": { "type": "integer", "description": "ID of the order item. This is the same identifier carried by order item webhook events.", "example": 2668662 }, "status": { "type": "string", "description": "Current delivery status of this piece.", "enum": ["Processing", "Printed", "In Transit", "In Local Area", "Processed for Delivery", "Delivered", "Re-routed", "Returned to Sender", "Failed"], "example": "In Transit" }, "delivery_date": { "type": ["string", "null"], "format": "date", "description": "Date the piece was delivered, or `null` if it has not been delivered yet.", "example": "2025-09-15" }, "scans": { "type": "integer", "description": "Number of times this piece's QR code has been scanned.", "example": 0 }, "failure": { "type": ["string", "null"], "description": "Reason the piece could not be mailed or delivered, or `null` if there was no failure.", "example": "USPS lists address as 'no-stat' - address is unlikely to receive mail." }, "recipient": { "type": "object", "description": "Recipient details as submitted with the order \u2014 the mailing address plus the ten custom fields.", "properties": { "name": { "type": ["string", "null"], "example": "Tobias Example" }, "company": { "type": ["string", "null"], "example": "thanks.io" }, "address": { "type": ["string", "null"], "example": "12345 Main Street" }, "address2": { "type": ["string", "null"], "example": "Apartment 1" }, "city": { "type": ["string", "null"], "example": "Any Town" }, "province": { "type": ["string", "null"], "description": "State or Province", "example": "KS" }, "postal_code": { "type": ["string", "null"], "example": "12345" }, "country": { "type": ["string", "null"], "example": "US" }, "email": { "type": ["string", "null"], "example": "tobias@example.com" }, "phone": { "type": ["string", "null"], "example": "5555555555" }, "custom1": { "type": ["string", "null"], "description": "Custom field 1 as submitted with the order.", "example": "Unique Info" }, "custom2": { "type": ["string", "null"], "description": "Custom field 2 as submitted with the order.", "example": "For example a product code or customer ID" }, "custom3": { "type": ["string", "null"], "description": "Custom field 3 as submitted with the order.", "example": "" }, "custom4": { "type": ["string", "null"], "description": "Custom field 4 as submitted with the order.", "example": "" }, "custom5": { "type": ["string", "null"], "description": "Custom field 5 as submitted with the order.", "example": "" }, "custom6": { "type": ["string", "null"], "description": "Custom field 6 as submitted with the order.", "example": "" }, "custom7": { "type": ["string", "null"], "description": "Custom field 7 as submitted with the order.", "example": "" }, "custom8": { "type": ["string", "null"], "description": "Custom field 8 as submitted with the order.", "example": "" }, "custom9": { "type": ["string", "null"], "description": "Custom field 9 as submitted with the order.", "example": "" }, "custom10": { "type": ["string", "null"], "description": "Custom field 10 as submitted with the order.", "example": "" }, "absentee_address": { "type": ["string", "null"], "description": "The absentee (property) address as it was when this piece was sent, or null. Mail was delivered to `address`.", "example": "742 Evergreen Terrace, Springfield, IL 62704" } } }, "giftcard": { "type": ["object", "null"], "description": "Present only on gift card orders. `null` when the gift card for this piece has not been issued yet. The redemption code, claim link and rendered card image are never returned.", "properties": { "brand": { "type": "string", "description": "Brand code of the gift card.", "example": "amazonus" }, "amount": { "type": "integer", "description": "Face value of the gift card in cents.", "example": 2500 }, "redeemed_at": { "type": ["string", "null"], "format": "date-time", "description": "When the recipient redeemed the gift card, or `null` if it has not been redeemed.", "example": null }, "invalidated_at": { "type": ["string", "null"], "format": "date-time", "description": "When the gift card was invalidated, or `null` if it has not been. An invalidated gift card can no longer be redeemed.", "example": null } } }, "preview": { "type": "object", "description": "The rendered proof of this recipient's piece, personalized with their name, address and custom fields. Each value is `null` until the piece has been rendered, which happens shortly after the order is placed, and stays `null` for a piece that failed before rendering. Absent on gift card orders: the rendered card carries the redemption code, so it is never returned.", "properties": { "front": { "type": ["string", "null"], "format": "uri", "description": "Image of the front of the piece. For a letter or windowless letter, the first page.", "example": "https://cdn.thanks.io/orders/items/proofs/front-example.png" }, "back": { "type": ["string", "null"], "format": "uri", "description": "Image of the back of the piece. Postcards and magnacards only; `null` for other mailer types.", "example": "https://cdn.thanks.io/orders/items/proofs/back-example.png" }, "pdf": { "type": ["string", "null"], "format": "uri", "description": "PDF proof of the full piece. Letters, windowless letters and notecards only; `null` for other mailer types.", "example": null } } }, "created_at": { "type": "string", "format": "date-time", "example": "2025-09-08T16:05:12.000000Z" } } }, "giftcard-group": { "type": "object", "properties": { "title": { "type": "string", "description": "Giftcard Brand Grouping Title" }, "brands": { "type": "array", "items": { "type": "object", "properties": { "brand_code": { "type": "string", "description": "Code to send to the API to use this brand" }, "title": { "type": "string", "description": "Giftcard Brand Title to display to users" }, "image": { "type": "string", "description": "Image URL for the brand to display to users" }, "available_amounts": { "type": "array", "description": "Available amounts for this brand in cents", "items": { "type": "integer" } } } } } } }, "giftcard-group-list": { "type": "object", "properties": { "brands": { "type": "array", "items": { "type": "object", "properties": { "brand_code": { "type": "string", "description": "Code to send to the API to use this brand", "example": "amazonus" }, "title": { "type": "string", "description": "Giftcard Brand Title to display to users", "example": "Amazon.com" }, "image": { "type": "string", "description": "Image URL for the brand to display to users", "example": "https://s3.amazonaws.com/cdn.thanks.io/giftcards/amazonus.png" }, "available_amounts": { "type": "array", "description": "Available amounts for this brand in cents", "items": { "type": "integer", "example": 1000 } }, "group": { "type": "string", "description": "Giftcard Brand Grouping Title", "example": "Featured" } } } } } }, "mailing-list": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 2 }, "sub_account_id": { "type": ["integer", "null"] }, "type": { "type": "string", "example": "manual", "enum": [ "csv", "manual", "map", "friends", "retarget", "leads", "zapier", "radius", "highlevel", "qrscans" ] }, "description": { "type": "string", "example": "Test" }, "qrcode_url": { "type": ["string", "null"] }, "total_recipients": { "type": "integer", "example": 1 }, "processed": { "type": "boolean", "example": true }, "is_suppression_list": { "type": "boolean", "example": false }, "total_scans": { "type": "integer", "example": 0 }, "unique_scans": { "type": "integer", "example": 0 }, "last_scan": { "type": ["string", "null"] }, "total_sends": { "type": "integer", "example": 0 }, "last_send": { "type": ["string", "null"] }, "api_key": { "type": "string", "description": "API key that can be used to add recipients to this mailing list with thanks.io Webhooks", "example": "abcd1234efgh5678ijkl9012mnop3456" }, "created_at": { "type": "string", "example": "2018-07-15T06:06:57.000000Z", "format": "date-time" }, "created_at_diff": { "type": "string", "example": "6 years ago", "description": "Human-friendly relative time since creation" }, "updated_at": { "type": "string", "example": "2025-06-27T14:57:11.000000Z", "format": "date-time" } } }, "image-template": { "type": "object", "properties": { "id": { "type": "integer", "example": 6 }, "user_id": { "type": "integer", "example": 2 }, "sub_account_id": { "type": "integer", "example": 55 }, "type": { "type": "string", "enum": [ "postcard", "postcard6x9", "postcard6x11", "letter", "notecard", "giftcard", "windowlessletter", "magnacard" ], "example": "postcard" }, "name": { "type": "string", "example": "Thank You Image" }, "image": { "type": "string", "description": "URL of the template image", "example": "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png" }, "canva_id": { "type": "string", "example": "some-canva-id" }, "created_at": { "type": "string", "example": "2018-08-07 00:00:00" }, "updated_at": { "type": "string", "example": "2018-08-08 00:00:00" } } }, "creative": { "type": "object", "description": "A creative from your Creatives library: a saved pairing of an image template and a message template, sent exactly as saved by passing its `id` as `creative_id` to any send or estimate endpoint.", "properties": { "id": { "type": "integer", "description": "Pass this as `creative_id` to send the creative." }, "name": { "type": "string" }, "mailer_type": { "type": [ "string", "null" ], "description": "The type the creative sends as. `postcard` is 4x6." }, "postcard_size": { "type": [ "string", "null" ] }, "sub_account_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "hidden": { "type": "boolean" }, "default": { "type": "boolean" }, "preview_image_url": { "type": [ "string", "null" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "share_url": { "type": [ "string", "null" ] }, "is_complete": { "type": "boolean", "description": "Whether the creative can be sent: both sides present and not deleted (letters need only a message)." }, "needs": { "type": "array", "items": { "type": "string", "enum": [ "front", "message" ] }, "description": "The sides an incomplete creative is missing." }, "image_template": { "type": [ "object", "null" ], "description": "The front. `deleted` is true when the template was deleted after the creative was made. `tracked_qr_url` is set when the front prints a tracked thanks.io QR code over the one in your uploaded design, and is the address its scans go to." }, "message_template": { "type": [ "object", "null" ], "description": "The message. `deleted` is true when the template was deleted after the creative was made." }, "back_background": { "type": [ "object", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "absentee-address": { "type": "string", "description": "The property (absentee) address for this recipient, such as a house an absentee owner owns, as opposed to where they get mail. Give either the whole address here, or the street line here with `absentee_city`, `absentee_province` and `absentee_postal_code`. When set, the `~ABSENTEE_STREET~`, `~ABSENTEE_FULL_ADDRESS~`, `~FULL_ADDRESS~` and `~STREET_VIEW~` image template variables, and `%ABSENTEE_STREET%` in messages, use this address instead of the mailing address. The mailer is still delivered to `address`. Include the city, state and ZIP so Street View finds the right property. It is stored and returned in its own `absentee_address` field, and also copied into `custom2` when that is empty, so templates that print `%CUSTOM2%` keep working; a `custom2` you send is never changed. The older convention of `custom1` = `absentee` with `custom2` = the property address is still accepted and copied into `absentee_address`.", "example": "742 Evergreen Terrace" }, "absentee-city": { "type": "string", "description": "City of the absentee (property) address. Requires `absentee_address` in the same request.", "example": "Springfield" }, "absentee-province": { "type": "string", "description": "State or province of the absentee (property) address. Requires `absentee_address` in the same request.", "example": "IL" }, "absentee-postal-code": { "type": "string", "description": "ZIP or postal code of the absentee (property) address. Requires `absentee_address` in the same request.", "example": "62704" }, "creative-id": { "type": "integer", "description": "Recommended: send a saved creative instead of assembling image and message parameters per request. ID of a creative from your Creatives library (see List Creatives). The creative is sent exactly as saved: its image template, message template, handwriting and background all come from it. It cannot be combined with any parameter that changes those (image_template_id, message_template_id, front_image_url, message, the handwriting and custom background parameters, pdf_only_url, skip_creative_generation, or for gift cards giftcard_brand and giftcard_amount_in_cents); a request that does is rejected with a 422 naming them. Only qrcode_url and additional_pages_url can be added. The creative must belong to your account, be of the mailer type being sent (for postcards, the size being sent), and be complete (`is_complete: true`).", "example": 501 }, "message-template": { "type": "object", "properties": { "id": { "type": "integer", "example": 2 }, "user_id": { "type": "integer", "example": 2 }, "sub_account_id": { "type": ["integer", "null"] }, "handwriting_style_id": { "type": "integer", "description": "ID of the handwriting style used in the message template", "example": 18 }, "font_size": { "type": "integer", "description": "Font size used in the message template. Only valid for AI fonts", "enum": ["auto", "large", "medium", "small"] }, "font_color": { "type": "string", "description": "Font color used in the message template.", "example": "#000000" }, "handwriting_realism": { "type": "boolean", "description": "Handwriting realism level used in the message template. Only valid for AI fonts" }, "name": { "type": "string", "example": "Thank You Message" }, "content": { "type": "string", "example": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" }, "additional_pages": { "type": "string", "format": "uri", "description": "URL to additional pages to include with the cover letter. Only valid for letter templates." }, "skip_creative_generation": { "type": "integer", "description": "Flag to skip creative generation. Set when message template is PDF file only.", "example": 0 }, "custom_background_url": { "type": "string", "description": "URL of the custom background image for the message template. Only valid for postcard backs and the interior background of notecards and giftcards.", "example": "https://example.com/background.png" }, "qrcode_url": { "type": "string", "description": "URL of the QR code image for the message template", "example": "https://thanks.io" }, "cc_emails": { "type": "array", "description": "List of email addresses to be CC'd on when a QR code is scanned", "items": { "type": "string", "format": "email" } }, "created_at": { "type": "string", "format": "date-time", "example": "2018-08-08T02:56:59.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-02-12T05:13:15.000000Z" }, "type": { "type": "string", "example": "notecard", "enum": [ "postcard", "postcard6x9", "postcard6x11", "letter", "windowlessletter", "notecard", "giftcard", "magnacard" ], "description": "Type of the message template" }, "giftcard_brand_code": { "type": "string", "description": "Brand code of the gift card", "example": "amazonus" }, "giftcard_brand_image": { "type": "string", "description": "Image URL of the gift card brand", "example": "https://cdn.thanks.io/giftcards/amazonus.png" }, "giftcard_amount": { "type": "integer", "description": "Amount of the gift card in cents", "example": 5000 }, "landing_page_url": { "type": "string", "format": "uri", "description": "URL of the gated landing page (also known as a gating URL). Recipients must visit this page before they can redeem the gift card, letting you gate redemption behind an action such as booking a demo or completing a form. Only valid for giftcards." }, "share_uuid": { "type": "string", "example": "5J5N-QAD3-6LLL-LSZZ" } } }, "message-template-create": { "type": "object", "properties": { "type": { "type": "string", "example": "notecard", "enum": [ "postcard", "postcard6x9", "postcard6x11", "letter", "windowlessletter", "notecard", "giftcard", "magnacard" ], "description": "Type of the message template" }, "name": { "type": "string", "description": "Name of the message template", "example": "Thank You Message" }, "handwriting_style_id": { "type": "integer", "description": "Handwriting style ID for the message template", "example": 4 }, "font_color": { "type": "string", "description": "Handwriting color to use", "example": "rgba(31,0,113,0.80)" }, "handwriting_realism": { "type": "boolean", "description": "Set to true to enable the realism effect for AI fonts.", "example": true }, "content": { "type": "string", "description": "Template body content.", "example": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" }, "sub_account_id": { "type": ["integer", "null"], "description": "ID of the sub-account to associate with this template.", "example": 7 }, "additional_pages": { "type": "string", "format": "uri", "description": "URL to additional pages to include with the cover letter. Only valid for letter templates.", "example": "https://example.com/additional-pages.pdf" }, "pdf_only_url": { "type": "string", "format": "uri", "description": "URL to PDF file to use for entire mailer. If this is specified, no cover letter is generated. Valid for letter templates only. Providing this URL automatically sets skip_creative_generation to true. For windowed letter templates, leave the upper-left address area of page 1 blank and do not include a recipient address in the PDF; thanks.io prints each recipient's address there.", "example": "https://example.com/mailer.pdf" }, "custom_background_url": { "type": "string", "format": "uri", "description": "URL of a custom background image for the template. Only valid for postcard backs and the interior background of notecards and giftcards.", "example": "https://example.com/background.png" }, "qrcode_url": { "type": "string", "format": "uri", "description": "URL of the QR code image to use for the template.", "example": "https://thanks.io" }, "cc_emails": { "type": "array", "description": "List of email addresses to CC when a QR code is scanned", "items": { "type": "string", "format": "email" } }, "giftcard_brand_code": { "type": "string", "description": "Brand code of the gift card. Required when type is giftcard.", "example": "amazonus" }, "giftcard_amount": { "type": "integer", "description": "Amount of the gift card in cents. Required when type is giftcard. Use this field for public v2 requests instead of giftcard_amount_in_cents.", "example": 5000 }, "landing_page_url": { "type": "string", "format": "uri", "description": "URL of the gated landing page (also known as a gating URL). Recipients must visit this page before they can redeem the gift card, letting you gate redemption behind an action such as booking a demo or completing a form. Only valid for giftcards.", "example": "https://example.com/landing" } }, "allOf": [ { "if": { "properties": { "type": { "const": "giftcard" } }, "required": ["type"] }, "then": { "required": ["giftcard_brand_code", "giftcard_amount"] } } ] }, "message-template-update": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated name of the message template" }, "handwriting_style_id": { "type": "integer", "description": "Handwriting style ID for the message template", "example": 4 }, "font_color": { "type": "string", "description": "Handwriting color to use", "example": "rgba(31,0,113,0.80)" }, "handwriting_realism": { "type": "boolean", "description": "Set to true to enable the realism effect for AI fonts.", "example": true }, "content": { "type": "string", "description": "Updated template body content" }, "type": { "type": "string", "example": "notecard", "enum": [ "postcard", "postcard6x9", "postcard6x11", "letter", "windowlessletter", "notecard", "giftcard", "magnacard" ], "description": "Type of the message template" }, "sub_account_id": { "type": ["integer", "null"], "description": "ID of the sub-account to associate with this template." }, "additional_pages": { "type": "string", "format": "uri", "description": "Updated additional PDF URL for the template" }, "pdf_only_url": { "type": "string", "format": "uri", "description": "URL to PDF file to use for entire mailer. If this is specified, no cover letter is generated. Valid for letter templates only. Providing this URL automatically sets skip_creative_generation to true. For windowed letter templates, leave the upper-left address area of page 1 blank and do not include a recipient address in the PDF; thanks.io prints each recipient's address there." }, "custom_background_url": { "type": "string", "format": "uri", "description": "Updated custom background image URL. Only valid for postcard backs and the interior background of notecards and giftcards." }, "qrcode_url": { "type": "string", "format": "uri", "description": "Updated QR code image URL" }, "cc_emails": { "type": "array", "items": { "type": "string", "format": "email" } }, "giftcard_brand_code": { "type": "string", "description": "Updated gift card brand code. Required when type is giftcard." }, "giftcard_amount": { "type": "integer", "description": "Updated gift card amount in cents. Required when type is giftcard." }, "landing_page_url": { "type": "string", "format": "uri", "description": "Updated gated landing page URL (also known as a gating URL). Recipients must visit this page before they can redeem the gift card, letting you gate redemption behind an action such as booking a demo or completing a form. Only valid for giftcards." } } }, "recipient": { "type": "object", "properties": { "id": { "type": "integer", "example": 18113288, "readOnly": true }, "mailing_list_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Tobias Example" }, "company": { "type": "string", "example": "thanks.io" }, "address": { "type": "string", "example": "123 Main Street" }, "address2": { "type": "string", "example": "Apartment 1" }, "city": { "type": "string", "example": "Any Town" }, "province": { "type": "string", "description": "State or Province", "example": "KS" }, "postal_code": { "type": "string", "example": "12345" }, "country": { "type": "string", "example": "US" }, "dob": { "type": "string", "description": "Date of Birth in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format.", "example": "1981-04-23" }, "anniversary": { "type": "string", "description": "Can be used for house purchase anniversaries, move-in dates, or any recurring annual milestone. Anniversary date in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format.", "example": "2025-07-21" }, "email": { "type": "string", "example": "tobias@example.com" }, "phone": { "type": "string", "example": "+1 (555) 123-4567" }, "custom1": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Unique Info" }, "custom2": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "For example a product code or customer ID" }, "custom3": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom4": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom5": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom6": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom7": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom8": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom9": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom10": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "absentee_address": { "type": ["string", "null"], "description": "The property (absentee) address the absentee image template and message variables use, or null when none is set. Mail is delivered to `address`, not here.", "example": "742 Evergreen Terrace, Springfield, IL 62704" }, "mailing-list": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/mailing-list" } ], "description": "The mailing list this recipient belongs to" }, "created_at": { "readOnly": true, "type": "string", "example": "2025-06-27T14:57:11.000000Z" }, "updated_at": { "readOnly": true, "type": "string", "example": "2025-06-27T14:57:11.000000Z" } } }, "recipient-no-mailinglist": { "type": "object", "properties": { "name": { "type": "string", "example": "Tobias Example" }, "company": { "type": "string", "example": "thanks.io" }, "address": { "type": "string", "example": "123 Main Street" }, "address2": { "type": "string", "example": "Apartment 1" }, "city": { "type": "string", "example": "Any Town" }, "province": { "type": "string", "description": "State or Province", "example": "KS" }, "postal_code": { "type": "string", "example": "12345" }, "country": { "type": "string", "example": "US" }, "dob": { "type": "string", "description": "Date of Birth in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format.", "example": "1981-04-23" }, "anniversary": { "type": "string", "description": "Can be used for house purchase anniversaries, move-in dates, or any recurring annual milestone. Anniversary date in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format.", "example": "2025-07-21" }, "email": { "type": "string", "example": "tobias@example.com" }, "phone": { "type": "string", "example": "+1 (555) 123-4567" }, "custom1": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Unique Info" }, "custom2": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "For example a product code or customer ID" }, "custom3": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom4": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom5": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom6": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom7": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom8": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom9": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom10": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "absentee_address": { "type": ["string", "null"], "description": "The property (absentee) address the absentee image template and message variables use. Present only on recipients sent with an absentee address. Mail is delivered to `address`, not here.", "example": "742 Evergreen Terrace, Springfield, IL 62704" } } }, "recipient-create": { "type": "object", "anyOf": [ { "title": "Create Recipient by Address", "description": "Create a recipient by providing address details", "required": ["mailing_list_id", "address"] }, { "title": "Create Recipient by Email", "description": "Create a recipient by providing email address", "required": ["mailing_list_id", "email"] } ], "properties": { "id": { "type": "integer", "example": 18113288, "readOnly": true }, "mailing_list_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Tobias Example" }, "company": { "type": "string", "example": "thanks.io" }, "address": { "type": "string", "example": "123 Main Street" }, "address2": { "type": "string", "example": "Apartment 1" }, "city": { "type": "string", "example": "Any Town" }, "province": { "type": "string", "description": "State or Province", "example": "KS" }, "postal_code": { "type": "string", "example": "12345" }, "country": { "type": "string", "example": "US" }, "dob": { "type": "string", "description": "Date of Birth in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format.", "example": "1981-04-23" }, "anniversary": { "type": "string", "description": "Can be used for house purchase anniversaries, move-in dates, or any recurring annual milestone. Anniversary date in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format.", "example": "2025-07-21" }, "email": { "type": "string", "example": "tobias@example.com" }, "phone": { "type": "string", "example": "+1 (555) 123-4567" }, "custom1": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Unique Info" }, "custom2": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "For example a product code or customer ID" }, "custom3": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom4": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom5": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom6": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom7": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom8": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom9": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom10": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "absentee_address": { "$ref": "#/components/schemas/absentee-address" }, "absentee_city": { "$ref": "#/components/schemas/absentee-city" }, "absentee_province": { "$ref": "#/components/schemas/absentee-province" }, "absentee_postal_code": { "$ref": "#/components/schemas/absentee-postal-code" }, "mailing-list": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/mailing-list" } ], "description": "The mailing list this recipient belongs to" }, "created_at": { "readOnly": true, "type": "string", "example": "2025-06-27T14:57:11.000000Z" }, "updated_at": { "readOnly": true, "type": "string", "example": "2025-06-27T14:57:11.000000Z" } } }, "recipient-create-no-mailinglist": { "type": "object", "anyOf": [ { "title": "Create Recipient by Address", "description": "Create a recipient by providing address details", "required": ["mailing_list_id", "address"] }, { "title": "Create Recipient by Email", "description": "Create a recipient by providing email address", "required": ["mailing_list_id", "email"] } ], "properties": { "name": { "type": "string", "example": "Tobias Example" }, "company": { "type": "string", "example": "thanks.io" }, "address": { "type": "string", "example": "123 Main Street" }, "address2": { "type": "string", "example": "Apartment 1" }, "city": { "type": "string", "example": "Any Town" }, "province": { "type": "string", "description": "State or Province", "example": "KS" }, "postal_code": { "type": "string", "example": "12345" }, "country": { "type": "string", "example": "US" }, "dob": { "type": "string", "description": "Date of Birth in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format.", "example": "1981-04-23" }, "anniversary": { "type": "string", "description": "Can be used for house purchase anniversaries, move-in dates, or any recurring annual milestone. Anniversary date in ISO 8601 format (YYYY-MM-DD) or null if not set. If provided as MM/DD/YYYY in requests, it will be converted to ISO 8601 format.", "example": "2025-07-21" }, "email": { "type": "string", "example": "tobias@example.com" }, "phone": { "type": "string", "example": "+1 (555) 123-4567" }, "custom1": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Unique Info" }, "custom2": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "For example a product code or customer ID" }, "custom3": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom4": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom5": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom6": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom7": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom8": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom9": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "custom10": { "type": "string", "description": "Custom field for additional information about the recipient", "example": "Any Extra Info" }, "absentee_address": { "$ref": "#/components/schemas/absentee-address" }, "absentee_city": { "$ref": "#/components/schemas/absentee-city" }, "absentee_province": { "$ref": "#/components/schemas/absentee-province" }, "absentee_postal_code": { "$ref": "#/components/schemas/absentee-postal-code" }, "mailing-list": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/mailing-list" } ], "description": "The mailing list this recipient belongs to" }, "created_at": { "readOnly": true, "type": "string", "example": "2025-06-27T14:57:11.000000Z" }, "updated_at": { "readOnly": true, "type": "string", "example": "2025-06-27T14:57:11.000000Z" } } }, "recipient-array": { "type": "array", "description": "Array of recipient objects", "items": { "$ref": "#/components/schemas/recipient" } }, "sub-account": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 2 }, "title": { "type": "string", "example": "My Sub Account" }, "return_name": { "type": "string", "example": "John Smith" }, "return_address": { "type": "string", "example": "123 Smith Street" }, "return_address2": { "type": "string", "example": "Apartment 2" }, "return_city": { "type": "string", "example": "Denver" }, "return_state": { "type": "string", "example": "CO" }, "return_postal_code": { "type": "string", "example": "12345" } } }, "sub-account-create": { "type": "object", "required": ["title"], "properties": { "title": { "type": "string", "example": "My Sub Account" }, "return_name": { "type": "string", "example": "John Smith" }, "return_address": { "type": "string", "example": "123 Smith Street" }, "return_address2": { "type": "string", "example": "Apartment 2" }, "return_city": { "type": "string", "example": "Denver" }, "return_state": { "type": "string", "example": "CO" }, "return_postal_code": { "type": "string", "example": "12345" } } }, "links": { "type": "object", "properties": { "first": { "type": ["string", "null"], "description": "URL of the first page of results" }, "last": { "type": ["string", "null"], "description": "URL of the last page of results" }, "prev": { "type": ["string", "null"], "description": "URL of the previous page of results" }, "next": { "type": ["string", "null"], "description": "URL of the next page of results" } } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1, "description": "Current page number" }, "from": { "type": ["integer", "null"], "example": 1, "description": "Index of the first item on the current page" }, "last_page": { "type": "integer", "example": 1, "description": "Total number of pages" }, "path": { "type": "string", "description": "Base URL for the resource" }, "per_page": { "type": "integer", "example": 25, "description": "Number of items per page" }, "to": { "type": ["integer", "null"], "example": 1, "description": "Index of the last item on the current page" }, "total": { "type": "integer", "example": 1, "description": "Total number of items" } } }, "paginated": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1, "description": "Current page number" }, "first_page_url": { "type": ["string", "null"], "description": "URL of the first page of results", "example": "https://api.thanks.io/api/v2/mailing-lists-utils/recipients/3014?page=1" }, "from": { "type": "integer", "example": 1, "description": "Index of the first item on the current page" }, "last_page": { "type": "integer", "example": 1, "description": "Total number of pages" }, "last_page_url": { "type": ["string", "null"], "description": "URL of the last page of results", "example": "https://api.thanks.io/api/v2/mailing-lists-utils/recipients/3014?page=1" }, "next_page_url": { "type": ["string", "null"], "description": "URL of the next page of results" }, "path": { "type": "string", "description": "Base URL for the resource", "example": "https://api.thanks.io/api/v2/mailing-lists-utils/recipients/3014" }, "per_page": { "type": "integer", "example": 50, "description": "Number of items per page" }, "prev_page_url": { "type": ["string", "null"], "description": "URL of the previous page of results" }, "to": { "type": "integer", "example": 12, "description": "Index of the last item on the current page" }, "total": { "type": "integer", "example": 12, "description": "Total number of items" } } }, "estimate-response": { "type": "object", "title": "Estimate Response", "properties": { "message": { "type": "string", "example": "OK" }, "data": { "type": "object", "properties": { "type": { "type": "string", "description": "Mailer type that was priced. A 6x9 postcard is reported as `postcard6x9` and a 6x11 postcard as `postcard6x11`; `postcard` means 4x6.", "enum": [ "postcard", "postcard6x9", "postcard6x11", "letter", "windowlessletter", "notecard", "magnacard", "giftcard" ], "example": "postcard" }, "size": { "type": [ "string", "null" ], "description": "Postcard size that was priced. `null` for other mailer types.", "example": "4x6" }, "total_recipients": { "type": "integer", "description": "Number of pieces the order would mail.", "example": 2 }, "recipients": { "type": "object", "description": "`total_recipients` split by destination.", "properties": { "united_states": { "type": "integer", "example": 2 }, "international": { "type": "integer", "example": 0 } } }, "pending_email_lookups": { "type": "integer", "description": "Recipients sent with an email address but no mailing address. The estimate does not run the email-to-address lookup, so they are priced as if an address is found. Any whose address can't be found when you send are not mailed or charged.", "example": 0 }, "costs_in_cents": { "type": "object", "description": "Breakdown of the total, in cents.", "properties": { "united_states": { "type": "integer", "description": "Printing and postage for US pieces.", "example": 236 }, "international": { "type": "integer", "description": "Printing and postage for international pieces.", "example": 0 }, "additional_pages": { "type": "integer", "description": "Additional letter pages, priced per page. `0` for other mailer types.", "example": 0 }, "giftcard_face_value": { "type": "integer", "description": "Combined face value of every gift card in the order. `0` for other mailer types.", "example": 0 }, "grand_total": { "type": "integer", "description": "Everything except gift card face value. This can include fees not broken out above, such as radius search records.", "example": 236 } } }, "total_cost_in_cents": { "type": "integer", "description": "The order total: `grand_total` plus `giftcard_face_value`. For every mailer type except gift cards, this is what the same request is charged when you send it. See Estimate Giftcard for how gift card face value is billed.", "example": 236 }, "total_cost": { "type": "string", "description": "`total_cost_in_cents` formatted in dollars.", "example": "$2.36" }, "current_balance_in_cents": { "type": "integer", "description": "Your account's credit balance right now.", "example": 5000 }, "covered_by_balance": { "type": "boolean", "description": "`true` if `current_balance_in_cents` covers `total_cost_in_cents`.", "example": true }, "test_mode": { "type": "boolean", "description": "`true` if API Test Mode is on for your account. The estimate always quotes your real rates, while a send in test mode is not charged.", "example": false }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Plain-language caveats about anything that could make the real charge differ, such as email-only recipients or a PDF whose pages could not be counted. Empty when there are none.", "example": [] } } } } }, "send-mailer-base": { "type": "object", "properties": { "preview": { "type": "boolean", "description": "Set to true to return a preview instead of sending the mail piece. You can use this with any send call to inspect the output before submitting the order. On the Free and Business plans, preview images carry a DRAFT watermark; the mail you send never does. Professional and Enterprise previews have no watermark.", "example": true }, "mailing_list_ids": { "type": "array", "description": "Mailing list IDs to send to. Required if `recipients` and `radius_search` are not provided.", "items": { "type": "integer" }, "example": [5166, 514] }, "recipients": { "type": "array", "description": "Recipients to send to. Required if `mailing_list_ids` and `radius_search` are not provided.", "items": { "$ref": "#/components/schemas/recipient-create-no-mailinglist" } }, "radius_search": { "type": "object", "description": "Use a radius search to find recipients near an address. Required if `mailing_list_ids` and `recipients` are not provided. Lookup fees are $0.05 per record.", "properties": { "preview": { "type": "boolean", "description": "Return a preview of the number of matching recipients and the estimated cost.", "default": false }, "address": { "type": "string", "example": "123 Main Street, Fake City, NY, 55555", "description": "Full street address to use as the center point of the nearest-neighbor search." }, "record_count": { "type": "integer", "description": "Number of nearby records to return.", "minimum": 1, "maximum": 10000, "example": 1 }, "record_types": { "type": "string", "description": "Record type to search for", "enum": [ "all", "likelytomove", "likelytorefi", "absenteeowner", "highnetworth", "majorityhomeequity", "homefreeclear", "underwater", "kidsinhousehold", "newhomeowner", "firsttimehomebuyer", "renters", "retiring", "retired", "pool", "onlybusinesses", "newbusiness" ], "default": "all" }, "include_condos": { "type": "boolean", "description": "Include condos in search.", "default": false }, "append_data": { "type": "boolean", "description": "Append phone and email to each record for an additional fee ($.20 per record).", "default": false }, "use_property_owner": { "type": "boolean", "description": "Use the property owner's address when searching commercial records.", "default": false }, "include_search_address": { "type": "boolean", "description": "Set to true to include the search address in the generated mailing list." } } }, "handwriting_style_id": { "type": "integer", "description": "ID of handwriting style to use.", "example": 4 }, "handwriting_color": { "type": "string", "description": "Handwriting color to use. Options are preset named colors or specified as hex format, such as '#4287f5'", "enum": ["blue", "black", "green", "purple", "red"], "examples": ["blue", "#4287f5"] }, "handwriting_realism": { "type": "boolean", "description": "Set to true to enable the realism effect for AI fonts.", "example": true }, "sub_account": { "type": "integer", "description": "Sub-account ID to use for this order.", "example": 7 }, "notification_emails": { "type": "string", "description": "Optional comma-separated list of email addresses to notify about order events such as QR scan notifications.", "example": "ops@example.com,sales@example.com" }, "email_lookup": { "type": "boolean", "description": "Whether a recipient given an `email` but no street address has their postal address looked up from the email. Each address found is charged as an Email to Address lookup. Defaults to `true`. Set to `false` to skip the lookup: recipients without a street address are then left out of the order, which mails only the recipients that have one. Estimates never run the lookup and price such recipients as if found.", "default": true, "example": false }, "postage_class": { "type": "string", "description": "Postage class for this order. `first_class` mails First Class. `standard` mails Standard Mail (also known as Marketing Mail): lower cost for US addresses and slower to deliver, with no tracking status and no return-to-sender. Omit it to use your account's default, set with Standard Mail Mode under Settings > Mail Preferences. Standard Mail only changes the price of US addresses. Nonprofit accounts always mail at their nonprofit rate. `standard` needs a paid plan: free plan accounts always mail First Class, and `standard` from one is rejected with a 422.", "enum": ["first_class", "standard"], "example": "standard" }, "return_name": { "type": "string", "description": "Custom return name for the order.", "example": "Custom Return" }, "return_address": { "type": "string", "description": "Custom return address for the order.", "example": "1 Main Street" }, "return_address2": { "type": "string", "description": "Custom return address line 2 for the order.", "example": "Unit 1" }, "return_city": { "type": "string", "description": "Custom return city for the order.", "example": "Woodbridge" }, "return_state": { "type": "string", "description": "Custom return state/province for the order.", "example": "NJ" }, "return_postal_code": { "type": "string", "description": "Custom return postal code for the order.", "example": "07095" }, "metadata": { "type": ["object", "null"], "description": "Your own key/value data to store with the order. It is returned unchanged by the order endpoints and included in every webhook event for the order as `order.metadata`. Must be a JSON object rather than an array, and no larger than 8,192 bytes once encoded as JSON. thanks.io does not print or otherwise act on these values.", "additionalProperties": true, "example": { "crm_deal_id": "D-1042", "campaign": "spring-winback", "source": "hubspot" } } } }, "send-mailer-order-response": { "type": "object", "title": "Send Mailer Order Submitted Response", "description": "Response when an Order is successfully submitted to Send Mailer", "properties": { "id": { "type": "integer", "description": "Unique identifier for the order", "example": 42664 }, "user_id": { "type": "integer", "description": "User ID for the order", "example": 2 }, "sub_account": { "description": "Sub-account Info For Order. Can be null", "allOf": [ { "$ref": "#/components/schemas/sub-account" } ], "type": ["object", "null"] }, "sub_account_id": { "type": ["integer", "null"], "description": "Sub account ID for the order", "example": 12345 }, "total_estimated_recipients": { "type": "integer", "description": "Total estimated recipients for the order", "example": 1 }, "authorization_total": { "type": "integer", "description": "Total authorization amount for the order in cents", "example": 58 }, "leads_fee": { "type": "integer", "description": "Total leads fee for the order in cents", "example": 99 }, "mailing_list_ids_used": { "type": "string", "description": "Mailing lists used for the order. Can be null if recipients or radius search is used.", "example": "3046,3020" }, "recipients": { "type": "array", "description": "List of recipients for the order", "items": { "$ref": "#/components/schemas/recipient-no-mailinglist" } }, "front_image": { "type": "string", "description": "Front image URL for the order", "example": "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png" }, "image_template_id": { "type": ["integer", "null"], "description": "Image template ID for the order", "example": 6 }, "custom_background_url": { "type": ["string", "null"], "description": "Custom background URL for the order. Only valid for postcard backs and the interior background of notecards and giftcards.", "example": "https://s3.amazonaws.com/content.thanks.io/templates/branding-builder-images/c09d39aadfc-3701d4467b8/4524cce0-78cb-11f0-b937-17570cbedaf4.png" }, "message": { "type": "string", "description": "Message content for the order", "example": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum." }, "message_template_id": { "type": ["integer", "null"], "description": "Message template ID for the order", "example": 12345 }, "handwriting_color": { "type": "string", "description": "Handwriting color to use", "example": "rgba(31,0,113,0.80)" }, "font_size": { "type": "string", "description": "Font size for the order", "enum": ["auto", "small", "medium", "large"], "example": "auto" }, "style": { "type": "integer", "description": "Handwriting style ID for the order", "example": 4 }, "append_or_current_resident": { "type": "boolean", "description": "Appended \"Or Current Resident\" for the order. This is helpful if you want to ensure delivery.", "example": false }, "return_name": { "type": ["string", "null"], "description": "Return name for the order", "example": "John Doe" }, "return_address": { "type": ["string", "null"], "description": "Return address line 1 for the order", "example": "123 Main Street" }, "return_address2": { "type": ["string", "null"], "description": "Return address line 2 for the order", "example": null }, "return_city": { "type": ["string", "null"], "description": "Return city for the order", "example": "Anytown" }, "return_province": { "type": ["string", "null"], "description": "Return state/province for the order", "example": "NY" }, "return_postal_code": { "type": ["string", "null"], "description": "Return postal code for the order", "example": "12345" }, "type": { "type": "string", "description": "Type of the order", "enum": [ "postcard", "postcard6x9", "postcard6x11", "letter", "notecard", "giftcard", "windowlessletter" ], "example": "postcard" }, "size": { "type": "string", "description": "Size of the order (valid for postcards only)", "enum": ["4x6", "6x9", "6x11"], "example": "4x6" }, "method": { "type": "string", "description": "Method for the order", "enum": ["api", "cardbuilder", "drip", "email", "zapier"] }, "status": { "type": "string", "description": "Status of the order", "enum": [ "reviewing", "processing", "fulfilled", "cancelled", "printed", "shipped", "paused", "delivered" ] }, "display_status": { "type": "string", "description": "Display status for the order", "example": "Reviewing" }, "display_trigger": { "type": "string", "description": "Display trigger for the order", "example": "API" }, "display_type": { "type": "string", "description": "Display type for the order", "example": "Postcard-4x6" }, "addons": { "type": ["object", "null"], "description": "Add-ons for the order", "properties": { "standardmail": { "type": "string", "description": "Standard mail add-on status", "enum": ["on", "off"], "example": "on" } } }, "qrcode_url": { "type": ["string", "null"], "description": "QR code URL for the order", "example": "https://www.google.com?name=~FULL_NAME~&custom_field_1=~CUSTOM1~&custom_field2=~CUSTOM2~" }, "giftcard_brand": { "type": ["string", "null"], "description": "Gift card brand for the order (valid for Giftcard orders only)", "example": null }, "giftcard_image": { "type": ["string", "null"], "description": "Gift card image URL for the order (valid for Giftcard orders only)", "example": null }, "giftcard_amount": { "type": ["integer", "null"], "description": "Gift card amount for the order in cents (valid for Giftcard orders only)", "example": null }, "giftcard_brand_longname": { "type": "string", "description": "Gift card brand long name for the order (valid for Giftcard orders only)", "example": "Amazon.com" }, "metadata": { "type": ["object", "null"], "description": "The metadata object submitted with the order, returned exactly as it was sent. Null when the order was created without metadata.", "additionalProperties": true, "example": { "crm_deal_id": "D-1042", "campaign": "spring-winback", "source": "hubspot" } }, "updated_at": { "type": "string", "format": "date-time", "description": "Last updated timestamp for the order", "example": "2025-08-14 16:42:44" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp for the order", "example": "2025-08-14 16:42:44" } } }, "send-mailer-preview-response": { "type": "object", "title": "Send Mailer Preview Response", "description": "Preview image URLs returned when `preview` is set to `true`.", "properties": { "message": { "type": "string", "example": "OK", "description": "Response message" }, "data": { "type": "object", "description": "Preview data containing image URLs", "properties": { "previews": { "type": "array", "description": "Array of preview image URLs", "items": { "type": "string", "format": "uri", "example": "https://s3.amazonaws.com/cdn.thanks.io/preview/12345.png" } } } } } } }, "responses": { "Unauthorized": { "description": "Access token is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Unauthorized" } } } } } }, "UserError": { "description": "User error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Sub Account ID does not exist" } } } } } }, "UnknownError": { "description": "An unknown error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Error Submitting Mailer" } } } } } }, "MailingListDoesNotExist": { "description": "The specified mailing list does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Mailing List Does Not Exist" } } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Not Found" } } } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token authentication using your thanks.io API key" } } }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Recipients" }, { "name": "Mailing Lists" }, { "name": "Send Mailer" }, { "name": "Order Estimates" }, { "name": "Orders" }, { "name": "Message Templates" }, { "name": "Image Templates" }, { "name": "Creatives Library", "description": "Your Creatives library: saved pairings of an image template and a message template. Sending one by `creative_id` is the recommended way to send. Creatives are designed in your dashboard; these endpoints list and read them so your integration can find the right `creative_id`." }, { "name": "Handwriting Styles" }, { "name": "Giftcards" }, { "name": "Dynamic Images", "description": "" }, { "name": "Image Builder" }, { "name": "Sub Accounts" }, { "name": "Webhooks" }, { "name": "Webhook Events" } ], "webhooks": { "orderItemStatusUpdate": { "post": { "tags": ["Webhook Events"], "summary": "Order Item Status Change Webhook", "description": "Sent when an order item changes status. The payload includes the recipient, order, and order item context for the affected mail piece.", "operationId": "orderItemStatusUpdateWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "example": "order_item.status_update" }, "event_id": { "type": "string", "example": "7199e4e0-516b-11f0-ba5f-f135ea42fb62" }, "data": { "$ref": "#/components/schemas/webhook-order-item-status-update-payload" }, "timestamp": { "type": "integer", "example": 1750818235 }, "date_time": { "type": "string", "example": "2025-06-25 02:23:55" } }, "required": ["event_type", "event_id", "data", "timestamp", "date_time"] }, "example": { "event_type": "order_item.status_update", "event_id": "7199e4e0-516b-11f0-ba5f-f135ea42fb62", "data": { "order_item.id": 2668662, "order_item.scans": null, "order_item.failure": null, "recipient.name": "John Doe", "recipient.company": null, "recipient.address": "123 Fake St", "recipient.address2": null, "recipient.absentee_address": null, "recipient.city": "Any Town", "recipient.province": "NY", "recipient.postal_code": "12345", "recipient.country": "US", "recipient.email": null, "recipient.phone": null, "recipient.custom_1": "Example Custom 1", "recipient.custom_2": "Example Custom 2", "recipient.custom_3": "Example Custom 3", "recipient.custom_4": "Example Custom 4", "recipient.custom_5": "Example Custom 5", "recipient.custom_6": "Example Custom 6", "recipient.custom_7": "Example Custom 7", "recipient.custom_8": "Example Custom 8", "recipient.custom_9": "Example Custom 9", "recipient.custom_10": "Example Custom 10", "order.id": 42399, "order.sub_account_id": 5, "order.status": "Printing", "order.metadata": { "crm_deal_id": "D-1042" }, "order_item.delivery_date": "2025-07-05", "order_item.previous_status": null, "order_item.current_status": "Processing" }, "timestamp": 1750818235, "date_time": "2025-06-25 02:23:55" } } } }, "responses": { "200": { "description": "Webhook received" } } } }, "orderStatusUpdate": { "post": { "tags": ["Webhook Events"], "summary": "Order Status Change Webhook", "description": "Sent when an order changes status. The payload includes the affected order identifier and its updated status.", "operationId": "orderStatusUpdateWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "example": "order.status_update" }, "event_id": { "type": "string", "example": "a8a59df0-516d-11f0-9ca2-31daad0e4f7f" }, "data": { "$ref": "#/components/schemas/webhook-order-status-update-payload" }, "timestamp": { "type": "integer", "example": 1750819187 }, "date_time": { "type": "string", "example": "2025-06-25 02:39:47" } }, "required": ["event_type", "event_id", "data", "timestamp", "date_time"] }, "example": { "event_type": "order.status_update", "event_id": "a8a59df0-516d-11f0-9ca2-31daad0e4f7f", "data": { "order.id": 42401, "order.status": "Printing", "order.previous_status": "reviewing", "order.current_status": "processing", "order.metadata": { "crm_deal_id": "D-1042" } }, "timestamp": 1750819187, "date_time": "2025-06-25 02:39:47" } } } }, "responses": { "200": { "description": "Webhook received" } } } }, "orderItemDelivered": { "post": { "tags": ["Webhook Events"], "summary": "Order Item Delivered Webhook", "description": "Sent when a mail piece is delivered. The payload includes the recipient, order, and order item state at delivery.", "operationId": "orderItemDeliveredWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "example": "order_item.delivered" }, "event_id": { "type": "string", "example": "7199e4e0-516b-11f0-ba5f-f135ea42fb62" }, "data": { "$ref": "#/components/schemas/webhook-order-item-delivered-payload" }, "timestamp": { "type": "integer", "example": 1750818235 }, "date_time": { "type": "string", "example": "2025-06-25 02:23:55" } }, "required": ["event_type", "event_id", "data", "timestamp", "date_time"] }, "example": { "event_type": "order_item.delivered", "event_id": "7199e4e0-516b-11f0-ba5f-f135ea42fb62", "data": { "order_item.id": 2668662, "order_item.scans": null, "order_item.failure": null, "recipient.name": "John Doe", "recipient.company": null, "recipient.address": "123 Fake St", "recipient.address2": null, "recipient.absentee_address": null, "recipient.city": "Any Town", "recipient.province": "NY", "recipient.postal_code": "12345", "recipient.country": "US", "recipient.email": null, "recipient.phone": null, "recipient.custom_1": "Example Custom 1", "recipient.custom_2": "Example Custom 2", "recipient.custom_3": "Example Custom 3", "recipient.custom_4": "Example Custom 4", "recipient.custom_5": "Example Custom 5", "recipient.custom_6": "Example Custom 6", "recipient.custom_7": "Example Custom 7", "recipient.custom_8": "Example Custom 8", "recipient.custom_9": "Example Custom 9", "recipient.custom_10": "Example Custom 10", "order.id": 42399, "order.sub_account_id": 5, "order.status": "Printing", "order.metadata": { "crm_deal_id": "D-1042" }, "order_item.delivery_date": "2025-07-05", "order_item.previous_status": "Shipped", "order_item.current_status": "Delivered" }, "timestamp": 1750818235, "date_time": "2025-06-25 02:23:55" } } } }, "responses": { "200": { "description": "Webhook received" } } } }, "qrCodeScanUpdate": { "post": { "tags": ["Webhook Events"], "summary": "QR Code Scan Webhook", "description": "Sent when a recipient scans a thanks.io QR code on a mailer. The payload includes the scan context plus the QR code destination URL.", "operationId": "qrCodeScanUpdateWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "example": "scans.scan_update" }, "event_id": { "type": "string", "example": "c4e1aa40-516a-11f0-94e9-4b4494619f64" }, "data": { "$ref": "#/components/schemas/webhook-scan-update-payload" }, "timestamp": { "type": "integer", "example": 1750817946 }, "date_time": { "type": "string", "example": "2025-06-25 02:19:06" } }, "required": ["event_type", "event_id", "data", "timestamp", "date_time"] }, "example": { "event_type": "scans.scan_update", "event_id": "c4e1aa40-516a-11f0-94e9-4b4494619f64", "data": { "order_item.id": 2668661, "order_item.scans": 4, "order_item.failure": null, "recipient.name": "John Doe", "recipient.company": null, "recipient.address": "123 Fake St", "recipient.address2": null, "recipient.absentee_address": null, "recipient.city": "Any Town", "recipient.province": "NY", "recipient.postal_code": "12345", "recipient.country": "US", "recipient.email": null, "recipient.phone": null, "recipient.custom_1": "Example Custom 1", "recipient.custom_2": "Example Custom 2", "recipient.custom_3": "Example Custom 3", "recipient.custom_4": "Example Custom 4", "recipient.custom_5": "Example Custom 5", "recipient.custom_6": "Example Custom 6", "recipient.custom_7": "Example Custom 7", "recipient.custom_8": "Example Custom 8", "recipient.custom_9": "Example Custom 9", "recipient.custom_10": "Example Custom 10", "order.id": 42398, "order.sub_account_id": 5, "order.status": "Fulfilled", "order.metadata": { "crm_deal_id": "D-1042" }, "order_item.delivery_date": "2025-06-05", "order_item.current_status": "Processing", "qrcode.url": "https://www.google.com" }, "timestamp": 1750817946, "date_time": "2025-06-25 02:19:06" } } } }, "responses": { "200": { "description": "Webhook received" } } } }, "scanBoardStatusUpdate": { "post": { "tags": [ "Webhook Events" ], "summary": "Scan Board Stage Change Webhook", "description": "Sent when a card on your QR Scan Board enters the stage set in the webhook's scan_board_status, including when a newly scanned mailer lands in New. Each webhook fires at most once per card per stage. Available on the Business plan and up.", "operationId": "scanBoardStatusUpdateWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "example": "scan_board.status_update" }, "event_id": { "type": "string", "example": "c4e1aa40-516a-11f0-94e9-4b4494619f64" }, "data": { "$ref": "#/components/schemas/webhook-scan-board-status-update-payload" }, "timestamp": { "type": "integer", "example": 1750817946 }, "date_time": { "type": "string", "example": "2025-06-25 02:19:06" } }, "required": [ "event_type", "event_id", "data", "timestamp", "date_time" ] }, "example": { "event_type": "scan_board.status_update", "event_id": "c4e1aa40-516a-11f0-94e9-4b4494619f64", "data": { "order_item.id": 2668661, "order_item.scans": 4, "order_item.failure": null, "recipient.name": "John Doe", "recipient.company": null, "recipient.address": "123 Fake St", "recipient.address2": null, "recipient.city": "Any Town", "recipient.province": "NY", "recipient.postal_code": "12345", "recipient.country": "US", "recipient.email": null, "recipient.phone": null, "recipient.custom_1": "Example Custom 1", "recipient.custom_2": "Example Custom 2", "recipient.absentee_address": null, "recipient.custom_3": "Example Custom 3", "recipient.custom_4": "Example Custom 4", "recipient.custom_5": "Example Custom 5", "recipient.custom_6": "Example Custom 6", "recipient.custom_7": "Example Custom 7", "recipient.custom_8": "Example Custom 8", "recipient.custom_9": "Example Custom 9", "recipient.custom_10": "Example Custom 10", "order.id": 42398, "order.status": "Fulfilled", "order.sub_account_id": null, "order.metadata": { "crm_deal_id": "D-1042" }, "order_item.delivery_date": "2025-06-05", "scan_board.card_id": 1187, "scan_board.previous_status": "new", "scan_board.current_status": "contacted", "scan_board.last_scanned_at": "2025-06-24 23:19:06" }, "timestamp": 1750817946, "date_time": "2025-06-25 02:19:06" } } } }, "responses": { "200": { "description": "Webhook received" } } } } }, "paths": { "/recipients/{recipientId}": { "parameters": [ { "name": "recipientId", "in": "path", "description": "Recipient ID", "required": true, "schema": { "type": "integer", "example": 296446 } } ], "get": { "tags": ["Recipients"], "operationId": "getRecipientsDetails", "summary": "Get Recipient", "description": "Get a recipient by ID.", "responses": { "200": { "description": "Successful Response", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/recipient" }, "examples": { "recipient": { "$ref": "#/components/examples/recipient-example" } } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": ["Recipients"], "summary": "Update Recipient", "operationId": "updateRecipientDetails", "description": "Update details of a specific recipient by ID. Leave out `absentee_address` to keep the current absentee address. Sending it replaces the stored absentee address as a whole, so send it together with any of `absentee_city`, `absentee_province` and `absentee_postal_code`: those on their own, for example only a new ZIP, are refused with a 400 and nothing is updated. Send `absentee_address` as an empty string or null to remove the absentee address; if the same request also sets `custom1` to `absentee` with an address in `custom2`, that address is copied in instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/recipient" }, { "type": "object", "properties": { "absentee_city": { "$ref": "#/components/schemas/absentee-city" }, "absentee_province": { "$ref": "#/components/schemas/absentee-province" }, "absentee_postal_code": { "$ref": "#/components/schemas/absentee-postal-code" } } } ] } } } }, "responses": { "200": { "description": "Successful Response", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/recipient" }, "examples": { "recipient": { "$ref": "#/components/examples/recipient-example" } } } } }, "400": { "description": "The mailing list does not exist, or the absentee fields are invalid, such as `absentee_postal_code` sent without `absentee_address`", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "Mailing list does not exist": { "value": { "message": "Mailing List Does Not Exist" } }, "Absentee fields without absentee_address": { "value": { "message": "absentee_city, absentee_province and absentee_postal_code need absentee_address as well." } } } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": ["Recipients"], "operationId": "deleteRecipient", "summary": "Delete Recipient", "responses": { "200": { "description": "Successful Response", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "success" } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/recipients": { "post": { "tags": ["Recipients"], "operationId": "createRecipient", "summary": "Create Recipient", "description": "Add a recipient. If you do not provide a valid mailing address but do provide a valid email address, thanks.io can attempt to look up a street address for an additional fee.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/recipient-create" }, "examples": { "Adding By Address": { "value": { "mailing_list_id": 1, "name": "Tobias Example", "company": "thanks.io", "address": "12345 Main Street", "address2": "Apartment 1", "city": "Any Town", "province": "NY", "postal_code": "12345", "country": "US", "dob": "1981-04-23", "anniversary": "2025-07-21", "email": "tobias@example.com", "phone": "845-988-6485", "custom1": "Unique Info", "custom2": "For example a product code or customer ID", "custom3": "", "custom4": "" } }, "Adding By Email": { "value": { "mailing_list_id": 1, "email": "tobias@example.com" } } } } } }, "responses": { "200": { "description": "Successful Response", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/recipient" }, "examples": { "recipient": { "$ref": "#/components/examples/recipient-example" } } } } }, "400": { "$ref": "#/components/responses/MailingListDoesNotExist" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/recipients-utils/create-multiple": { "post": { "tags": ["Recipients"], "operationId": "createMultipleRecipients", "summary": "Create Multiple Recipients", "description": "Add multiple recipients at once using a JSON array of recipient objects. If a recipient does not include a valid mailing address but does include a valid email address, thanks.io can attempt to look up a street address for an additional fee.", "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/recipient-create" }, "example": [ { "mailing_list": 1, "name": "Tobias First", "address": "987 Main Street", "address2": null, "city": "LENEXA", "province": "KS", "postal_code": "66216", "country": "US", "dob": "04/23/1981", "anniversary": "04/23/2025", "custom1": null, "custom2": null, "email": "testemail@thanks.io", "phone": "1234567890" }, { "mailing_list": 1, "email": "another-testemail@thanks.io", "phone": "1234567890" } ] } } } }, "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/recipient-array" }, "example": [ { "province": "KS", "city": "Lenexa", "name": "Tobias First", "company": null, "dob": "04/23/1981", "anniversary": "04/23/2025", "country": "US", "address": "987 Main Street", "address2": "", "email": "testemail@thanks.io", "phone": "1234567890", "custom1": null, "custom2": null, "postal_code": "66216" }, { "province": "KS", "city": "Lenexa", "name": "Tobias Second", "company": null, "dob": "04/23/1981", "anniversary": "04/23/2025", "country": "US", "address": "654 Main Street", "address2": "", "email": "testemail@thanks.io", "phone": "1234567890", "custom1": null, "custom2": null, "postal_code": "66216", "error": "This address is already on this mailing list." } ] } } } } } }, "/recipients-utils/delete-by-address": { "post": { "tags": ["Recipients"], "summary": "Delete Recipient By Address", "description": "Delete a recipient by using their address or their email address.", "operationId": "deleteRecipientByAddress", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "title": "Delete Recipient by Address", "description": "Delete a recipient by providing address details", "required": ["mailing_list_id", "address", "postal_code"] }, { "title": "Delete Recipient by Email", "description": "Delete a recipient by providing email address", "required": ["mailing_list_id", "email"] } ], "properties": { "mailing_list_id": { "type": "integer", "example": 1 }, "address": { "type": "string", "example": "123 Main Street" }, "address2": { "type": "string", "example": "Apartment 1" }, "city": { "type": "string", "example": "Any Town" }, "province": { "type": "string", "description": "State or Province", "example": "KS" }, "postal_code": { "type": "string", "example": "12345" }, "country": { "type": "string", "example": "US" }, "email": { "type": "string", "example": "tobias@example.com" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "Recipient 297230 Deleted" } } } }, "400": { "$ref": "#/components/responses/MailingListDoesNotExist" } } } }, "/mailing-lists/": { "get": { "tags": ["Mailing Lists"], "operationId": "getMailingLists", "summary": "List All", "description": "List all available mailing lists. Returns a paginated list of mailing lists.", "parameters": [ { "$ref": "#/components/parameters/items_per_page" } ], "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/mailing-list" } }, "links": { "$ref": "#/components/schemas/links" }, "meta": { "$ref": "#/components/schemas/meta" } } }, "example": { "data": [ { "id": 3019, "user_id": 2, "sub_account_id": null, "type": "manual", "description": "Test Mailing List", "qrcode_url": null, "total_recipients": 0, "processed": true, "is_suppression_list": false, "total_scans": 0, "unique_scans": 0, "last_scan": null, "total_sends": 0, "last_send": null, "api_key": "TEST-KEY1", "created_at": "2025-08-06T01:06:52.000000Z", "created_at_diff": "13 hours ago", "updated_at": "2025-08-06T01:06:52.000000Z" }, { "id": 3017, "user_id": 2, "sub_account_id": null, "type": "csv", "description": "Mailing List (Csv) Created 07/16/2025", "qrcode_url": null, "total_recipients": 0, "processed": false, "is_suppression_list": false, "total_scans": 0, "unique_scans": 0, "last_scan": null, "total_sends": 0, "last_send": null, "api_key": "TEST-KEY2", "created_at": "2025-07-16T19:00:31.000000Z", "created_at_diff": "2 weeks ago", "updated_at": "2025-07-16T19:00:31.000000Z" } ], "links": { "first": "https://api.thanks.io/api/v2/mailing-lists?page=1", "last": "https://api.thanks.io/api/v2/mailing-lists?page=377", "prev": null, "next": "https://api.thanks.io/api/v2/mailing-lists?page=2" }, "meta": { "current_page": 1, "from": 1, "last_page": 377, "path": "https://api.thanks.io/api/v2/mailing-lists", "per_page": "2", "to": 2, "total": 754 } } } } }, "403": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Mailing Lists"], "operationId": "createMailingList", "summary": "Create Mailing List", "description": "If qrcode_url is provided, it will be used as the default QR Code URL when placing orders with this mailing list.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "example": "Birthday List" }, "sub_account_id": { "type": "integer", "description": "ID of the sub-account to associate with this mailing list. If not provided, the mailing list will be associated with the main account.", "example": 7 }, "qrcode_url": { "type": "string", "description": "QR Code URL for the mailing list.", "example": "https://www.google.com" } }, "required": ["description"] } } } }, "responses": { "201": { "description": "Created", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "manual", "enum": [ "csv", "manual", "map", "friends", "retarget", "zapier", "radius", "highlevel", "qrscans" ] }, "description": { "type": "string", "example": "New Mailing List (Created via API 09/07/2024)" }, "sub_account_id": { "type": ["integer", "null"], "example": 7 }, "user_id": { "type": "integer", "example": 2 }, "updated_at": { "type": "string", "example": "2024-09-07 02:10:32" }, "created_at": { "type": "string", "example": "1 second ago" }, "id": { "type": "integer", "example": 610 } } }, "example": { "type": "manual", "description": "New Mailing List (Created via API 09/07/2024)", "sub_account_id": 7, "user_id": 2, "updated_at": "2024-09-07 02:10:32", "created_at": "1 second ago", "id": 610 } } } }, "403": { "$ref": "#/components/responses/Unauthorized" } } } }, "/mailing-lists/{mailingListId}": { "parameters": [ { "name": "mailingListId", "in": "path", "description": "ID of mailing list", "required": true, "schema": { "type": "integer", "example": 56 } } ], "get": { "tags": ["Mailing Lists"], "operationId": "getMailingListDetails", "summary": "Get Details", "description": "Gets a mailing list by ID. Returns a single mailing list object.", "responses": { "200": { "description": "Successful Response", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mailing-list" }, "examples": { "mailing-list": { "$ref": "#/components/examples/mailing-list-example" } } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": ["Mailing Lists"], "operationId": "deleteMailingList", "summary": "Delete Mailing List", "responses": { "200": { "description": "Successful Response", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "success" } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/mailing-lists-utils/recipients/{mailingListId}": { "get": { "tags": ["Mailing Lists"], "summary": "List Recipients", "description": "Retrieve recipients for a specific mailing list.", "parameters": [ { "name": "limit", "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer", "example": 1000, "maximum": 10000, "minimum": 1 } }, { "name": "updated_since", "in": "query", "description": "Return only recipients updated since this date/time. Format: YYYY-MM-DD HH:MM:SS", "schema": { "type": "string", "example": "2020-04-06 01:55:50" } }, { "name": "mailingListId", "in": "path", "description": "ID of mailing list", "required": true, "schema": { "type": "integer", "example": 56 } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/recipient" }, "description": "Array of recipient objects" } } }, { "$ref": "#/components/schemas/paginated" } ] }, "example": { "current_page": 1, "data": [ { "id": 293345, "mailing_list_id": 514, "session_id": null, "name": "John Doe", "address": "123 Main Street", "address2": null, "city": "Austin", "province": "TX", "postal_code": "78703", "country": "US", "dob": null, "anniversary": null, "custom1": null, "custom2": null, "deliverability": null, "can_deliver": true, "created_at": "2020-03-10 13:33:04", "updated_at": "2020-04-06 01:57:50" } ], "first_page_url": "http://api.thanks.io/api/v2/mailing-lists/514/recipients?page=1", "from": 1, "last_page": 1, "last_page_url": "http://api.thanks.io/api/v2/mailing-lists/514/recipients?page=1", "next_page_url": null, "path": "http://api.thanks.io/api/v2/mailing-lists/514/recipients", "per_page": "1000", "prev_page_url": null, "to": 1, "total": 1 } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/mailing-lists-utils/buy-radius-search": { "post": { "tags": ["Mailing Lists"], "summary": "Radius Search", "description": "This call will purchase a radius search mailing listing and add it to your account. Each record added to the mailing list costs $.05. You can specify the number of records to return (up to 2,500) and the address/postal code to center the search around. You can also specify a mailing_list_id to add the results to an existing mailing list, or leave it blank to create a new mailing list. While API/Zapier Test Mode is enabled on the account, this endpoint is limited to 5 records per purchase \u2014 test mode cancels orders, but buying a radius search is not an order and is charged in full, so the limit is what keeps an integration under development from buying a full list by accident.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["address", "postal_code", "record_count"], "properties": { "mailing_list_id": { "type": "integer", "example": 1, "description": "ID of the mailing list to add the radius search results to. If not provided, a new mailing list will be created." }, "address": { "type": "string", "example": "123 Main Street", "description": "Street address to use for center of nearest neighbor search." }, "postal_code": { "type": "string", "example": "55555", "description": "Postal code to use for center of nearest neighbor search." }, "record_count": { "type": "integer", "description": "Number of nearest neighbors to search for. While API/Zapier Test Mode is enabled on the account, a purchase through this endpoint is limited to 5 records; a larger value is refused with a 422 and nothing is bought or charged. Buying from the dashboard is not affected and keeps the full 2,500.", "minimum": 1, "maximum": 2500, "example": 1 }, "record_types": { "type": "string", "description": "Which type of records to search for", "enum": [ "all", "likelytomove", "apartmentcomplex", "likelytodownsize", "likelytorefi", "absenteeowner", "highnetworth", "majorityhomeequity", "homefreeclear", "underwater", "kidsinhousehold", "newhomeowner", "firsttimehomebuyer", "renters", "retiring", "retired", "pool", "onlybusinesses", "newbusiness" ], "default": "all" }, "include_condos": { "type": "boolean", "description": "Include condos in search.", "default": true }, "append_data": { "type": "boolean", "description": "Append phone and email to each record for an additional fee ($.20 per record).", "default": false }, "use_property_owner": { "type": "boolean", "description": "Use Property Owners Address when searching for a commercial record_type.", "default": false }, "include_search_address": { "type": "boolean", "description": "Specifies whether to include the search address in the mailing list created." } } }, "examples": { "Create New List w/ Phone+Email Append": { "value": { "address": "123 Main Street", "postal_code": "55555", "record_types": "all", "record_count": 10, "include_condos": false, "append_data": true } }, "Append To Existing List w/ Condos": { "value": { "address": "123 Main Street", "postal_code": "55555", "record_types": "all", "record_count": 10, "include_condos": true, "append_data": false, "mailing_list_id": 3020 } } } } } }, "responses": { "200": { "description": "Successful Response", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "success" }, "mailing_list_id": { "type": "integer", "example": 1196 }, "failure": { "type": "boolean", "example": false } } }, "example": { "message": "success", "mailing_list_id": 1196, "failure": false } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "No neighbors could be found with search parameters." }, "failure": { "type": "boolean", "example": true } } } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Duplicate radius search purchase. An identical purchase was already made from this account within the last 24 hours and was refused so the records are not bought twice. The response carries the identifiers the original purchase produced, so use those instead of retrying. Change any search parameter, or wait for the window to pass, to buy again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An identical radius search purchase was already made from this account within the last 24 hours. Change the search parameters, or wait 24 hours, to buy these leads again." }, "code": { "type": "string", "example": "duplicate_radius_search" }, "mailing_list_id": { "type": "integer", "nullable": true, "description": "The mailing list the original purchase created, when it produced one.", "example": 1196 }, "order_id": { "type": "integer", "nullable": true, "description": "The order the original purchase was bought for, when the search was bought as part of a send.", "example": null }, "failure": { "type": "boolean", "example": true } } } } } }, "422": { "description": "Record count above the API/Zapier Test Mode limit. While test mode is enabled on the account, a purchase through this endpoint is limited to 5 records. The request is refused during validation, so no leads are bought, the account is not charged, and the 24 hour duplicate purchase window is not used up. Send a record_count of 5 or fewer, or turn off API/Zapier Test Mode in API Settings to buy a full list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "properties": { "record_count": { "type": "array", "items": { "type": "string" }, "example": ["Test mode is enabled on this account, so a radius search bought via API or Zapier is limited to 5 records per purchase. Nothing was purchased and the account was not charged. Send record_count of 5 or fewer, or turn test mode off in the dashboard under API Settings to buy a full list."] } } }, "failure": { "type": "boolean", "example": true } } } } } } } } }, "/mailing-lists-utils/count-radius-search": { "post": { "tags": ["Mailing Lists"], "summary": "Radius Search Count", "description": "This call reports how many records a radius search would find, without buying them. Nothing is charged, no mailing list is created, and the call can be repeated freely, so use it to preview a search before purchasing it with the Radius Search endpoint. It accepts the same search parameters with the same defaults, so sending the same payload to both counts exactly what would be bought. Because counting is free, record_count may go up to 10,000 and the API/Zapier Test Mode purchase limit does not apply.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["address", "postal_code", "record_count"], "properties": { "address": { "type": "string", "example": "123 Main Street", "description": "Street address to use for center of nearest neighbor search." }, "postal_code": { "type": "string", "example": "55555", "description": "Postal code to use for center of nearest neighbor search." }, "record_count": { "type": "integer", "description": "Maximum number of nearest neighbors to count. The response reports how many records the search actually finds, up to this number.", "minimum": 1, "maximum": 10000, "example": 100 }, "record_types": { "type": "string", "description": "Which type of records to search for", "enum": [ "all", "likelytomove", "apartmentcomplex", "likelytodownsize", "likelytorefi", "absenteeowner", "highnetworth", "majorityhomeequity", "homefreeclear", "underwater", "kidsinhousehold", "newhomeowner", "firsttimehomebuyer", "renters", "retiring", "retired", "pool", "onlybusinesses", "newbusiness" ], "default": "all" }, "include_condos": { "type": "boolean", "description": "Include condos in search.", "default": true } } }, "examples": { "Count Before Buying": { "value": { "address": "123 Main Street", "postal_code": "55555", "record_types": "all", "record_count": 100, "include_condos": true } } } } } }, "responses": { "200": { "description": "Successful Response", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "count": { "type": "integer", "description": "Number of records the search found, up to record_count.", "example": 42 }, "failure": { "type": "boolean", "example": false } } }, "example": { "status": "success", "count": 42, "failure": false } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation error. The request was refused before the search ran, so no count was performed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "properties": { "record_count": { "type": "array", "items": { "type": "string" }, "example": ["The record count field must not be greater than 10000."] } } }, "failure": { "type": "boolean", "example": true } } } } } } } } }, "/send/postcard": { "post": { "tags": ["Send Mailer"], "summary": "Send Postcard", "description": "Send a 4x6, 6x9, or 6x11 postcard.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/send-mailer-base" }, { "type": "object", "properties": { "creative_id": { "$ref": "#/components/schemas/creative-id" }, "image_template_id": { "type": "integer", "description": "ID of image template to use for front of postcard. Use a template of the matching type: `postcard` for 4x6, `postcard6x9` for 6x9, `postcard6x11` for 6x11. A 6x9 send also accepts a `postcard` template. Required if front_image_url is not specified.", "example": 6 }, "front_image_url": { "type": "string", "description": "URL to image to use for front of postcard. Must be 1875px by 1275px for 4x6 postcards, 2738px by 1838px for 6x9 postcards, or 3337px by 1777px for 6x11 postcards. Required if image_template_id is not specified.", "example": "https://cdn.thanks.io/letter-backgrounds/bg0.png" }, "message": { "type": "string", "description": "Handwritten message content used for content on back of postcard.", "example": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" }, "message_template_id": { "type": "integer", "description": "ID of message template to use for content on back of postcard. Use a template of the matching type: `postcard` for 4x6, `postcard6x9` for 6x9, `postcard6x11` for 6x11. A 6x9 send also accepts a `postcard` template.", "example": 12 }, "use_custom_background": { "type": "boolean", "description": "Use custom background image. This can be used to turn off the default background image.", "default": false }, "custom_background_image": { "type": "string", "description": "URL to custom background image to use for back of postcard. This image will be placed behind the handwritten message. Must be 1875px by 1275px for 4x6 postcards, 2738px by 1838px for 6x9 postcards, or 3337px by 1777px for 6x11 postcards.", "example": "https://cdn.thanks.io/letter-backgrounds/bg0.png" }, "qrcode_url": { "type": "string", "description": "URL to Autogenerate QR Code on back of postcard. If not specified, account default QR code URL will be used.", "example": "https://www.google.com" }, "size": { "type": "string", "description": "Size of the postcard. A 6x9 postcard is placed as a `postcard6x9` order and a 6x11 postcard as a `postcard6x11` order.", "default": "4x6", "enum": ["4x6", "6x9", "6x11"] } } } ] }, "examples": { "4x6 w/ Image URL/Recipients": { "summary": "4x6 Postcard with Custom Image and Recipients", "description": "Example of sending a 4x6 postcard using a custom front image URL, handwritten message, and an array of recipients with custom fields.", "value": { "size": "4x6", "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } }, "6x9 w/ Templates/QR Code/Custom Return ": { "summary": "6x9 Postcard with Templates and QR Code", "description": "Example of sending a 6x9 postcard using predefined image and message templates, targeting specific mailing lists, including a QR code for recipient engagement, and attaching your own metadata so it comes back on the order and its webhook events.", "value": { "size": "6x9", "return_name": "Your Company Name", "return_address": "123 Return St", "return_city": "Return City", "return_state": "RC", "return_postal_code": "12345", "image_template_id": 6, "message_template_id": 12, "qrcode_url": "https://www.google.com", "mailing_list_ids": [5166, 514], "metadata": { "crm_deal_id": "D-1042", "campaign": "spring-winback", "source": "hubspot" } } }, "6x9 w/ Custom Background/Standard": { "summary": "6x9 Postcard with Custom Background and Standard Mail", "description": "Example of sending a 6x9 postcard with a custom background image, specific handwriting style, and using standard mail delivery (lower cost option).", "value": { "size": "6x9", "image_template_id": 8, "use_custom_background": true, "custom_background_image": "https://s3.amazonaws.com/content.thanks.io/templates/branding-builder-images/c09d39aadfc-3701d4467b8/449d24b0-78cb-11f0-a351-bfecbf71caa6.png", "handwriting_style_id": 3, "postage_class": "standard", "mailing_list_ids": [5166, 514] } }, "6x11 w/ Radius Search": { "summary": "6x11 Postcard with Radius Search Targeting", "description": "Example of sending a large 6x11 postcard using radius search to automatically find and target recipients within a specific geographic area, with custom message and image URL.", "value": { "size": "6x11", "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "radius_search": { "address": "123 Main Street, Fake City, NY, 55555", "record_types": "likelytomove", "record_count": 10, "include_condos": false, "append_data": true } } }, "4x6 Preview": { "summary": "Preview 4x6 Postcard Before Sending", "description": "Example of generating a preview of a 4x6 postcard before actually sending it. Use the preview parameter to see how your postcard will look without placing an actual order.", "value": { "size": "4x6", "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "preview": true, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } } } } } }, "responses": { "200": { "description": "Send Mailer Success", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/send-mailer-order-response" }, { "$ref": "#/components/schemas/send-mailer-preview-response" } ] }, "examples": { "Order Submitted Response": { "summary": "Order Submitted Response Example", "value": { "total_estimated_recipients": 2, "authorization_total": 116, "leads_fee": 0, "mailing_list_ids_used": "3046,3020", "handwriting_color": "rgba(31,0,113,0.80)", "front_image": "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png", "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.", "append_or_current_resident": true, "type": "postcard", "return_name": null, "return_address": null, "return_address2": null, "return_city": null, "return_province": null, "return_postal_code": null, "message_template_id": null, "image_template_id": 6, "method": "api", "sub_account_id": null, "font_size": "auto", "qrcode_url": "https://www.google.com?name=~FULL_NAME~&custom_field_1=~CUSTOM1~&custom_field2=~CUSTOM2~", "size": "4x6", "custom_background_url": "https://s3.amazonaws.com/content.thanks.io/templates/branding-builder-images/c09d39aadfc-3701d4467b8/4524cce0-78cb-11f0-b937-17570cbedaf4.png", "giftcard_brand": null, "giftcard_image": null, "giftcard_amount": null, "status": "reviewing", "addons": { "standardmail": "on" }, "style": 4, "user_id": 2, "updated_at": "2025-08-14 16:48:13", "created_at": "2025-08-14 16:48:13", "id": 42665, "display_status": "Reviewing", "display_trigger": "API", "display_type": "Postcard-4x6", "handwriting_image": null, "giftcard_brand_longname": "", "metadata": { "crm_deal_id": "D-1042" }, "sub_account": null } }, "Preview Response": { "summary": "Preview Response Example", "value": { "success": true, "code": 200, "message": "OK", "data": { "previews": [ "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png", "https://s3.amazonaws.com/content.thanks.io/sls-handwriting-engine/images/1056d992-b7f8-bf98-5ad5-9d089cd46e62.png" ] } } } } } } }, "400": { "$ref": "#/components/responses/UserError" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnknownError" } } } }, "/send/magnacard": { "post": { "tags": ["Send Mailer"], "summary": "Send Magnacard", "description": "Send a Magnacard.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/send-mailer-base" }, { "type": "object", "properties": { "creative_id": { "$ref": "#/components/schemas/creative-id" }, "image_template_id": { "type": "integer", "description": "ID of image template to use for front of magnacard. Required if front_image_url is not specified.", "example": 6 }, "front_image_url": { "type": "string", "description": "URL to image to use for front of magnacard. Required if image_template_id is not specified.", "example": "https://cdn.thanks.io/letter-backgrounds/bg0.png" }, "message": { "type": "string", "description": "Handwritten message content used for content on back of magnacard.", "example": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" }, "message_template_id": { "type": "integer", "description": "ID of message template to use for content on back of magnacard.", "example": 12 }, "use_custom_background": { "type": "boolean", "description": "Use custom background image. This can be used to turn off the default background image.", "default": false }, "custom_background_image": { "type": "string", "description": "URL to custom background image to use for back of magnacard. This image will be placed behind the handwritten message.", "example": "https://cdn.thanks.io/letter-backgrounds/bg0.png" } } } ] }, "examples": { "w/ Image URL/Recipients": { "summary": "Magnacard with Custom Image and Recipients", "description": "Example of sending a magnacard using a custom front image URL, handwritten message, and an array of recipients with custom fields.", "value": { "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } }, "w/ Templates/Custom Return": { "summary": "Magnacard with Templates", "description": "Example of sending a magnacard using predefined image and message templates, targeting specific mailing lists.", "value": { "return_name": "Your Company Name", "return_address": "123 Return St", "return_city": "Return City", "return_state": "RC", "return_postal_code": "12345", "image_template_id": 6, "message_template_id": 12, "mailing_list_ids": [5166, 514] } }, "Preview": { "summary": "Preview Magnacard Before Sending", "description": "Example of generating a preview of a magnacard before actually sending it. Use the preview parameter to see how it will look without placing an actual order.", "value": { "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "preview": true, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } } } } } }, "responses": { "200": { "description": "Send Mailer Success", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/send-mailer-order-response" }, { "$ref": "#/components/schemas/send-mailer-preview-response" } ] }, "examples": { "Order Submitted Response": { "summary": "Order Submitted Response Example", "value": { "total_estimated_recipients": 2, "authorization_total": 116, "leads_fee": 0, "mailing_list_ids_used": "3046,3020", "handwriting_color": "rgba(31,0,113,0.80)", "front_image": "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png", "message": "Lorem ipsum dolor sit amet", "append_or_current_resident": true, "type": "magnacard", "return_name": null, "return_address": null, "return_address2": null, "return_city": null, "return_province": null, "return_postal_code": null, "message_template_id": null, "image_template_id": 6, "method": "api", "sub_account_id": null, "font_size": "auto", "custom_background_url": "https://s3.amazonaws.com/content.thanks.io/templates/branding-builder-images/c09d39aadfc-3701d4467b8/4524cce0-78cb-11f0-b937-17570cbedaf4.png", "giftcard_brand": null, "giftcard_image": null, "giftcard_amount": null, "status": "reviewing", "addons": { "standardmail": "on" }, "style": 4, "user_id": 2, "updated_at": "2025-08-14 16:48:13", "created_at": "2025-08-14 16:48:13", "id": 42665, "display_status": "Reviewing", "display_trigger": "API", "display_type": "Magnacard", "handwriting_image": null, "giftcard_brand_longname": "", "sub_account": null } }, "Preview Response": { "summary": "Preview Response Example", "value": { "success": true, "code": 200, "message": "OK", "data": { "previews": [ "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png", "https://s3.amazonaws.com/content.thanks.io/sls-handwriting-engine/images/1056d992-b7f8-bf98-5ad5-9d089cd46e62.png" ] } } } } } } }, "400": { "$ref": "#/components/responses/UserError" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnknownError" } } } }, "/send/windowedletter": { "post": { "tags": ["Send Mailer"], "summary": "Send Windowed Letter", "description": "Send a letter in a windowed envelope.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/send-mailer-base" }, { "type": "object", "properties": { "creative_id": { "$ref": "#/components/schemas/creative-id" }, "image_template_id": { "type": "integer", "description": "ID of image template to use for the background of the cover letter. If neither image_template_id nor front_image_url is specified, a blank background will be used.", "example": 6 }, "front_image_url": { "type": "string", "description": "URL to image to use for the background of the cover letter. If neither image_template_id nor front_image_url is specified, a blank background will be used.", "example": "https://cdn.thanks.io/letter-backgrounds/bg0.png" }, "message": { "type": "string", "description": "Handwritten message content used for cover letter.", "example": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" }, "message_template_id": { "type": "integer", "description": "ID of message template to use for cover letter.", "example": 12 }, "qrcode_url": { "type": "string", "description": "URL to Autogenerate QR Code on cover letter.", "example": "https://www.google.com" }, "additional_pages_url": { "type": "string", "description": "URL to additional pages to include with the cover letter.", "example": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" }, "pdf_only_url": { "type": "string", "description": "URL to PDF file to use for entire mailer. If this is specified, no cover letter is generated. Do not include the recipient's address in your PDF: thanks.io prints each recipient's name and address in the upper-left area of page 1, where it shows through the envelope window. Leave that area blank; an address already in the PDF is printed over.", "example": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" } } } ] }, "examples": { "Image URL & Recipients": { "summary": "Windowed Letter with Custom Image and Recipients", "description": "Example of sending a windowed letter using a custom front image URL, handwritten message, and an array of recipients with custom fields.", "value": { "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } }, "PDF File Only": { "summary": "Windowed Letter with PDF File Only", "description": "Example of sending a windowed letter with a PDF file attachment, targeting specific mailing lists. Leave the upper-left address area of page 1 blank in your PDF; thanks.io prints each recipient's address there.", "value": { "pdf_only_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", "mailing_list_ids": [5166, 514] } }, "Templates & QR Code ": { "summary": "Windowed Letter with Templates, QR Code, and Additional Pages", "description": "Example of sending a windowed letter using predefined image and message templates, targeting specific mailing lists, and including a QR code for recipient engagement.", "value": { "image_template_id": 6, "message_template_id": 12, "qrcode_url": "https://www.google.com", "mailing_list_ids": [5166, 514], "additional_pages_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" } }, "Radius Search": { "summary": "Windowed Letter with Radius Search Targeting", "description": "Example of sending a windowed letter using radius search to automatically find and target recipients within a specific geographic area, with custom message and image URL.", "value": { "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "radius_search": { "address": "123 Main Street, Fake City, NY, 55555", "record_types": "likelytomove", "record_count": 10, "include_condos": false, "append_data": true } } }, "Preview": { "summary": "Preview Windowed Letter Before Sending", "description": "Example of generating a preview of a windowed letter before actually sending it. Use the preview parameter to see how your letter will look without placing an actual order.", "value": { "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "preview": true, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } } } } } }, "responses": { "200": { "description": "Send Mailer Success", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/send-mailer-order-response" }, { "$ref": "#/components/schemas/send-mailer-preview-response" } ] }, "examples": { "Order Submitted Response": { "summary": "Order Submitted Response Example", "value": { "total_estimated_recipients": 1, "authorization_total": 60, "leads_fee": 0, "mailing_list_ids_used": "", "additional_letter_pages_count": 0, "handwriting_color": "rgba(31,0,113,0.80)", "front_image": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Test Message", "append_or_current_resident": true, "type": "letter", "return_name": "Custom Return", "return_address": "1 Main Street", "return_address2": "Unit 1", "return_city": "Woodbridge", "return_province": "NJ", "return_postal_code": "07095", "message_template_id": null, "image_template_id": null, "method": "api", "sub_account_id": null, "font_size": "auto", "qrcode_url": null, "custom_background_url": null, "giftcard_brand": null, "giftcard_image": null, "giftcard_amount": null, "status": "reviewing", "addons": { "standardmail": "on" }, "style": 5, "user_id": 2, "updated_at": "2025-08-15 03:22:20", "created_at": "2025-08-15 03:22:19", "id": 42670, "display_status": "Reviewing", "display_trigger": "API", "display_type": "Windowed Letter", "giftcard_brand_longname": "", "sub_account": null, "recipients": [ { "name": "Current Resident", "address": "1 Main Street", "city": "Anytown", "province": "NY", "postal_code": "55555", "country": "US", "address2": "" } ] } }, "Preview Response": { "summary": "Preview Response Example", "value": { "success": true, "code": 200, "message": "OK", "data": { "previews": [ "https://s3.amazonaws.com/content.thanks.io/sls-handwriting-engine/images/ae538eb8-1d62-45db-8b9f-2c9b08f8e5b3.png" ] } } } } } } }, "400": { "$ref": "#/components/responses/UserError" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnknownError" } } } }, "/send/windowlessletter": { "post": { "tags": ["Send Mailer"], "summary": "Send Windowless Letter", "description": "Send a letter in a windowless envelope.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/send-mailer-base" }, { "type": "object", "properties": { "creative_id": { "$ref": "#/components/schemas/creative-id" }, "image_template_id": { "type": "integer", "description": "ID of image template to use for the background of the cover letter. If neither image_template_id nor front_image_url is specified, a blank background will be used.", "example": 6 }, "front_image_url": { "type": "string", "description": "URL to image to use for the background of the cover letter. If neither image_template_id nor front_image_url is specified, a blank background will be used.", "example": "https://cdn.thanks.io/letter-backgrounds/bg0.png" }, "message": { "type": "string", "description": "Handwritten message content used for cover letter.", "example": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" }, "message_template_id": { "type": "integer", "description": "ID of message template to use for cover letter.", "example": 12 }, "qrcode_url": { "type": "string", "description": "URL to Autogenerate QR Code on cover letter.", "example": "https://www.google.com" }, "additional_pages_url": { "type": "string", "description": "URL to additional pages to include with the cover letter.", "example": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" }, "pdf_only_url": { "type": "string", "description": "URL to PDF file to use for entire mailer. If this is specified, no cover letter is generated. The recipient's address is printed on the envelope, so do not include it in your PDF; the full page is available for your content.", "example": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" } } } ] }, "examples": { "Image URL & Recipients": { "summary": "Windowless Letter with Custom Image and Recipients", "description": "Example of sending a windowless letter using a custom front image URL, handwritten message, and an array of recipients with custom fields.", "value": { "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } }, "PDF File Only": { "summary": "Windowless Letter with PDF File Only", "description": "Example of sending a windowless letter with a PDF file attachment, targeting specific mailing lists.", "value": { "pdf_only_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", "mailing_list_ids": [5166, 514] } }, "Templates & QR Code ": { "summary": "Windowless Letter with Templates, QR Code, and Additional PPages", "description": "Example of sending a windowless letter using predefined image and message templates, targeting specific mailing lists, and including a QR code for recipient engagement.", "value": { "image_template_id": 6, "message_template_id": 12, "qrcode_url": "https://www.google.com", "mailing_list_ids": [5166, 514], "additional_pages_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" } }, "Radius Search": { "summary": "Windowless Letter with Radius Search Targeting", "description": "Example of sending a windowless letter using radius search to automatically find and target recipients within a specific geographic area, with custom message and image URL.", "value": { "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "radius_search": { "address": "123 Main Street, Fake City, NY, 55555", "record_types": "likelytomove", "record_count": 10, "include_condos": false, "append_data": true } } }, "Preview": { "summary": "Preview windowless Letter Before Sending", "description": "Example of generating a preview of a windowless letter before actually sending it. Use the preview parameter to see how your letter will look without placing an actual order.", "value": { "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "preview": true, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } } } } } }, "responses": { "200": { "description": "Send Mailer Success", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/send-mailer-order-response" }, { "$ref": "#/components/schemas/send-mailer-preview-response" } ] }, "examples": { "Order Submitted Response": { "summary": "Order Submitted Response Example", "value": { "total_estimated_recipients": 1, "authorization_total": 112, "leads_fee": 0, "mailing_list_ids_used": "", "additional_letter_pages_count": 0, "handwriting_color": "rgba(31,0,113,0.80)", "front_image": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "\n\n\n\n\n\n\n\nWhat is Lorem Ipsum? Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum. Why do we use it? It is a long established fact that a reader will be distracted by the readable content of a page when looking at its layout. The point of using Lorem Ipsum is that it has a more-or-less normal distribution of letters, as opposed to using 'Content here, content here', making it look like readable English. Many desktop publishing packages and web page editors now use Lorem Ipsum as their default model text, and a search for 'lorem ipsum' will uncover many web sites still in their infancy. Various versions have evolved over the years, sometimes by accident, sometimes on purpose (injected humour and the like).", "append_or_current_resident": true, "type": "windowlessletter", "return_name": "Custom Return", "return_address": "1 Main Street", "return_address2": "Unit 1", "return_city": "Woodbridge", "return_province": "NJ", "return_postal_code": "07095", "message_template_id": null, "image_template_id": null, "method": "api", "sub_account_id": null, "font_size": "auto", "qrcode_url": null, "custom_background_url": null, "giftcard_brand": null, "giftcard_image": null, "giftcard_amount": null, "status": "reviewing", "addons": { "standardmail": "on" }, "style": 5, "user_id": 2, "updated_at": "2025-08-15 03:50:51", "created_at": "2025-08-15 03:50:51", "id": 42676, "display_status": "Reviewing", "display_trigger": "API", "display_type": "Windowless Letter", "giftcard_brand_longname": "", "sub_account": null, "recipients": [ { "name": "Current Resident", "address": "1 Main Street", "city": "Anytown", "province": "NY", "postal_code": "55555", "country": "US", "address2": "" } ] } }, "Preview Response": { "summary": "Preview Response Example", "value": { "success": true, "code": 200, "message": "OK", "data": { "previews": [ "https://s3.amazonaws.com/content.thanks.io/sls-handwriting-engine/images/9f0bddc8-7dd1-7b1c-8d7e-d9f20084ec5d.png" ] } } } } } } }, "400": { "$ref": "#/components/responses/UserError" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnknownError" } } } }, "/send/notecard": { "post": { "tags": ["Send Mailer"], "summary": "Send Notecard", "description": "Send a folded 4.25x5.5 notecard in envelope.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/send-mailer-base" }, { "type": "object", "properties": { "creative_id": { "$ref": "#/components/schemas/creative-id" }, "image_template_id": { "type": "integer", "description": "ID of image template to use for the exterior of the notecard. Required if not front_image_url is specified.", "example": 6 }, "front_image_url": { "type": "string", "description": "URL to image to use for the exterior of the notecard. Required if image_template_id is not specified.", "example": "https://cdn.thanks.io/notecard-inspirations/note1.png" }, "message": { "type": "string", "description": "Handwritten message content to use for interior of notecard.", "example": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" }, "message_template_id": { "type": "integer", "description": "ID of message template to use for interior of notecard.", "example": 12 }, "use_custom_background": { "type": "boolean", "description": "Use custom interior background image. This can be used to turn off the default background image.", "default": false }, "custom_background_image": { "type": "string", "description": "URL to custom background image to use for interior of notecard. This image will be placed behind the handwritten message. Must be 1650px by 2475px.", "example": "https://s3.amazonaws.com/content.thanks.io/templates/branding-builder-images/c09d39aadfc-3701d4467b8/44e9a510-78cb-11f0-a77d-dd13e72edce5.png" }, "qrcode_url": { "type": "string", "description": "URL to Autogenerate QR Code in interior of notecard.", "example": "https://www.google.com" } } } ] }, "examples": { "Image URL & Recipients": { "summary": "Notecard with Custom Image and Recipients", "description": "Example of sending a notecard using a custom front image URL, handwritten message, and an array of recipients with custom fields.", "value": { "front_image_url": "https://cdn.thanks.io/notecard-inspirations/note1.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } }, "Templates & QR Code & Custom Return Address": { "summary": "Notecard with Templates, QR Code, and Custom Return Address", "description": "Example of sending a notecard using predefined image and message templates, targeting specific mailing lists, including a QR code for recipient engagement, and specifying a custom return address.", "value": { "image_template_id": 6, "message_template_id": 12, "qrcode_url": "https://www.google.com", "mailing_list_ids": [5166, 514], "return_name": "Your Company Name", "return_address": "123 Return St", "return_city": "Return City", "return_state": "RC", "return_postal_code": "12345" } }, "Radius Search": { "summary": "Notecard with Radius Search Targeting and Standard Mail", "description": "Example of sending a notecard using radius search to automatically find and target recipients within a specific geographic area, with custom message and image URL.", "value": { "front_image_url": "https://cdn.thanks.io/notecard-inspirations/note1.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "postage_class": "standard", "radius_search": { "address": "123 Main Street, Fake City, NY, 55555", "record_types": "likelytomove", "record_count": 10, "include_condos": false, "append_data": true } } }, "Preview": { "summary": "Preview notecard Letter Before Sending", "description": "Example of generating a preview of a notecard before actually sending it. Use the preview parameter to see how your letter will look without placing an actual order.", "value": { "front_image_url": "https://cdn.thanks.io/notecard-inspirations/note1.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "preview": true, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } } } } } }, "responses": { "200": { "description": "Send Mailer Success", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/send-mailer-order-response" }, { "$ref": "#/components/schemas/send-mailer-preview-response" } ] }, "examples": { "Order Submitted Response": { "summary": "Order Submitted Response Example", "value": { "total_estimated_recipients": 1, "authorization_total": 200, "leads_fee": 0, "mailing_list_ids_used": "", "handwriting_color": "rgba(31,0,113,0.80)", "front_image": "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png", "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident.", "append_or_current_resident": true, "type": "notecard", "return_name": null, "return_address": null, "return_address2": null, "return_city": null, "return_province": null, "return_postal_code": null, "message_template_id": null, "image_template_id": 6, "method": "api", "sub_account_id": null, "font_size": "auto", "qrcode_url": null, "custom_background_url": "https://s3.amazonaws.com/content.thanks.io/templates/branding-builder-images/c09d39aadfc-3701d4467b8/44e9a510-78cb-11f0-a77d-dd13e72edce5.png", "giftcard_brand": null, "giftcard_image": null, "giftcard_amount": null, "status": "reviewing", "style": 4, "user_id": 2, "updated_at": "2025-08-15 04:24:50", "created_at": "2025-08-15 04:24:50", "id": 42680, "display_status": "Reviewing", "display_trigger": "API", "display_type": "Notecard", "giftcard_brand_longname": "", "sub_account": null, "recipients": [ { "name": "Current Resident", "address": "1 Main Street", "city": "Anytown", "province": "NY", "postal_code": "55555", "country": "US", "address2": "" } ] } }, "Preview Response": { "summary": "Preview Response Example", "value": { "success": true, "code": 200, "message": "OK", "data": { "previews": [ "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png", "https://s3.amazonaws.com/content.thanks.io/sls-handwriting-engine/images/64caa2fb-a7bb-2226-da66-0440446fad30.png" ] } } } } } } }, "400": { "$ref": "#/components/responses/UserError" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnknownError" } } } }, "/send/giftcard": { "post": { "tags": ["Send Mailer"], "summary": "Send Giftcard", "description": "Send a folded 4.25x5.5 giftcard in envelope.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/send-mailer-base" }, { "type": "object", "properties": { "creative_id": { "$ref": "#/components/schemas/creative-id" }, "image_template_id": { "type": "integer", "description": "ID of image template to use for the exterior of the giftcard. Required if not front_image_url is specified.", "example": 6 }, "front_image_url": { "type": "string", "description": "URL to image to use for the exterior of the giftcard. Required if image_template_id is not specified.", "example": "https://cdn.thanks.io/notecard-inspirations/note1.png" }, "message": { "type": "string", "description": "Handwritten message content to use for interior of giftcard.", "example": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" }, "message_template_id": { "type": "integer", "description": "ID of message template to use for interior of giftcard.", "example": 12 }, "giftcard_brand": { "type": "string", "description": "Brand of giftcard to use. Must be one of the supported brands. The `/giftcard-brands` endpoint can be used to retrieve a list of supported brands. Leave this out when sending a `creative_id`: a gift card creative carries its own brand and amount, and passing this with it is rejected with a 422.", "example": "amazonus" }, "giftcard_amount_in_cents": { "type": "integer", "description": "Amount of giftcard in cents. The `/giftcard-brands` endpoint can be used to retrieve a list of supported amounts by brand. Leave this out when sending a `creative_id`: a gift card creative carries its own brand and amount, and passing this with it is rejected with a 422.", "example": 10000 } } } ] }, "examples": { "Image URL & Recipients": { "summary": "Giftcard with Custom Image and Recipients", "description": "Example of sending a giftcard using a custom front image URL, handwritten message, and an array of recipients with custom fields.", "value": { "front_image_url": "https://cdn.thanks.io/notecard-inspirations/note1.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "giftcard_brand": "amazonus", "giftcard_amount_in_cents": 10000, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } }, "Templates": { "summary": "Giftcard with Templates", "description": "Example of sending a giftcard using predefined image and message templates & targeting specific mailing lists.", "value": { "image_template_id": 6, "message_template_id": 12, "mailing_list_ids": [5166, 514], "giftcard_brand": "amazonus", "giftcard_amount_in_cents": 10000 } }, "Radius Search": { "summary": "Giftcard with Radius Search Targeting and Standard Mail", "description": "Example of sending a giftcard using radius search to automatically find and target recipients within a specific geographic area, with custom message and image URL.", "value": { "front_image_url": "https://cdn.thanks.io/notecard-inspirations/note1.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "postage_class": "standard", "giftcard_brand": "amazonus", "giftcard_amount_in_cents": 10000, "radius_search": { "address": "123 Main Street, Fake City, NY, 55555", "record_types": "likelytomove", "record_count": 10, "include_condos": false, "append_data": true } } }, "Preview": { "summary": "Preview Giftcard Before Sending", "description": "Example of generating a preview of a giftcard before actually sending it. Use the preview parameter to see how your letter will look without placing an actual order.", "value": { "front_image_url": "https://cdn.thanks.io/notecard-inspirations/note1.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "preview": true, "giftcard_brand": "amazonus", "giftcard_amount_in_cents": 10000, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } } } } } }, "responses": { "200": { "description": "Send Mailer Success", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/send-mailer-order-response" }, { "$ref": "#/components/schemas/send-mailer-preview-response" } ] }, "examples": { "Order Submitted Response": { "summary": "Order Submitted Response Example", "value": { "total_estimated_recipients": 1, "authorization_total": 179, "leads_fee": 0, "mailing_list_ids_used": "", "handwriting_color": "#000001", "front_image": "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png", "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.", "append_or_current_resident": true, "type": "giftcard", "return_name": null, "return_address": null, "return_address2": null, "return_city": null, "return_province": null, "return_postal_code": null, "message_template_id": null, "image_template_id": 6, "method": "api", "sub_account_id": null, "font_size": "auto", "qrcode_url": null, "custom_background_url": null, "giftcard_brand": "amazonus", "giftcard_image": "https://cdn.thanks.io/giftcards/amazonus.png", "giftcard_amount": 10000, "status": "reviewing", "addons": { "standardmail": "on" }, "style": 4, "user_id": 2, "updated_at": "2025-09-02 18:25:44", "created_at": "2025-09-02 18:25:44", "id": 42696, "display_status": "Reviewing", "display_trigger": "API", "display_type": "Giftcard", "giftcard_brand_longname": "Amazon.com", "sub_account": null, "recipients": [ { "name": "Current Resident", "address": "1 Main Street", "city": "Anytown", "province": "NY", "postal_code": "55555", "country": "US", "address2": "" } ] } }, "Preview Response": { "summary": "Preview Response Example", "value": { "success": true, "code": 200, "message": "OK", "data": { "previews": [ "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png", "https://s3.amazonaws.com/content.thanks.io/sls-handwriting-engine/images/de84e2b3-f3a7-9d35-edc8-4e8da81dbdc0.png" ] } } } } } } }, "400": { "$ref": "#/components/responses/UserError" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnknownError" } } } }, "/estimate/postcard": { "post": { "tags": [ "Order Estimates" ], "summary": "Estimate Postcard", "description": "Price a postcard order without placing it. Send the same request body you would send to Send Postcard: nothing is charged, nothing is printed or mailed, and no order is created.\n\nThe request is validated exactly as the send is, so a payload the send would reject is rejected here too. Recipients with only an email address are priced as if the email-to-address lookup finds them, and counted in `pending_email_lookups`. A `radius_search` is counted and priced, but no records are purchased.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/send-mailer-base" }, { "type": "object", "properties": { "creative_id": { "$ref": "#/components/schemas/creative-id" }, "image_template_id": { "type": "integer", "description": "ID of image template to use for front of postcard. Use a template of the matching type: `postcard` for 4x6, `postcard6x9` for 6x9, `postcard6x11` for 6x11. A 6x9 send also accepts a `postcard` template. Required if front_image_url is not specified.", "example": 6 }, "front_image_url": { "type": "string", "description": "URL to image to use for front of postcard. Must be 1875px by 1275px for 4x6 postcards, 2738px by 1838px for 6x9 postcards, or 3337px by 1777px for 6x11 postcards. Required if image_template_id is not specified.", "example": "https://cdn.thanks.io/letter-backgrounds/bg0.png" }, "message": { "type": "string", "description": "Handwritten message content used for content on back of postcard.", "example": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" }, "message_template_id": { "type": "integer", "description": "ID of message template to use for content on back of postcard. Use a template of the matching type: `postcard` for 4x6, `postcard6x9` for 6x9, `postcard6x11` for 6x11. A 6x9 send also accepts a `postcard` template.", "example": 12 }, "use_custom_background": { "type": "boolean", "description": "Use custom background image. This can be used to turn off the default background image.", "default": false }, "custom_background_image": { "type": "string", "description": "URL to custom background image to use for back of postcard. This image will be placed behind the handwritten message. Must be 1875px by 1275px for 4x6 postcards, 2738px by 1838px for 6x9 postcards, or 3337px by 1777px for 6x11 postcards.", "example": "https://cdn.thanks.io/letter-backgrounds/bg0.png" }, "qrcode_url": { "type": "string", "description": "URL to Autogenerate QR Code on back of postcard. If not specified, account default QR code URL will be used.", "example": "https://www.google.com" }, "size": { "type": "string", "description": "Size of the postcard. A 6x9 postcard is placed as a `postcard6x9` order and a 6x11 postcard as a `postcard6x11` order.", "default": "4x6", "enum": [ "4x6", "6x9", "6x11" ] } } } ] }, "examples": { "4x6 w/ Image URL/Recipients": { "summary": "4x6 Postcard with Custom Image and Recipients", "description": "Example of sending a 4x6 postcard using a custom front image URL, handwritten message, and an array of recipients with custom fields.", "value": { "size": "4x6", "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } } } } } }, "responses": { "200": { "description": "The order was priced. Nothing was charged and no order was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/estimate-response" }, "example": { "message": "OK", "data": { "type": "postcard", "size": "4x6", "total_recipients": 2, "recipients": { "united_states": 2, "international": 0 }, "pending_email_lookups": 0, "costs_in_cents": { "united_states": 236, "international": 0, "additional_pages": 0, "giftcard_face_value": 0, "grand_total": 236 }, "total_cost_in_cents": 236, "total_cost": "$2.36", "current_balance_in_cents": 5000, "covered_by_balance": true, "test_mode": false, "notes": [] } } } } }, "400": { "$ref": "#/components/responses/UserError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "API access has been temporarily disabled due to repeated payment failures.", "content": { "application/json": { "example": { "status": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.", "message": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.", "code": "api_disabled_payment_failures" } } } }, "422": { "description": "Validation failed on the request body, exactly as it would on the matching send." } } } }, "/estimate/windowedletter": { "post": { "tags": [ "Order Estimates" ], "summary": "Estimate Windowed Letter", "description": "Price a windowed letter order without placing it. Send the same request body you would send to Send Windowed Letter: nothing is charged, nothing is printed or mailed, and no order is created.\n\nThe request is validated exactly as the send is, so a payload the send would reject is rejected here too. Recipients with only an email address are priced as if the email-to-address lookup finds them, and counted in `pending_email_lookups`. A `radius_search` is counted and priced, but no records are purchased.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/send-mailer-base" }, { "type": "object", "properties": { "creative_id": { "$ref": "#/components/schemas/creative-id" }, "image_template_id": { "type": "integer", "description": "ID of image template to use for the background of the cover letter. If neither image_template_id nor front_image_url is specified, a blank background will be used.", "example": 6 }, "front_image_url": { "type": "string", "description": "URL to image to use for the background of the cover letter. If neither image_template_id nor front_image_url is specified, a blank background will be used.", "example": "https://cdn.thanks.io/letter-backgrounds/bg0.png" }, "message": { "type": "string", "description": "Handwritten message content used for cover letter.", "example": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" }, "message_template_id": { "type": "integer", "description": "ID of message template to use for cover letter.", "example": 12 }, "qrcode_url": { "type": "string", "description": "URL to Autogenerate QR Code on cover letter.", "example": "https://www.google.com" }, "additional_pages_url": { "type": "string", "description": "URL to additional pages to include with the cover letter.", "example": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" }, "pdf_only_url": { "type": "string", "description": "URL to PDF file to use for entire mailer. If this is specified, no cover letter is generated. Do not include the recipient's address in your PDF: thanks.io prints each recipient's name and address in the upper-left area of page 1, where it shows through the envelope window. Leave that area blank; an address already in the PDF is printed over.", "example": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" } } } ] }, "examples": { "Image URL & Recipients": { "summary": "Windowed Letter with Custom Image and Recipients", "description": "Example of sending a windowed letter using a custom front image URL, handwritten message, and an array of recipients with custom fields.", "value": { "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } } } } } }, "responses": { "200": { "description": "The order was priced. Nothing was charged and no order was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/estimate-response" }, "example": { "message": "OK", "data": { "type": "letter", "size": null, "total_recipients": 2, "recipients": { "united_states": 2, "international": 0 }, "pending_email_lookups": 0, "costs_in_cents": { "united_states": 236, "international": 0, "additional_pages": 0, "giftcard_face_value": 0, "grand_total": 236 }, "total_cost_in_cents": 236, "total_cost": "$2.36", "current_balance_in_cents": 5000, "covered_by_balance": true, "test_mode": false, "notes": [] } } } } }, "400": { "$ref": "#/components/responses/UserError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "API access has been temporarily disabled due to repeated payment failures.", "content": { "application/json": { "example": { "status": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.", "message": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.", "code": "api_disabled_payment_failures" } } } }, "422": { "description": "Validation failed on the request body, exactly as it would on the matching send." } } } }, "/estimate/windowlessletter": { "post": { "tags": [ "Order Estimates" ], "summary": "Estimate Windowless Letter", "description": "Price a windowless letter order without placing it. Send the same request body you would send to Send Windowless Letter: nothing is charged, nothing is printed or mailed, and no order is created.\n\nThe request is validated exactly as the send is, so a payload the send would reject is rejected here too. Recipients with only an email address are priced as if the email-to-address lookup finds them, and counted in `pending_email_lookups`. A `radius_search` is counted and priced, but no records are purchased.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/send-mailer-base" }, { "type": "object", "properties": { "creative_id": { "$ref": "#/components/schemas/creative-id" }, "image_template_id": { "type": "integer", "description": "ID of image template to use for the background of the cover letter. If neither image_template_id nor front_image_url is specified, a blank background will be used.", "example": 6 }, "front_image_url": { "type": "string", "description": "URL to image to use for the background of the cover letter. If neither image_template_id nor front_image_url is specified, a blank background will be used.", "example": "https://cdn.thanks.io/letter-backgrounds/bg0.png" }, "message": { "type": "string", "description": "Handwritten message content used for cover letter.", "example": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" }, "message_template_id": { "type": "integer", "description": "ID of message template to use for cover letter.", "example": 12 }, "qrcode_url": { "type": "string", "description": "URL to Autogenerate QR Code on cover letter.", "example": "https://www.google.com" }, "additional_pages_url": { "type": "string", "description": "URL to additional pages to include with the cover letter.", "example": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" }, "pdf_only_url": { "type": "string", "description": "URL to PDF file to use for entire mailer. If this is specified, no cover letter is generated. The recipient's address is printed on the envelope, so do not include it in your PDF; the full page is available for your content.", "example": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" } } } ] }, "examples": { "Image URL & Recipients": { "summary": "Windowless Letter with Custom Image and Recipients", "description": "Example of sending a windowless letter using a custom front image URL, handwritten message, and an array of recipients with custom fields.", "value": { "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } } } } } }, "responses": { "200": { "description": "The order was priced. Nothing was charged and no order was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/estimate-response" }, "example": { "message": "OK", "data": { "type": "windowlessletter", "size": null, "total_recipients": 2, "recipients": { "united_states": 2, "international": 0 }, "pending_email_lookups": 0, "costs_in_cents": { "united_states": 236, "international": 0, "additional_pages": 0, "giftcard_face_value": 0, "grand_total": 236 }, "total_cost_in_cents": 236, "total_cost": "$2.36", "current_balance_in_cents": 5000, "covered_by_balance": true, "test_mode": false, "notes": [] } } } } }, "400": { "$ref": "#/components/responses/UserError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "API access has been temporarily disabled due to repeated payment failures.", "content": { "application/json": { "example": { "status": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.", "message": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.", "code": "api_disabled_payment_failures" } } } }, "422": { "description": "Validation failed on the request body, exactly as it would on the matching send." } } } }, "/estimate/notecard": { "post": { "tags": [ "Order Estimates" ], "summary": "Estimate Notecard", "description": "Price a notecard order without placing it. Send the same request body you would send to Send Notecard: nothing is charged, nothing is printed or mailed, and no order is created.\n\nThe request is validated exactly as the send is, so a payload the send would reject is rejected here too. Recipients with only an email address are priced as if the email-to-address lookup finds them, and counted in `pending_email_lookups`. A `radius_search` is counted and priced, but no records are purchased.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/send-mailer-base" }, { "type": "object", "properties": { "creative_id": { "$ref": "#/components/schemas/creative-id" }, "image_template_id": { "type": "integer", "description": "ID of image template to use for the exterior of the notecard. Required if not front_image_url is specified.", "example": 6 }, "front_image_url": { "type": "string", "description": "URL to image to use for the exterior of the notecard. Required if image_template_id is not specified.", "example": "https://cdn.thanks.io/notecard-inspirations/note1.png" }, "message": { "type": "string", "description": "Handwritten message content to use for interior of notecard.", "example": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" }, "message_template_id": { "type": "integer", "description": "ID of message template to use for interior of notecard.", "example": 12 }, "use_custom_background": { "type": "boolean", "description": "Use custom interior background image. This can be used to turn off the default background image.", "default": false }, "custom_background_image": { "type": "string", "description": "URL to custom background image to use for interior of notecard. This image will be placed behind the handwritten message. Must be 1650px by 2475px.", "example": "https://s3.amazonaws.com/content.thanks.io/templates/branding-builder-images/c09d39aadfc-3701d4467b8/44e9a510-78cb-11f0-a77d-dd13e72edce5.png" }, "qrcode_url": { "type": "string", "description": "URL to Autogenerate QR Code in interior of notecard.", "example": "https://www.google.com" } } } ] }, "examples": { "Image URL & Recipients": { "summary": "Notecard with Custom Image and Recipients", "description": "Example of sending a notecard using a custom front image URL, handwritten message, and an array of recipients with custom fields.", "value": { "front_image_url": "https://cdn.thanks.io/notecard-inspirations/note1.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } } } } } }, "responses": { "200": { "description": "The order was priced. Nothing was charged and no order was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/estimate-response" }, "example": { "message": "OK", "data": { "type": "notecard", "size": null, "total_recipients": 2, "recipients": { "united_states": 2, "international": 0 }, "pending_email_lookups": 0, "costs_in_cents": { "united_states": 236, "international": 0, "additional_pages": 0, "giftcard_face_value": 0, "grand_total": 236 }, "total_cost_in_cents": 236, "total_cost": "$2.36", "current_balance_in_cents": 5000, "covered_by_balance": true, "test_mode": false, "notes": [] } } } } }, "400": { "$ref": "#/components/responses/UserError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "API access has been temporarily disabled due to repeated payment failures.", "content": { "application/json": { "example": { "status": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.", "message": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.", "code": "api_disabled_payment_failures" } } } }, "422": { "description": "Validation failed on the request body, exactly as it would on the matching send." } } } }, "/estimate/magnacard": { "post": { "tags": [ "Order Estimates" ], "summary": "Estimate Magnacard", "description": "Price a magnacard order without placing it. Send the same request body you would send to Send Magnacard: nothing is charged, nothing is printed or mailed, and no order is created.\n\nThe request is validated exactly as the send is, so a payload the send would reject is rejected here too. Recipients with only an email address are priced as if the email-to-address lookup finds them, and counted in `pending_email_lookups`. A `radius_search` is counted and priced, but no records are purchased.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/send-mailer-base" }, { "type": "object", "properties": { "creative_id": { "$ref": "#/components/schemas/creative-id" }, "image_template_id": { "type": "integer", "description": "ID of image template to use for front of magnacard. Required if front_image_url is not specified.", "example": 6 }, "front_image_url": { "type": "string", "description": "URL to image to use for front of magnacard. Required if image_template_id is not specified.", "example": "https://cdn.thanks.io/letter-backgrounds/bg0.png" }, "message": { "type": "string", "description": "Handwritten message content used for content on back of magnacard.", "example": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" }, "message_template_id": { "type": "integer", "description": "ID of message template to use for content on back of magnacard.", "example": 12 }, "use_custom_background": { "type": "boolean", "description": "Use custom background image. This can be used to turn off the default background image.", "default": false }, "custom_background_image": { "type": "string", "description": "URL to custom background image to use for back of magnacard. This image will be placed behind the handwritten message.", "example": "https://cdn.thanks.io/letter-backgrounds/bg0.png" } } } ] }, "examples": { "w/ Image URL/Recipients": { "summary": "Magnacard with Custom Image and Recipients", "description": "Example of sending a magnacard using a custom front image URL, handwritten message, and an array of recipients with custom fields.", "value": { "front_image_url": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } } } } } }, "responses": { "200": { "description": "The order was priced. Nothing was charged and no order was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/estimate-response" }, "example": { "message": "OK", "data": { "type": "magnacard", "size": null, "total_recipients": 2, "recipients": { "united_states": 2, "international": 0 }, "pending_email_lookups": 0, "costs_in_cents": { "united_states": 236, "international": 0, "additional_pages": 0, "giftcard_face_value": 0, "grand_total": 236 }, "total_cost_in_cents": 236, "total_cost": "$2.36", "current_balance_in_cents": 5000, "covered_by_balance": true, "test_mode": false, "notes": [] } } } } }, "400": { "$ref": "#/components/responses/UserError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "API access has been temporarily disabled due to repeated payment failures.", "content": { "application/json": { "example": { "status": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.", "message": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.", "code": "api_disabled_payment_failures" } } } }, "422": { "description": "Validation failed on the request body, exactly as it would on the matching send." } } } }, "/estimate/giftcard": { "post": { "tags": [ "Order Estimates" ], "summary": "Estimate Giftcard", "description": "Price a giftcard order without placing it. Send the same request body you would send to Send Giftcard: nothing is charged, nothing is printed or mailed, and no order is created.\n\nThe request is validated exactly as the send is, so a payload the send would reject is rejected here too. Recipients with only an email address are priced as if the email-to-address lookup finds them, and counted in `pending_email_lookups`. A `radius_search` is counted and priced, but no records are purchased.\n\nGift card face value is included in `costs_in_cents.giftcard_face_value` and in `total_cost_in_cents`. On paid plans, a card's face value is charged only when the recipient redeems it, so for a gift card order `total_cost_in_cents` is the most the order can cost, and `costs_in_cents.grand_total` is what is charged when you send. Accounts that can't send gift cards receive a `402` with the code `giftcards_require_paid_plan`, the same response the send returns.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/send-mailer-base" }, { "type": "object", "properties": { "creative_id": { "$ref": "#/components/schemas/creative-id" }, "image_template_id": { "type": "integer", "description": "ID of image template to use for the exterior of the giftcard. Required if not front_image_url is specified.", "example": 6 }, "front_image_url": { "type": "string", "description": "URL to image to use for the exterior of the giftcard. Required if image_template_id is not specified.", "example": "https://cdn.thanks.io/notecard-inspirations/note1.png" }, "message": { "type": "string", "description": "Handwritten message content to use for interior of giftcard.", "example": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" }, "message_template_id": { "type": "integer", "description": "ID of message template to use for interior of giftcard.", "example": 12 }, "giftcard_brand": { "type": "string", "description": "Brand of giftcard to use. Must be one of the supported brands. The `/giftcard-brands` endpoint can be used to retrieve a list of supported brands. Leave this out when sending a `creative_id`: a gift card creative carries its own brand and amount, and passing this with it is rejected with a 422.", "example": "amazonus" }, "giftcard_amount_in_cents": { "type": "integer", "description": "Amount of giftcard in cents. The `/giftcard-brands` endpoint can be used to retrieve a list of supported amounts by brand. Leave this out when sending a `creative_id`: a gift card creative carries its own brand and amount, and passing this with it is rejected with a 422.", "example": 10000 } } } ] }, "examples": { "Image URL & Recipients": { "summary": "Giftcard with Custom Image and Recipients", "description": "Example of sending a giftcard using a custom front image URL, handwritten message, and an array of recipients with custom fields.", "value": { "front_image_url": "https://cdn.thanks.io/notecard-inspirations/note1.png", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "handwriting_style_id": 4, "giftcard_brand": "amazonus", "giftcard_amount_in_cents": 10000, "recipients": [ { "name": "Current Resident", "address": "123 Main Street", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "custom1": "Example Custom 1", "custom2": "Example Custom 2", "custom3": "Example Custom 3", "custom4": "Example Custom 4" }, { "name": "Jane Doe", "address": "456 Another St", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US" } ] } } } } } }, "responses": { "200": { "description": "The order was priced. Nothing was charged and no order was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/estimate-response" }, "example": { "message": "OK", "data": { "type": "giftcard", "size": null, "total_recipients": 2, "recipients": { "united_states": 2, "international": 0 }, "pending_email_lookups": 0, "costs_in_cents": { "united_states": 236, "international": 0, "additional_pages": 0, "giftcard_face_value": 20000, "grand_total": 236 }, "total_cost_in_cents": 20236, "total_cost": "$202.36", "current_balance_in_cents": 5000, "covered_by_balance": false, "test_mode": false, "notes": [] } } } } }, "400": { "$ref": "#/components/responses/UserError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "API access has been temporarily disabled due to repeated payment failures, or the account can't send gift cards.", "content": { "application/json": { "example": { "status": "Gift card sends require a paid plan. This account is on the free plan — upgrade in the thanks.io dashboard, or send a postcard, letter, notecard or magnacard instead.", "message": "Gift card sends require a paid plan. This account is on the free plan — upgrade in the thanks.io dashboard, or send a postcard, letter, notecard or magnacard instead.", "error": "Gift card sends require a paid plan. This account is on the free plan — upgrade in the thanks.io dashboard, or send a postcard, letter, notecard or magnacard instead.", "errors": [ "Gift card sends require a paid plan. This account is on the free plan — upgrade in the thanks.io dashboard, or send a postcard, letter, notecard or magnacard instead." ], "failure": true, "code": "giftcards_require_paid_plan" } } } }, "422": { "description": "Validation failed on the request body, exactly as it would on the matching send." } } } }, "/build/image-template": { "get": { "tags": ["Dynamic Images"], "x-hidden": true, "summary": "Create", "description": "Build image for the front of your postcard or notecard. Includes ability to set dynmiac fields and QR code. This does not create an order, it simply builds the image and returns a URL to the image. You can then use this image URL in your order creation request.\n\n ## Dynamic Data Tags\n\nUse these tags in your header, sub-header, background image URL, and QR Code/Redirect URL to have recipient data automatically added further personalizing each postcard.\n- `~FULL_NAME~`\n- `~FIRST_NAME~`\n- `~COMPANY~`\n- `~ADDRESS~`\n- `~ADDRESS2~`\n- `~CITY~`\n- `~STATE~`\n- `~ZIP~`\n- `~EMAIL~`\n- `~PHONE~`\n- `~CUSTOM1~`\n- `~CUSTOM2~`\n- `~CUSTOM3~`\n- `~CUSTOM4~`\n- `~YOUR_FULL_NAME~`\n- `~YOUR_FIRST_NAME~`\n- `~YOUR_COMPANY~`\n- `~YOUR_EMAIL~`\n- `~YOUR_PHONE~`", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 18, "example": "8" }, "required": true, "description": "Template ID to use" }, { "name": "background_url", "in": "query", "schema": { "type": "string", "example": "~STREET_VIEW~" }, "description": "Background Image URL sits behind the generated dynamic image. Can be one of the following\n- `~MAP_VIEW~` for Google Map View. \n- `~STREET_VIEW~` for Google Street View.\n- Valid HTTP png or jpg URL " }, { "name": "header", "in": "query", "schema": { "type": "string", "example": "Want to Know ~ADDRESS~'s Value?" }, "description": "Header Text - Taggable" }, { "name": "subheader", "in": "query", "schema": { "type": "string", "example": "Scan the QR code to get an immediate value for ~ADDRESS~." }, "description": "Sub-header Text - Taggable" }, { "name": "redirect_url", "in": "query", "schema": { "type": "string", "example": "https://thanks.io" }, "description": "Location to redirect recipeint to on QR Code Scan. Can be one of the following\n- `~MESSAGE_QR~` for Message Template QR Code\n- Valid http URL" }, { "name": "logo_url", "in": "query", "schema": { "type": "string", "example": "https://cdn.thanks.io/assets/brand/logo%402x.png" }, "description": "Image Logo to use. Can be one of the following\n- `~YOUR_LOGO~` for your branding logo\n- `~YOUR_SYMBOL~`for your branding symbol\n- Valid HTTP png or jpg URL" }, { "name": "overlay_url", "in": "query", "schema": { "type": "string", "example": "https://s3.amazonaws.com/content.thanks.io/templates/dynamic-images/b96a8260-34ce-11f0-b5f2-81d9e83ce1aa.png" }, "description": "Overlay Image URL sits in front of the generated dynamic image. Must be 1875x1275 png or jpg, or 2738x1838 when `size` is `6x9`." }, { "name": "size", "in": "query", "schema": { "type": "string", "enum": ["4x6", "6x9"], "default": "4x6", "example": "6x9" }, "description": "Canvas to render the image at. `4x6` renders 1875x1275 for 4x6 postcards; `6x9` renders 2738x1838 for 6x9 postcards." } ], "responses": { "200": { "description": "Successful Response", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/handwriting-styles": { "get": { "tags": ["Handwriting Styles"], "operationId": "listHandwritingStyles", "summary": "List Styles", "description": "List Available Handwriting Styles", "security": [ { "noauthAuth": [] } ], "responses": { "200": { "description": "200 Response", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "handwriting_style_id": { "type": "integer", "description": "Unique ID of the handwriting style", "example": 1 }, "name": { "type": "string", "description": "Name of the handwriting style", "example": "Hi Clarice" }, "sample": { "type": "string", "description": "Sample image URL of the handwriting style", "example": "https://cdn.thanks.io/handwriting_examples/1.png" }, "type": { "type": "string", "description": "Type of handwriting style", "example": "Realistic", "enum": ["Realistic", "AI"] } } } } } }, "example": { "data": [ { "handwriting_style_id": 1, "sample": "https://cdn.thanks.io/handwriting_examples/1.png", "name": "Hi Clarice", "type": "Realistic" }, { "handwriting_style_id": 2, "sample": "https://cdn.thanks.io/handwriting_examples/2.png", "name": "Practiced Sharpie", "type": "Bold" }, { "handwriting_style_id": 3, "sample": "https://cdn.thanks.io/handwriting_examples/3.png", "name": "Bold Note", "type": "Bold" }, { "handwriting_style_id": 4, "sample": "https://cdn.thanks.io/handwriting_examples/4.png", "name": "Foxy Lady", "type": "Realistic" }, { "handwriting_style_id": 5, "sample": "https://cdn.thanks.io/handwriting_examples/5.png", "name": "That Dude", "type": "Bold" }, { "handwriting_style_id": 6, "sample": "https://cdn.thanks.io/handwriting_examples/6.png", "name": "Normal Print", "type": "Bold" }, { "handwriting_style_id": 7, "sample": "https://cdn.thanks.io/handwriting_examples/7.png", "name": "Shopping List", "type": "Realistic" }, { "handwriting_style_id": 8, "sample": "https://cdn.thanks.io/handwriting_examples/8.png", "name": "Lazy Note", "type": "Realistic" }, { "handwriting_style_id": 9, "sample": "https://cdn.thanks.io/handwriting_examples/9.png", "name": "Blurred Lines", "type": "Realistic" }, { "handwriting_style_id": 10, "sample": "https://cdn.thanks.io/handwriting_examples/10.png", "name": "Birthday Card", "type": "Realistic" }, { "handwriting_style_id": 11, "sample": "https://cdn.thanks.io/handwriting_examples/11.png", "name": "Scully, Not Molder", "type": "Realistic" }, { "handwriting_style_id": 12, "sample": "https://cdn.thanks.io/handwriting_examples/12.png", "name": "Wow! Signal", "type": "Realistic" }, { "handwriting_style_id": 13, "sample": "https://cdn.thanks.io/handwriting_examples/13.png", "name": "Arabic", "type": "International" }, { "handwriting_style_id": 14, "sample": "https://cdn.thanks.io/handwriting_examples/14.png", "name": "Chinese", "type": "International" }, { "handwriting_style_id": 15, "sample": "https://cdn.thanks.io/handwriting_examples/15.png", "name": "Cyrillic", "type": "International" }, { "handwriting_style_id": 16, "sample": "https://cdn.thanks.io/handwriting_examples/16.png", "name": "Hebrew", "type": "International" }, { "handwriting_style_id": 17, "sample": "https://cdn.thanks.io/handwriting_examples/17.png", "name": "Japanese", "type": "International" }, { "handwriting_style_id": 18, "sample": "https://cdn.thanks.io/handwriting_examples/18.png", "name": "Korean", "type": "International" }, { "handwriting_style_id": 19, "sample": "https://cdn.thanks.io/handwriting_examples/19.png", "name": "Vietnamese", "type": "International" }, { "handwriting_style_id": 20, "sample": "https://cdn.thanks.io/handwriting_examples/20.png", "name": "Notey", "type": "Realistic" }, { "handwriting_style_id": 101, "sample": "https://cdn.thanks.io/handwriting_examples/101.png", "name": "Optimus Prime", "type": "AI" }, { "handwriting_style_id": 102, "sample": "https://cdn.thanks.io/handwriting_examples/102.png", "name": "Binary Bard", "type": "AI" }, { "handwriting_style_id": 103, "sample": "https://cdn.thanks.io/handwriting_examples/103.png", "name": "Quantum Quip", "type": "AI" }, { "handwriting_style_id": 104, "sample": "https://cdn.thanks.io/handwriting_examples/104.png", "name": "Analytic Atom", "type": "AI" }, { "handwriting_style_id": 106, "sample": "https://cdn.thanks.io/handwriting_examples/106.png", "name": "Cerebral Circuit", "type": "AI" }, { "handwriting_style_id": 107, "sample": "https://cdn.thanks.io/handwriting_examples/107.png", "name": "Reflective Relay 2", "type": "AI" }, { "handwriting_style_id": 109, "sample": "https://cdn.thanks.io/handwriting_examples/109.png", "name": "Thoughtful Transistor", "type": "AI" }, { "handwriting_style_id": 110, "sample": "https://cdn.thanks.io/handwriting_examples/110.png", "name": "Bright Byte", "type": "AI" }, { "handwriting_style_id": 112, "sample": "https://cdn.thanks.io/handwriting_examples/112.png", "name": "Pensive Pixel", "type": "AI" }, { "handwriting_style_id": 113, "sample": "https://cdn.thanks.io/handwriting_examples/113.png", "name": "Judicious Jolt", "type": "AI" }, { "handwriting_style_id": 114, "sample": "https://cdn.thanks.io/handwriting_examples/114.png", "name": "Astute Actuator", "type": "AI" }, { "handwriting_style_id": 115, "sample": "https://cdn.thanks.io/handwriting_examples/115.png", "name": "Insightful Interface", "type": "AI" }, { "handwriting_style_id": 118, "sample": "https://cdn.thanks.io/handwriting_examples/118.png", "name": "Prudent Processor", "type": "AI" }, { "handwriting_style_id": 119, "sample": "https://cdn.thanks.io/handwriting_examples/119.png", "name": "Wise Wire", "type": "AI" }, { "handwriting_style_id": 120, "sample": "https://cdn.thanks.io/handwriting_examples/120.png", "name": "Neura Nomad", "type": "AI" }, { "handwriting_style_id": 121, "sample": "https://cdn.thanks.io/handwriting_examples/121.png", "name": "Rosario Type", "type": "AI" } ] } } } } } } }, "/giftcard-brands": { "get": { "tags": ["Giftcards"], "operationId": "listGiftcardBrands", "summary": "List Brands", "description": "List all available Giftcard brands.", "security": [ { "noauthAuth": [] } ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "main": { "description": "Featured Giftcard Brands", "$ref": "#/components/schemas/giftcard-group" }, "food": { "description": "Food Related Giftcard Brands", "$ref": "#/components/schemas/giftcard-group" }, "entertainment": { "description": "Entertainment Related Giftcard Brands", "$ref": "#/components/schemas/giftcard-group" }, "gift": { "description": "Gift Related Giftcard Brands", "$ref": "#/components/schemas/giftcard-group" }, "travel": { "description": "Travel Industry Giftcard Brands", "$ref": "#/components/schemas/giftcard-group" }, "big_box": { "description": "Big Box Store Giftcard Brands", "$ref": "#/components/schemas/giftcard-group" }, "other": { "description": "Giftcard Brands that don't fit in other categories", "$ref": "#/components/schemas/giftcard-group" } } }, "example": { "main": { "title": "Featured", "brands": [ { "brand_code": "amazonus", "title": "Amazon.com", "image": "https://cdn.thanks.io/giftcards/amazonus.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 3000, 4000, 5000, 10000, 20000 ] }, { "brand_code": "starbucksus", "title": "Starbucks", "image": "https://cdn.thanks.io/giftcards/starbucks.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ] } ] }, "food": { "title": "Food", "brands": [ { "brand_code": "applebees", "title": "Applebees", "image": "https://cdn.thanks.io/giftcards/applebees.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "baskinrobbinsus", "title": "Baskin Robbins", "image": "https://cdn.thanks.io/giftcards/baskin.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ] }, { "brand_code": "burgerkingus", "title": "Burger King", "image": "https://cdn.thanks.io/giftcards/burgerking.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "charthouse", "title": "Chart House", "image": "https://cdn.thanks.io/giftcards/charthouse.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "chilis", "title": "Chili's", "image": "https://cdn.thanks.io/giftcards/chilis.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ] }, { "brand_code": "chipotle", "title": "Chipotle", "image": "https://cdn.thanks.io/giftcards/chipotle.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "coldstonecreameryus", "title": "Cold Stone Creamery", "image": "https://cdn.thanks.io/giftcards/coldstone.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000 ] }, { "brand_code": "dominos", "title": "Domino's", "image": "https://cdn.thanks.io/giftcards/dominos.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ] }, { "brand_code": "doordashus", "title": "DoorDash", "image": "https://cdn.thanks.io/giftcards/doordash.png", "available_amounts": [ 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "dunkindonuts", "title": "Dunkin' Donuts", "image": "https://cdn.thanks.io/giftcards/dunkindonts.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ] }, { "brand_code": "grubhubus", "title": "Grubhub", "image": "https://cdn.thanks.io/giftcards/grubhub.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "ihop", "title": "IHOP", "image": "https://cdn.thanks.io/giftcards/ihop.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "mortons", "title": "Morton's The Steakhouse", "image": "https://cdn.thanks.io/giftcards/mortons.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "omahasteaks", "title": "Omaha Steaks", "image": "https://cdn.thanks.io/giftcards/omahasteaks.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "ontheborder", "title": "On The Border", "image": "https://cdn.thanks.io/giftcards/ontheborder.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ] }, { "brand_code": "outback", "title": "Outback Steakhouse", "image": "https://cdn.thanks.io/giftcards/outback.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "panerabreadus", "title": "Panera", "image": "https://cdn.thanks.io/giftcards/panera.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "papjohns", "title": "Papa John's", "image": "https://cdn.thanks.io/giftcards/papajohns.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "pfchangs", "title": "P.F. Chang's", "image": "https://cdn.thanks.io/giftcards/pfchangs.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "redrobin", "title": "Red Robin", "image": "https://cdn.thanks.io/giftcards/redrobin.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ] }, { "brand_code": "sonicus", "title": "SONIC", "image": "https://cdn.thanks.io/giftcards/sonic.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ] }, { "brand_code": "tacobellus", "title": "Taco Bell", "image": "https://cdn.thanks.io/giftcards/tacobell.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "tgifridaysus", "title": "TGI Fridays", "image": "https://cdn.thanks.io/giftcards/tjfridays.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "ubereats", "title": "Uber Eats", "image": "https://cdn.thanks.io/giftcards/ubereats.png", "available_amounts": [ 1500, 2000, 2500, 5000, 10000, 20000 ] } ] }, "entertainment": { "title": "Entertainment", "brands": [ { "brand_code": "amctheatres", "title": "AMC Theatres", "image": "https://cdn.thanks.io/giftcards/amctheaters.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ] }, { "brand_code": "itunesus", "title": "Apple Gift Card", "image": "https://cdn.thanks.io/giftcards/itunes.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "cinemark", "title": "Cinemark", "image": "https://cdn.thanks.io/giftcards/cinemark.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "fandangous", "title": "Fandango", "image": "https://cdn.thanks.io/giftcards/fandango.png", "available_amounts": [2500, 5000, 10000] }, { "brand_code": "gamestop", "title": "Game Stop", "image": "https://cdn.thanks.io/giftcards/gamestop.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "googleplay", "title": "Google Play", "image": "https://cdn.thanks.io/giftcards/googleplay.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "playstationus", "title": "Sony Playstation", "image": "https://cdn.thanks.io/giftcards/playstation.png", "available_amounts": [1000, 5000] }, { "brand_code": "regal", "title": "Regal", "image": "https://cdn.thanks.io/giftcards/regal.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000 ] }, { "brand_code": "xbox", "title": "Microsoft Xbox", "image": "https://cdn.thanks.io/giftcards/xbox.png", "available_amounts": [1500, 2500, 5000] } ] }, "gifts": { "title": "Gifts", "brands": [ { "brand_code": "1800flowers", "title": "1-800-Flowers.com", "image": "https://cdn.thanks.io/giftcards/1800flowers.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "athleta", "title": "Athleta", "image": "https://cdn.thanks.io/giftcards/athleta.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "autozoneus", "title": "AutoZone", "image": "https://cdn.thanks.io/giftcards/autozone.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "babygap", "title": "Baby Gap", "image": "https://cdn.thanks.io/giftcards/babygap.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "barnesandnoble", "title": "Barnes and Noble", "image": "https://cdn.thanks.io/giftcards/barnesandnoble.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "bassproshops", "title": "Bass Pro Shops", "image": "https://cdn.thanks.io/giftcards/bassprosshops.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "buildabear", "title": "Build-A-Bear Workshop", "image": "https://cdn.thanks.io/giftcards/buildabear.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "cabelas", "title": "Cabela's", "image": "https://cdn.thanks.io/giftcards/cabelas.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "callaway", "title": "Callaway", "image": "https://cdn.thanks.io/giftcards/callaway.png", "available_amounts": [5000, 10000] }, { "brand_code": "cratebarrelus", "title": "Crate & Barrel", "image": "https://cdn.thanks.io/giftcards/crateandbarrel.png", "available_amounts": [2500, 5000, 10000, 20000] }, { "brand_code": "cvs", "title": "CVS Pharmacy", "image": "https://cdn.thanks.io/giftcards/cvs.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "ebay1", "title": "eBay", "image": "https://cdn.thanks.io/giftcards/ebay.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ] }, { "brand_code": "fanatics", "title": "Fanatics", "image": "https://cdn.thanks.io/giftcards/fanatics.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "footlocker", "title": "Foot Locker", "image": "https://cdn.thanks.io/giftcards/footlocker.png", "available_amounts": [ 500, 1000, 1500, 2500, 5000, 10000 ] }, { "brand_code": "goplaygolf", "title": "Go Play Golf", "image": "https://cdn.thanks.io/giftcards/goplaygolf.png", "available_amounts": [2500, 5000, 10000, 20000] }, { "brand_code": "guitarcenterus", "title": "Guitar Center", "image": "https://cdn.thanks.io/giftcards/guitarcenter.png", "available_amounts": [2500, 5000, 10000, 20000] }, { "brand_code": "kohls", "title": "Kohl's", "image": "https://cdn.thanks.io/giftcards/kohls.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "landsend", "title": "Land's End", "image": "https://cdn.thanks.io/giftcards/landsend.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "reius", "title": "REI", "image": "https://cdn.thanks.io/giftcards/rei.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "sephora", "title": "Sephora", "image": "https://cdn.thanks.io/giftcards/sephora.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "spaweek", "title": "Spa Week", "image": "https://cdn.thanks.io/giftcards/spaweek.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] } ] }, "travel": { "title": "Travel", "brands": [ { "brand_code": "uber", "title": "Uber", "image": "https://cdn.thanks.io/giftcards/uberpng.png", "available_amounts": [ 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "delta", "title": "Delta Air Lines", "image": "https://cdn.thanks.io/giftcards/delta.png", "available_amounts": [5000, 10000] }, { "brand_code": "hotels", "title": "Hotels.com", "image": "https://cdn.thanks.io/giftcards/hotels.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "lyftus", "title": "Lyft", "image": "https://cdn.thanks.io/giftcards/lyft.png", "available_amounts": [2500, 5000, 10000, 20000] } ] }, "big_box": { "title": "Big Box", "brands": [ { "brand_code": "bestbuy", "title": "Best Buy", "image": "https://cdn.thanks.io/giftcards/bestbuy.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "homedepot", "title": "The Home Depot", "image": "https://cdn.thanks.io/giftcards/homedepot.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "target", "title": "Target", "image": "https://cdn.thanks.io/giftcards/target.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 3000, 4000, 5000, 10000, 20000 ] }, { "brand_code": "walmart", "title": "Walmart", "image": "https://cdn.thanks.io/giftcards/walmart.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] }, { "brand_code": "wayfairus", "title": "Wayfair", "image": "https://cdn.thanks.io/giftcards/wayfair.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ] } ] }, "other": { "title": "Other", "brands": [] } } } } } } } }, "/giftcard-brands-list": { "get": { "tags": ["Giftcards"], "operationId": "listGiftcardBrandsAsList", "summary": "List Brands Flat", "description": "List all available Giftcard brands as a flat list.", "security": [ { "noauthAuth": [] } ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/giftcard-group-list" } }, "example": { "brands": [ { "brand_code": "amazonus", "title": "Amazon.com", "image": "https://cdn.thanks.io/giftcards/amazonus.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 3000, 4000, 5000, 10000, 20000 ], "group": "Featured" }, { "brand_code": "starbucksus", "title": "Starbucks", "image": "https://cdn.thanks.io/giftcards/starbucks.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ], "group": "Featured" }, { "brand_code": "applebees", "title": "Applebees", "image": "https://cdn.thanks.io/giftcards/applebees.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "baskinrobbinsus", "title": "Baskin Robbins", "image": "https://cdn.thanks.io/giftcards/baskin.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ], "group": "Food" }, { "brand_code": "burgerkingus", "title": "Burger King", "image": "https://cdn.thanks.io/giftcards/burgerking.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "charthouse", "title": "Chart House", "image": "https://cdn.thanks.io/giftcards/charthouse.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "chilis", "title": "Chili's", "image": "https://cdn.thanks.io/giftcards/chilis.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ], "group": "Food" }, { "brand_code": "chipotle", "title": "Chipotle", "image": "https://cdn.thanks.io/giftcards/chipotle.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "coldstonecreameryus", "title": "Cold Stone Creamery", "image": "https://cdn.thanks.io/giftcards/coldstone.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000 ], "group": "Food" }, { "brand_code": "dominos", "title": "Domino's", "image": "https://cdn.thanks.io/giftcards/dominos.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ], "group": "Food" }, { "brand_code": "doordashus", "title": "DoorDash", "image": "https://cdn.thanks.io/giftcards/doordash.png", "available_amounts": [ 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "dunkindonuts", "title": "Dunkin' Donuts", "image": "https://cdn.thanks.io/giftcards/dunkindonts.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ], "group": "Food" }, { "brand_code": "grubhubus", "title": "Grubhub", "image": "https://cdn.thanks.io/giftcards/grubhub.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "ihop", "title": "IHOP", "image": "https://cdn.thanks.io/giftcards/ihop.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "mortons", "title": "Morton's The Steakhouse", "image": "https://cdn.thanks.io/giftcards/mortons.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "omahasteaks", "title": "Omaha Steaks", "image": "https://cdn.thanks.io/giftcards/omahasteaks.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "ontheborder", "title": "On The Border", "image": "https://cdn.thanks.io/giftcards/ontheborder.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ], "group": "Food" }, { "brand_code": "outback", "title": "Outback Steakhouse", "image": "https://cdn.thanks.io/giftcards/outback.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "panerabreadus", "title": "Panera", "image": "https://cdn.thanks.io/giftcards/panera.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "papjohns", "title": "Papa John's", "image": "https://cdn.thanks.io/giftcards/papajohns.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "pfchangs", "title": "P.F. Chang's", "image": "https://cdn.thanks.io/giftcards/pfchangs.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "redrobin", "title": "Red Robin", "image": "https://cdn.thanks.io/giftcards/redrobin.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ], "group": "Food" }, { "brand_code": "sonicus", "title": "SONIC", "image": "https://cdn.thanks.io/giftcards/sonic.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ], "group": "Food" }, { "brand_code": "tacobellus", "title": "Taco Bell", "image": "https://cdn.thanks.io/giftcards/tacobell.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "tgifridaysus", "title": "TGI Fridays", "image": "https://cdn.thanks.io/giftcards/tjfridays.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "ubereats", "title": "Uber Eats", "image": "https://cdn.thanks.io/giftcards/ubereats.png", "available_amounts": [ 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Food" }, { "brand_code": "amctheatres", "title": "AMC Theatres", "image": "https://cdn.thanks.io/giftcards/amctheaters.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ], "group": "Entertainment" }, { "brand_code": "itunesus", "title": "Apple Gift Card", "image": "https://cdn.thanks.io/giftcards/itunes.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Entertainment" }, { "brand_code": "cinemark", "title": "Cinemark", "image": "https://cdn.thanks.io/giftcards/cinemark.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Entertainment" }, { "brand_code": "fandangous", "title": "Fandango", "image": "https://cdn.thanks.io/giftcards/fandango.png", "available_amounts": [2500, 5000, 10000], "group": "Entertainment" }, { "brand_code": "gamestop", "title": "Game Stop", "image": "https://cdn.thanks.io/giftcards/gamestop.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Entertainment" }, { "brand_code": "googleplay", "title": "Google Play", "image": "https://cdn.thanks.io/giftcards/googleplay.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Entertainment" }, { "brand_code": "playstationus", "title": "Sony Playstation", "image": "https://cdn.thanks.io/giftcards/playstation.png", "available_amounts": [1000, 5000], "group": "Entertainment" }, { "brand_code": "regal", "title": "Regal", "image": "https://cdn.thanks.io/giftcards/regal.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000 ], "group": "Entertainment" }, { "brand_code": "xbox", "title": "Microsoft Xbox", "image": "https://cdn.thanks.io/giftcards/xbox.png", "available_amounts": [1500, 2500, 5000], "group": "Entertainment" }, { "brand_code": "1800flowers", "title": "1-800-Flowers.com", "image": "https://cdn.thanks.io/giftcards/1800flowers.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Gifts" }, { "brand_code": "athleta", "title": "Athleta", "image": "https://cdn.thanks.io/giftcards/athleta.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Gifts" }, { "brand_code": "autozoneus", "title": "AutoZone", "image": "https://cdn.thanks.io/giftcards/autozone.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Gifts" }, { "brand_code": "babygap", "title": "Baby Gap", "image": "https://cdn.thanks.io/giftcards/babygap.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Gifts" }, { "brand_code": "barnesandnoble", "title": "Barnes and Noble", "image": "https://cdn.thanks.io/giftcards/barnesandnoble.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Gifts" }, { "brand_code": "bassproshops", "title": "Bass Pro Shops", "image": "https://cdn.thanks.io/giftcards/bassprosshops.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Gifts" }, { "brand_code": "buildabear", "title": "Build-A-Bear Workshop", "image": "https://cdn.thanks.io/giftcards/buildabear.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Gifts" }, { "brand_code": "cabelas", "title": "Cabela's", "image": "https://cdn.thanks.io/giftcards/cabelas.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Gifts" }, { "brand_code": "callaway", "title": "Callaway", "image": "https://cdn.thanks.io/giftcards/callaway.png", "available_amounts": [5000, 10000], "group": "Gifts" }, { "brand_code": "cratebarrelus", "title": "Crate & Barrel", "image": "https://cdn.thanks.io/giftcards/crateandbarrel.png", "available_amounts": [2500, 5000, 10000, 20000], "group": "Gifts" }, { "brand_code": "cvs", "title": "CVS Pharmacy", "image": "https://cdn.thanks.io/giftcards/cvs.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Gifts" }, { "brand_code": "ebay1", "title": "eBay", "image": "https://cdn.thanks.io/giftcards/ebay.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ], "group": "Gifts" }, { "brand_code": "fanatics", "title": "Fanatics", "image": "https://cdn.thanks.io/giftcards/fanatics.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Gifts" }, { "brand_code": "footlocker", "title": "Foot Locker", "image": "https://cdn.thanks.io/giftcards/footlocker.png", "available_amounts": [500, 1000, 1500, 2500, 5000, 10000], "group": "Gifts" }, { "brand_code": "goplaygolf", "title": "Go Play Golf", "image": "https://cdn.thanks.io/giftcards/goplaygolf.png", "available_amounts": [2500, 5000, 10000, 20000], "group": "Gifts" }, { "brand_code": "guitarcenterus", "title": "Guitar Center", "image": "https://cdn.thanks.io/giftcards/guitarcenter.png", "available_amounts": [2500, 5000, 10000, 20000], "group": "Gifts" }, { "brand_code": "kohls", "title": "Kohl's", "image": "https://cdn.thanks.io/giftcards/kohls.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Gifts" }, { "brand_code": "landsend", "title": "Land's End", "image": "https://cdn.thanks.io/giftcards/landsend.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Gifts" }, { "brand_code": "reius", "title": "REI", "image": "https://cdn.thanks.io/giftcards/rei.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Gifts" }, { "brand_code": "sephora", "title": "Sephora", "image": "https://cdn.thanks.io/giftcards/sephora.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Gifts" }, { "brand_code": "spaweek", "title": "Spa Week", "image": "https://cdn.thanks.io/giftcards/spaweek.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Gifts" }, { "brand_code": "uber", "title": "Uber", "image": "https://cdn.thanks.io/giftcards/uberpng.png", "available_amounts": [ 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Travel" }, { "brand_code": "delta", "title": "Delta Air Lines", "image": "https://cdn.thanks.io/giftcards/delta.png", "available_amounts": [5000, 10000], "group": "Travel" }, { "brand_code": "hotels", "title": "Hotels.com", "image": "https://cdn.thanks.io/giftcards/hotels.png", "available_amounts": [ 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Travel" }, { "brand_code": "lyftus", "title": "Lyft", "image": "https://cdn.thanks.io/giftcards/lyft.png", "available_amounts": [2500, 5000, 10000, 20000], "group": "Travel" }, { "brand_code": "bestbuy", "title": "Best Buy", "image": "https://cdn.thanks.io/giftcards/bestbuy.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Big Box" }, { "brand_code": "homedepot", "title": "The Home Depot", "image": "https://cdn.thanks.io/giftcards/homedepot.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Big Box" }, { "brand_code": "target", "title": "Target", "image": "https://cdn.thanks.io/giftcards/target.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 3000, 4000, 5000, 10000, 20000 ], "group": "Big Box" }, { "brand_code": "walmart", "title": "Walmart", "image": "https://cdn.thanks.io/giftcards/walmart.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Big Box" }, { "brand_code": "wayfairus", "title": "Wayfair", "image": "https://cdn.thanks.io/giftcards/wayfair.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000, 20000 ], "group": "Big Box" } ] } } } } } } }, "/sub-accounts/": { "get": { "tags": ["Sub Accounts"], "operationId": "getSubAccounts", "summary": "List All", "description": "List all available sub-accounts.", "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/sub-account" } } } }, "example": { "data": [ { "$ref": "#/components/examples/sub-account-example" } ] } } } }, "403": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Sub Accounts"], "operationId": "createSubAccount", "summary": "Create Sub Account", "description": "Create a new sub-account.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sub-account-create" } } } }, "responses": { "201": { "description": "Created", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sub-account" }, "examples": { "sub-account": { "value": { "user_id": 2, "title": "API Update", "return_name": "Your Business", "return_address": "123 Main Street", "return_address2": "Apartment 1", "return_city": "Fake City", "return_state": "NY", "return_postal_code": null, "updated_at": "2025-09-09 18:26:51", "created_at": "2025-09-09 18:26:51", "id": 50 } } } } } }, "403": { "$ref": "#/components/responses/Unauthorized" } } } }, "/sub-accounts/{subAccountId}": { "parameters": [ { "name": "subAccountId", "in": "path", "description": "ID of sub-account", "required": true, "schema": { "type": "integer", "example": 56 } } ], "get": { "tags": ["Sub Accounts"], "operationId": "getSubAccountDetails", "summary": "Get Details", "description": "Gets a sub-account by ID. Returns a single sub-account object. branding_fields is an object that contains branding information for the sub-account - it can only be set via the thanks.io dashboard", "responses": { "200": { "description": "Successful Response", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sub-account" }, "examples": { "sub-account": { "$ref": "#/components/examples/sub-account-example" } } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": ["Sub Accounts"], "operationId": "updateSubAccount", "summary": "Update Sub Account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sub-account-create" } } } }, "responses": { "201": { "description": "Updated", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sub-account" }, "examples": { "sub-account": { "value": { "user_id": 2, "title": "API Update", "return_name": "Your Business", "return_address": "123 Main Street", "return_address2": "Apartment 1", "return_city": "Fake City", "return_state": "NY", "return_postal_code": null, "updated_at": "2025-09-09 18:26:51", "created_at": "2025-09-09 18:26:51", "id": 50 } } } } } }, "403": { "$ref": "#/components/responses/Unauthorized" } } }, "delete": { "tags": ["Sub Accounts"], "operationId": "deleteSubAccount", "summary": "Delete Sub Account. All sub account orders and mailing lists are moved to the main account. All image templates, message templates, and campaigns are deleted.", "responses": { "200": { "description": "Successful Response", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "success" } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/image-templates/": { "get": { "tags": ["Image Templates"], "operationId": "getImageTemplates", "summary": "List All", "description": "List all available image templates.", "parameters": [ { "$ref": "#/components/parameters/items_per_page" }, { "$ref": "#/components/parameters/sub_account_id" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["postcard", "postcard6x9", "postcard6x11", "letter", "windowlessletter", "notecard", "giftcard", "magnacard"] }, "description": "Only return templates of this type. `postcard` is 4x6." } ], "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/image-template" } }, "links": { "$ref": "#/components/schemas/links" }, "meta": { "$ref": "#/components/schemas/meta" } } }, "example": { "data": [ { "id": 6, "user_id": 2, "sub_account_id": null, "type": "postcard", "name": "Test", "image": "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png", "is_dynamic": false, "dynamic_image_url": null, "canva_id": null, "share_uuid": "AQQX-VYXJ-DZM6-XSPD", "created_at": "2018-08-07T00:00:00.000000Z", "updated_at": "2022-07-28T00:00:00.000000Z" }, { "id": 7, "user_id": 2, "sub_account_id": null, "type": "postcard", "name": "Test #2", "image": "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645579.png", "is_dynamic": false, "dynamic_image_url": null, "canva_id": null, "share_uuid": "ZLSK-FF7K-CF44-UVJM", "created_at": "2018-08-07T00:00:00.000000Z", "updated_at": "2022-07-28T00:00:00.000000Z" } ], "links": { "first": "https://api.thanks.io/api/v2/image-templates?page=1", "last": "https://api.thanks.io/api/v2/image-templates?page=214", "prev": null, "next": "https://api.thanks.io/api/v2/image-templates?page=2" }, "meta": { "current_page": 1, "from": 1, "last_page": 214, "path": "https://api.thanks.io/api/v2/image-templates", "per_page": "2", "to": 2, "total": 428 } } } } }, "403": { "$ref": "#/components/responses/Unauthorized" } } } }, "/creatives/": { "get": { "tags": [ "Creatives Library" ], "operationId": "getCreatives", "summary": "List All", "description": "List the creatives in your Creatives library, 24 per page: the default creative of each type first, then most recently updated. A creative pairs an image template with a message template; send one by passing its `id` as `creative_id` to any send or estimate endpoint.", "parameters": [ { "$ref": "#/components/parameters/sub_account_id" }, { "name": "mailer_type", "in": "query", "schema": { "type": "string", "enum": [ "postcard", "postcard6x9", "postcard6x11", "letter", "windowlessletter", "notecard", "giftcard", "magnacard" ] }, "description": "Only return creatives of this type. `postcard` is 4x6. Use the type you will send: a 6x9 postcard send takes a `postcard6x9` creative." }, { "name": "complete_only", "in": "query", "schema": { "type": "boolean" }, "description": "Only return creatives with both sides present (letters need only a message). Only complete creatives can be sent. Pass `1` to turn the filter on." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Only return creatives whose name contains this text." }, { "name": "include_hidden", "in": "query", "schema": { "type": "boolean" }, "description": "Include creatives hidden from the library. Pass `1` to turn it on." }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/creative" } }, "links": { "$ref": "#/components/schemas/links" }, "meta": { "$ref": "#/components/schemas/meta" } } }, "example": { "data": [ { "id": 501, "name": "Spring open house", "mailer_type": "postcard", "postcard_size": "4x6", "sub_account_id": null, "source": "user", "hidden": false, "default": true, "preview_image_url": null, "thumbnail_url": "https://cdn.thanks.io/creative-thumbnails/501.png", "share_url": "https://dashboard.thanks.io/creatives/share/6f1c2e9a-8a7d-4b8e-9d37-1c2b3a4d5e6f", "is_complete": true, "needs": [], "image_template": { "id": 6, "name": "Spring open house", "type": "postcard", "image": "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png", "is_dynamic": false, "dynamic_image_url": null, "canva_id": null, "default": false, "created_from_creative_generation_id": null, "deleted": false }, "message_template": { "id": 12, "name": "Spring open house", "type": "postcard", "content": "Hi %FIRST_NAME%, spring is here!", "handwriting_style_id": 7, "custom_background_url": null, "skip_creative_generation": false, "default": false, "deleted": false }, "back_background": null, "created_at": "2026-09-27T00:00:00.000000Z", "updated_at": "2026-10-01T00:00:00.000000Z" } ], "links": { "first": "https://api.thanks.io/api/v2/creatives?page=1", "last": "https://api.thanks.io/api/v2/creatives?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "path": "https://api.thanks.io/api/v2/creatives", "per_page": 24, "to": 1, "total": 1 } } } } }, "403": { "$ref": "#/components/responses/Unauthorized" } } } }, "/creatives/{creativeId}": { "get": { "tags": [ "Creatives Library" ], "operationId": "getCreative", "summary": "Get", "description": "Get one creative from your Creatives library, with the image and message templates it pairs.", "parameters": [ { "name": "creativeId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The creative's ID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/creative" } } }, "example": { "data": { "id": 501, "name": "Spring open house", "mailer_type": "postcard", "postcard_size": "4x6", "sub_account_id": null, "source": "user", "hidden": false, "default": true, "preview_image_url": null, "thumbnail_url": "https://cdn.thanks.io/creative-thumbnails/501.png", "share_url": "https://dashboard.thanks.io/creatives/share/6f1c2e9a-8a7d-4b8e-9d37-1c2b3a4d5e6f", "is_complete": true, "needs": [], "image_template": { "id": 6, "name": "Spring open house", "type": "postcard", "image": "https://s3.amazonaws.com/cdn.thanks.io/user_image_library/1533645532.png", "is_dynamic": false, "dynamic_image_url": null, "canva_id": null, "default": false, "created_from_creative_generation_id": null, "deleted": false }, "message_template": { "id": 12, "name": "Spring open house", "type": "postcard", "content": "Hi %FIRST_NAME%, spring is here!", "handwriting_style_id": 7, "custom_background_url": null, "skip_creative_generation": false, "default": false, "deleted": false }, "back_background": null, "created_at": "2026-09-27T00:00:00.000000Z", "updated_at": "2026-10-01T00:00:00.000000Z" } } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/message-templates/": { "get": { "tags": ["Message Templates"], "operationId": "getMessageTemplates", "summary": "List All", "description": "List all available message templates.", "parameters": [ { "$ref": "#/components/parameters/items_per_page" }, { "$ref": "#/components/parameters/sub_account_id" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["postcard", "postcard6x9", "postcard6x11", "letter", "windowlessletter", "notecard", "giftcard", "magnacard"] }, "description": "Only return templates of this type. `postcard` is 4x6." } ], "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/message-template" } }, "links": { "$ref": "#/components/schemas/links" }, "meta": { "$ref": "#/components/schemas/meta" } } }, "example": { "data": [ { "id": 1912, "user_id": 2, "sub_account_id": null, "handwriting_style_id": 102, "font_size": "small", "font_color": "#000000", "name": "Thank You Message Templates", "content": "Dear %FIRST_NAME%\\n\\nThis is another test message.", "additional_pages": null, "skip_creative_generation": 0, "custom_background_url": null, "qrcode_url": "https://www.google.com", "cc_emails": [], "created_at": "2026-08-05T02:38:44.000000Z", "updated_at": "2026-08-05T02:39:04.000000Z", "type": "postcard", "giftcard_brand_code": "", "giftcard_brand_image": null, "giftcard_amount": "", "youtube_id": "", "landing_page_url": "", "share_uuid": "TL9C-UUBP-SNT2-SX5Q", "brand_data": { "brand_code": "amazonus", "title": "Amazon.com", "image": "https://cdn.thanks.io/giftcards/amazonus.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 3000, 4000, 5000, 10000, 20000 ] }, "handwriting_realism": false }, { "id": 1913, "user_id": 2, "sub_account_id": null, "handwriting_style_id": 110, "font_size": "auto", "font_color": "rgba(31,0,113,0.80)", "name": "Birthday Card", "content": "Hey %FIRST_NAME%!, \n\nTHANK YOU for allowing us the opportunity to HELP you with your plan! \n\nHappy Birthday!", "additional_pages": null, "skip_creative_generation": 0, "custom_background_url": null, "qrcode_url": "", "cc_emails": [], "created_at": "2026-08-05T02:41:28.000000Z", "updated_at": "2026-08-05T02:41:32.000000Z", "type": "giftcard", "giftcard_brand_code": "starbucksus", "giftcard_brand_image": "https://cdn.thanks.io/giftcards/starbucks.png", "giftcard_amount": "2000", "youtube_id": "", "landing_page_url": "", "share_uuid": "PKE4-QGHH-CHZ9-QV6G", "brand_data": { "brand_code": "starbucksus", "title": "Starbucks", "image": "https://cdn.thanks.io/giftcards/starbucks.png", "available_amounts": [ 500, 1000, 1500, 2000, 2500, 5000, 10000 ] }, "handwriting_realism": false } ], "links": { "first": "https://api.thanks.io/api/v2/message-templates?page=1", "last": "https://api.thanks.io/api/v2/message-templates?page=71", "prev": null, "next": "https://api.thanks.io/api/v2/message-templates?page=2" }, "meta": { "current_page": 1, "from": 1, "last_page": 71, "path": "https://api.thanks.io/api/v2/message-templates", "per_page": "2", "to": 2, "total": 141 } } } } }, "403": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Message Templates"], "operationId": "createMessageTemplate", "summary": "Create Message Template", "description": "Create a message template for the authenticated user using the public v2 request shape.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message-template-create" }, "example": { "name": "Thank You Message", "type": "postcard", "content": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message-template" }, "example": { "id": 1912, "user_id": 2, "sub_account_id": null, "handwriting_style_id": 102, "font_size": "small", "font_color": "#000000", "name": "Thank You Message Templates", "content": "Dear %FIRST_NAME%\\n\\nThis is another test message.", "additional_pages": null, "skip_creative_generation": 0, "custom_background_url": null, "qrcode_url": "https://www.google.com", "cc_emails": [], "created_at": "2026-08-05T02:38:44.000000Z", "updated_at": "2026-08-05T02:39:04.000000Z", "type": "postcard", "giftcard_brand_code": "", "giftcard_brand_image": null, "giftcard_amount": "", "youtube_id": "", "landing_page_url": "", "share_uuid": "TL9C-UUBP-SNT2-SX5Q", "brand_data": { "brand_code": "amazonus", "title": "Amazon.com", "image": "https://cdn.thanks.io/giftcards/amazonus.png", "available_amounts": [500, 1000, 1500, 2000, 2500, 3000, 4000, 5000, 10000, 20000] }, "handwriting_realism": false } } } }, "403": { "$ref": "#/components/responses/Unauthorized" } } } }, "/message-templates/{messageTemplateId}": { "parameters": [ { "name": "messageTemplateId", "in": "path", "description": "ID of the message template", "required": true, "schema": { "type": "integer", "example": 2 } } ], "get": { "tags": ["Message Templates"], "operationId": "getMessageTemplate", "summary": "Get Message Template", "description": "Fetch a single message template by ID.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message-template" }, "example": { "id": 1912, "user_id": 2, "sub_account_id": null, "handwriting_style_id": 102, "font_size": "small", "font_color": "#000000", "name": "Thank You Message Templates", "content": "Dear %FIRST_NAME%\\n\\nThis is another test message.", "additional_pages": null, "skip_creative_generation": 0, "custom_background_url": null, "qrcode_url": "https://www.google.com", "cc_emails": [], "created_at": "2026-08-05T02:38:44.000000Z", "updated_at": "2026-08-05T02:39:04.000000Z", "type": "postcard", "giftcard_brand_code": "", "giftcard_brand_image": null, "giftcard_amount": "", "youtube_id": "", "landing_page_url": "", "share_uuid": "TL9C-UUBP-SNT2-SX5Q", "brand_data": { "brand_code": "amazonus", "title": "Amazon.com", "image": "https://cdn.thanks.io/giftcards/amazonus.png", "available_amounts": [500, 1000, 1500, 2000, 2500, 3000, 4000, 5000, 10000, 20000] }, "handwriting_realism": false } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": ["Message Templates"], "operationId": "updateMessageTemplate", "summary": "Update Message Template", "description": "Update a message template using the public v2 request shape.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message-template-update" }, "example": { "content": "Updated message body", "additional_pages": "https://example.com/additional-pages.pdf" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message-template" }, "example": { "id": 1913, "user_id": 2, "sub_account_id": null, "handwriting_style_id": 110, "font_size": "auto", "font_color": "rgba(31,0,113,0.80)", "name": "Birthday Card", "content": "Hey %FIRST_NAME%!, \n\nTHANK YOU for allowing us the opportunity to HELP you with your plan! \n\nHappy Birthday!", "additional_pages": null, "skip_creative_generation": 0, "custom_background_url": null, "qrcode_url": "", "cc_emails": [], "created_at": "2026-08-05T02:41:28.000000Z", "updated_at": "2026-08-05T02:41:32.000000Z", "type": "giftcard", "giftcard_brand_code": "starbucksus", "giftcard_brand_image": "https://cdn.thanks.io/giftcards/starbucks.png", "giftcard_amount": "2000", "youtube_id": "", "landing_page_url": "", "share_uuid": "PKE4-QGHH-CHZ9-QV6G", "brand_data": { "brand_code": "starbucksus", "title": "Starbucks", "image": "https://cdn.thanks.io/giftcards/starbucks.png", "available_amounts": [500, 1000, 1500, 2000, 2500, 5000, 10000] }, "handwriting_realism": false } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": ["Message Templates"], "operationId": "deleteMessageTemplate", "summary": "Delete Message Template", "description": "Delete a message template.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "success" } } }, "example": { "message": "success" } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/webhooks": { "get": { "tags": ["Webhooks"], "summary": "List Webhooks", "description": "Return a paginated list of configured webhooks. Webhooks are available on paid subscriptions only.", "parameters": [ { "$ref": "#/components/parameters/items_per_page" }, { "name": "type", "in": "query", "description": "Only return webhooks of this type.", "required": false, "schema": { "$ref": "#/components/schemas/webhook-type" } }, { "name": "scan_board_status", "in": "query", "description": "Only return Scan Board stage webhooks set to this stage.", "required": false, "schema": { "$ref": "#/components/schemas/scan-board-status" } } ], "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 11 }, "user_id": { "type": "integer", "example": 2 }, "mailing_list_id": { "type": ["integer", "null"], "example": 1 }, "type": { "$ref": "#/components/schemas/webhook-type" }, "scan_board_status": { "type": ["string", "null"], "enum": ["new", "contacted", "follow_up", "done", null], "description": "The Scan Board stage this webhook fires on. Required when type is scan_board.status_update; null for other types.", "example": null }, "description": { "type": ["string", "null"], "example": "Webhook for order item status updates" }, "invoke_count": { "type": "integer", "example": 0 }, "url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/thanksio" }, "verb": { "type": "string", "example": "post" }, "created_at": { "type": ["string", "null"], "format": "date-time", "example": "2026-03-02T02:10:29.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-03-10T17:45:02.000000Z" }, "deleted_at": { "type": ["string", "null"], "format": "date-time", "example": null } } } }, "links": { "$ref": "#/components/schemas/links" }, "meta": { "$ref": "#/components/schemas/meta" }, "can_manage_webhooks": { "type": "boolean", "example": true } } }, "example": { "data": [ { "id": 11, "user_id": 2, "mailing_list_id": 1, "type": "order_item.status_update", "description": "Updated webhook destination", "invoke_count": 0, "url": "https://example.com/webhooks/thanksio-updated", "verb": "get", "created_at": "2026-03-02T02:10:33.000000Z", "updated_at": "2026-03-02T02:23:27.000000Z", "deleted_at": null }, { "id": 10, "user_id": 2, "mailing_list_id": null, "type": "order.status_update", "description": "Order status updates", "invoke_count": 70, "url": "https://example.com/webhooks/thanksio", "verb": "post", "created_at": "2026-03-02T02:10:29.000000Z", "updated_at": "2026-03-10T17:45:02.000000Z", "deleted_at": null } ], "links": { "first": "https://api.thanks.io/api/v2/webhooks?page=1", "last": "https://api.thanks.io/api/v2/webhooks?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "path": "https://api.thanks.io/api/v2/webhooks", "per_page": "15", "to": 2, "total": 2 }, "can_manage_webhooks": true } } } }, "403": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Webhooks"], "operationId": "createWebhook", "summary": "Create Webhook", "description": "Create a webhook destination. Webhooks are available on paid subscriptions only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/thanksio" }, "type": { "$ref": "#/components/schemas/webhook-type" }, "scan_board_status": { "type": ["string", "null"], "enum": ["new", "contacted", "follow_up", "done", null], "description": "The Scan Board stage this webhook fires on. Required when type is scan_board.status_update; null for other types.", "example": null }, "description": { "type": ["string", "null"], "example": "Order status updates" }, "verb": { "type": "string", "example": "post" }, "mailing_list_id": { "type": ["integer", "null"], "example": null } }, "required": ["url", "type", "verb"] }, "example": { "url": "https://example.com/webhooks/thanksio", "type": "order.status_update", "description": "Order status updates", "verb": "post", "mailing_list_id": null } } } }, "responses": { "201": { "description": "Created", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/webhook-type" }, "scan_board_status": { "type": ["string", "null"], "enum": ["new", "contacted", "follow_up", "done", null], "description": "The Scan Board stage this webhook fires on. Required when type is scan_board.status_update; null for other types.", "example": null }, "url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/thanksio" }, "description": { "type": ["string", "null"], "example": "Order status updates" }, "verb": { "type": "string", "example": "post" }, "mailing_list_id": { "type": ["integer", "null"], "example": null }, "user_id": { "type": "integer", "example": 2 }, "invoke_count": { "type": "integer", "example": 0 }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-03-10T18:59:24.000000Z" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-03-10T18:59:24.000000Z" }, "id": { "type": "integer", "example": 13 } } }, "example": { "type": "order.status_update", "url": "https://example.com/webhooks/thanksio", "description": "Order status updates", "verb": "post", "mailing_list_id": null, "user_id": 2, "invoke_count": 0, "updated_at": "2026-03-10T18:59:24.000000Z", "created_at": "2026-03-10T18:59:24.000000Z", "id": 13 } } } }, "403": { "$ref": "#/components/responses/Unauthorized" } } } }, "/webhooks/{webhookId}": { "parameters": [ { "name": "webhookId", "in": "path", "description": "ID of webhook", "required": true, "schema": { "type": "integer", "example": 11 } } ], "put": { "tags": ["Webhooks"], "operationId": "updateWebhook", "summary": "Update Webhook", "description": "Update an existing webhook destination. Webhooks are available on paid subscriptions only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/thanksio-updated" }, "description": { "type": ["string", "null"], "example": "Updated webhook destination" }, "verb": { "type": "string", "example": "get" }, "type": { "$ref": "#/components/schemas/webhook-type" }, "scan_board_status": { "type": ["string", "null"], "enum": ["new", "contacted", "follow_up", "done", null], "description": "The Scan Board stage this webhook fires on. Required when type is scan_board.status_update; null for other types.", "example": null } }, "required": ["url", "type", "verb"] }, "example": { "url": "https://example.com/webhooks/thanksio-updated", "description": "Updated webhook destination", "verb": "get", "type": "order_item.status_update" } } } }, "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "example": 13 }, "user_id": { "type": "integer", "example": 2 }, "mailing_list_id": { "type": ["integer", "null"], "example": null }, "type": { "$ref": "#/components/schemas/webhook-type" }, "scan_board_status": { "type": ["string", "null"], "enum": ["new", "contacted", "follow_up", "done", null], "description": "The Scan Board stage this webhook fires on. Required when type is scan_board.status_update; null for other types.", "example": null }, "description": { "type": ["string", "null"], "example": "Updated webhook destination" }, "invoke_count": { "type": "integer", "example": 0 }, "url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/thanksio-updated" }, "verb": { "type": "string", "example": "get" }, "created_at": { "type": ["string", "null"], "format": "date-time", "example": "2026-03-10T18:59:24.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-03-10T20:54:01.000000Z" }, "deleted_at": { "type": ["string", "null"], "format": "date-time", "example": null } } }, "example": { "id": 13, "user_id": 2, "mailing_list_id": null, "type": "order_item.status_update", "description": "Updated webhook destination", "invoke_count": 0, "url": "https://example.com/webhooks/thanksio-updated", "verb": "get", "created_at": "2026-03-10T18:59:24.000000Z", "updated_at": "2026-03-10T20:54:01.000000Z", "deleted_at": null } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": ["Webhooks"], "operationId": "deleteWebhook", "summary": "Delete Webhook", "description": "Delete a webhook destination. Webhooks are available on paid subscriptions only.", "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } }, "example": { "status": "success" } } } }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/orders/list": { "get": { "tags": ["Orders"], "summary": "List Orders", "description": "Return list of recent orders.", "parameters": [ { "$ref": "#/components/parameters/items_per_page" }, { "$ref": "#/components/parameters/sub_account_id" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["postcard", "postcard6x9", "postcard6x11", "letter", "windowlessletter", "notecard", "giftcard", "magnacard", "4x6-postcard", "6x9-postcard"] }, "description": "Only return orders of this mailer type. `postcard` returns 4x6 postcards only; `postcard6x9` returns all 6x9 postcards, including 6x9 orders placed before 6x9 had its own type. `4x6-postcard` and `6x9-postcard` are accepted as aliases for `postcard` and `postcard6x9`." }, { "name": "creative_id", "in": "query", "schema": { "type": "integer" }, "description": "Only return orders sent as this creative from your Creatives library. Use an `id` from [List Creatives](/api-reference/endpoint/creatives-library/list-all-creatives)." }, { "name": "campaign", "in": "query", "schema": { "type": "integer" }, "description": "Only return orders sent by a campaign. Pass the ID of the campaign's mailing list: every order sent by that list's campaign actions is returned, including actions that have since been deleted." } ], "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/order" } }, "links": { "$ref": "#/components/schemas/links" }, "meta": { "$ref": "#/components/schemas/meta" } } }, "example": { "data": [ { "id": 42708, "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "size": "4x6", "sub_account_id": null, "type": "postcard", "display_type": "Postcard-4x6", "style": 1, "front_image": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "high_quality_preview": "", "authorization_total": 73, "grand_total": 73, "order_total": 73, "total_estimated_recipients": 1, "total_recipients": 1, "recipient_count": 1, "status": "Fulfilled", "method": "Campaign", "cancellable": false, "total_scans": 0, "metadata": { "crm_deal_id": "D-1042" }, "created_at": "2025-09-08T16:05:12.000000Z", "updated_at": "2025-09-08T16:06:08.000000Z" } ], "links": { "first": "https://api.thanks.io/api/v2/orders/list?page=1", "last": "https://api.thanks.io/api/v2/orders/list?page=4992", "prev": null, "next": "https://api.thanks.io/api/v2/orders/list?page=2" }, "meta": { "current_page": 1, "from": 1, "last_page": 4992, "path": "https://api.thanks.io/api/v2/orders/list", "per_page": "1", "to": 1, "total": 4992 } } } } }, "403": { "$ref": "#/components/responses/Unauthorized" } } } }, "/orders/{orderId}/track": { "get": { "tags": ["Orders"], "summary": "Track Order", "description": "Return Summary of delivery status for the order.", "parameters": [ { "name": "orderId", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 42708 }, "order": { "$ref": "#/components/schemas/order" }, "stats": { "type": "object", "properties": { "delivered": { "type": "integer", "description": "Number of items delivered", "example": 0 }, "processing": { "type": "integer", "description": "Number of items currently being processed", "example": 0 }, "printed": { "type": "integer", "description": "Number of items printed", "example": 1 }, "in_transit": { "type": "integer", "description": "Number of items in transit", "example": 0 }, "in_local_area": { "type": "integer", "description": "Number of items in the local delivery area", "example": 0 }, "processed_for_delivery": { "type": "integer", "description": "Number of items processed for delivery", "example": 0 }, "re_routed": { "type": "integer", "description": "Number of items re-routed", "example": 0 }, "returned_to_sender": { "type": "integer", "description": "Number of items returned to sender", "example": 0 }, "failed": { "type": "integer", "description": "Number of items that failed to be delivered", "example": 0 }, "scans": { "type": "integer", "description": "Number of times the item has been scanned", "example": 0 }, "multi_scans": { "type": "integer", "description": "Number of times the item has been scanned multiple times", "example": 0 } } }, "errors": { "type": "array", "description": "Array of recipients with errors", "items": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" }, "failure": { "type": "string" } } }, "example": [ { "name": "Current Resident", "address": "1 Main Street", "address2": "", "city": "Fake City", "province": "FC", "postal_code": "12345", "country": "US", "failure": "USPS lists address as 'no-stat' - address is unlikely to receive mail." } ] }, "returned": { "type": "array", "description": "Array of recipients whose mailers were returned", "items": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } }, "example": [ { "name": "Current Resident", "address": "1 Main Street", "address2": "", "city": "Fake City", "province": "FC", "postal_code": "12345", "country": "US" } ] } } } } }, "example": { "data": { "id": 42708, "order": { "sub_account_id": null, "type": "postcard", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "style": 1, "size": "4x6", "front_image": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "high_quality_preview": "", "total_estimated_recipients": 2, "authorization_total": 146, "total_recipients": 1, "grand_total": 73, "status": "Fulfilled", "method": "Campaign", "metadata": { "crm_deal_id": "D-1042" }, "created_at": "2025-09-08 16:05:12", "updated_at": "2025-09-08 16:06:08" }, "stats": { "delivered": 0, "processing": 0, "printed": 1, "in_transit": 0, "in_local_area": 0, "processed_for_delivery": 0, "re_routed": 0, "returned_to_sender": 0, "failed": 0, "scans": 0, "multi_scans": 0 }, "errors": [ { "name": "Current Resident", "address": "1 Main Street", "address2": "", "city": "Fake City", "province": "FC", "postal_code": "12345", "country": "US", "failure": "USPS lists address as 'no-stat' - address is unlikely to receive mail." } ], "returned": [] } } } } } } } }, "/orders/{orderId}/items": { "get": { "tags": ["Orders"], "summary": "List Order Items", "description": "Return the individual mail pieces that make up an order, one entry per recipient, with that piece's delivery status, delivery date, QR scan count, failure reason and recipient address. Use this when you need per-piece detail; Track Order returns the same order as aggregate counts instead.\n\nResults are paginated and ordered by item ID, ascending. The order must belong to the authenticated account.\n\nFor gift card orders each item also carries the gift card's `brand` and `amount`, plus `redeemed_at` and `invalidated_at` so you can see which cards have been claimed. To stop an unredeemed card from being redeemed, use Invalidate Gift Card.\n\nThe recipient's ten custom fields come back alongside the address, so the data you merged into the piece is available with it. Each item also carries a `preview` with the rendered front and back of that recipient's piece (and a PDF proof for letters and notecards), so you can see exactly what was mailed to each person. Previews are `null` until the piece has been rendered, shortly after the order is placed, and are never returned for gift card orders. Message content and per-item pricing are not part of this response; read those from the order itself.", "parameters": [ { "name": "orderId", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the order whose items you want to list." }, { "name": "per_page", "in": "query", "required": false, "description": "Number of items to return per page. Must be between 1 and 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "example": 25 }, { "name": "page", "in": "query", "required": false, "description": "Page of results to return.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 2 } ], "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/order-item" } }, "links": { "$ref": "#/components/schemas/links" }, "meta": { "$ref": "#/components/schemas/meta" } } }, "example": { "data": [ { "id": 2668662, "status": "In Transit", "delivery_date": null, "scans": 0, "failure": null, "recipient": { "name": "Tobias Example", "company": "thanks.io", "address": "12345 Main Street", "address2": "Apartment 1", "city": "Any Town", "province": "KS", "postal_code": "12345", "country": "US", "email": "tobias@example.com", "phone": "5555555555", "custom1": "Unique Info", "custom2": "For example a product code or customer ID", "custom3": "", "custom4": "", "custom5": "", "custom6": "", "custom7": "", "custom8": "", "custom9": "", "custom10": "" }, "preview": { "front": "https://cdn.thanks.io/orders/items/proofs/2668662-front.png", "back": "https://cdn.thanks.io/orders/items/proofs/2668662-back.png", "pdf": null }, "created_at": "2025-09-08T16:05:12.000000Z" }, { "id": 2668663, "status": "Delivered", "delivery_date": "2025-09-15", "scans": 2, "failure": null, "recipient": { "name": "Current Resident", "company": null, "address": "1 Main Street", "address2": "", "city": "Fake City", "province": "FC", "postal_code": "12345", "country": "US", "email": null, "phone": null, "custom1": null, "custom2": null, "custom3": null, "custom4": null, "custom5": null, "custom6": null, "custom7": null, "custom8": null, "custom9": null, "custom10": null }, "preview": { "front": "https://cdn.thanks.io/orders/items/proofs/2668663-front.png", "back": "https://cdn.thanks.io/orders/items/proofs/2668663-back.png", "pdf": null }, "created_at": "2025-09-08T16:05:12.000000Z" } ], "links": { "first": "https://api.thanks.io/api/v2/orders/42708/items?page=1", "last": "https://api.thanks.io/api/v2/orders/42708/items?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "path": "https://api.thanks.io/api/v2/orders/42708/items", "per_page": 50, "to": 2, "total": 2 } } } } }, "401": { "description": "The access token is missing or invalid, or the order belongs to another account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "errors": { "type": "array", "items": { "type": "string" }, "example": ["Unauthorized"] } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation failed on the query string — most commonly a `per_page` outside 1-100.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "example": { "errors": { "per_page": ["The per page field must be between 1 and 100."] } } } } } } } }, "/orders/{orderId}/cancel": { "put": { "tags": ["Orders"], "summary": "Cancel Order", "description": "If Order is in _Reviewing_ Status, then this will cancel the order and refund the credits for the order back to your account. If the order can be successfully canceled, the status will be updated to _cancelled_.", "parameters": [ { "name": "orderId", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "OK", "headers": { "Content-Type": { "schema": { "type": "string", "example": "application/json" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/order" } } }, "example": { "order": { "id": 42708, "user_id": 2, "sub_account_id": null, "type": "postcard", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "message_template_id": 116, "image_template_id": 195091, "style": 1, "handwriting_color": "#000001", "font_size": "auto", "handwriting_realism": true, "size": "4x6", "addons": { "standardmail": "on" }, "front_image": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "back_image": "", "preview_images": [ "https://cdn.thanks.io/letter-backgrounds/bg0.png" ], "thumbnail_images": [ "https://cdn.thanks.io/letter-backgrounds/bg0.png" ], "high_quality_preview": "", "custom_background_url": null, "additional_letter_pages": null, "skip_creative_generation": 0, "giftcard_brand": null, "giftcard_image": null, "giftcard_amount": null, "qrcode_url": null, "mailing_list_ids_used": "3047", "total_estimated_recipients": 1, "authorization_total": 73, "total_recipients": 1, "grand_total": 73, "status": "fulfilled", "method": "drip", "email_cc": null, "total_scans": 0, "unique_scans": 0, "last_scan": null, "return_name": null, "return_address": null, "return_address2": null, "return_city": null, "return_province": null, "return_postal_code": null, "display_addons": "+Standard Mail", "display_status": "Fulfilled", "display_trigger": "Campaign", "display_type": "Postcard-4x6", "giftcard_brand_longname": "", "metadata": { "crm_deal_id": "D-1042" } } } } } } } } }, "/orders/{orderId}/replay": { "post": { "tags": ["Orders"], "summary": "Replay Order", "description": "Submit a copy of a previously placed order as a brand-new order. The same creative is charged and mailed again, and the original order is left untouched. By default the replay is sent to the recipients the original actually reached (failed items are excluded). Supply a `recipients` array to send the same creative to a different audience instead.\n\nOnly settled, non-cancelled orders can be replayed. The replay is a fresh order that runs through the normal fulfillment pipeline, including Address Verification, Duplicate Prevention and suppression lists.", "parameters": [ { "name": "orderId", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the order to replay." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipients": { "type": "array", "description": "Optional override. When supplied, the replay mails the original's creative to these recipients instead of the ones the original reached. Each recipient requires an `address`; unlike the send endpoints, an address-less recipient is not accepted.", "minItems": 1, "items": { "type": "object", "required": ["address"], "properties": { "name": { "type": "string", "example": "Tobias Example" }, "company": { "type": "string", "example": "thanks.io" }, "address": { "type": "string", "example": "123 Main Street" }, "address2": { "type": "string", "example": "Apartment 1" }, "city": { "type": "string", "example": "Any Town" }, "province": { "type": "string", "description": "State or Province", "example": "KS" }, "postal_code": { "type": "string", "example": "12345" }, "country": { "type": "string", "example": "US" } } } }, "schedule_for": { "type": "string", "format": "date", "description": "Optional send date for the replay. Any format Carbon can parse is accepted; the date-only portion is stored.", "example": "2025-09-15" }, "metadata": { "type": ["object", "null"], "description": "Optional metadata for the replay. Same shape and limits as the send endpoints — returned unchanged by the order endpoints and included in every webhook event for the order as `order.metadata`. When omitted, the original order's metadata is carried over.", "additionalProperties": true, "example": { "crm_deal_id": "D-1042", "campaign": "spring-winback" } } } }, "examples": { "Replay to Original Recipients": { "summary": "Replay with no body", "description": "Submit a copy of the order and mail it to the same recipients the original reached. Failed recipients are excluded.", "value": {} }, "Replay to New Recipients": { "summary": "Send the same creative to a different audience", "description": "Reuse the original order's creative but supply a fresh recipient list.", "value": { "recipients": [ { "name": "Grace Hopper", "address": "1 Navy Yard", "city": "Phoenix", "province": "AZ", "postal_code": "85001", "country": "US" }, { "name": "Alan Turing", "address": "2 Bletchley Park", "city": "Phoenix", "province": "AZ", "postal_code": "85001", "country": "US" } ] } }, "Replay Scheduled with Metadata": { "summary": "Schedule the replay and attach metadata", "description": "Schedule the replay for a future send date and attach your own key/value data.", "value": { "schedule_for": "2025-09-15", "metadata": { "crm_deal_id": "D-1042", "campaign": "spring-winback" } } } } } } }, "responses": { "200": { "description": "Replay submitted. The response body mirrors the send endpoints' order-submitted shape, with an added `replayed_from_order_id` pointing back to the source order.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/send-mailer-order-response" }, { "type": "object", "properties": { "replayed_from_order_id": { "type": "integer", "description": "ID of the source order this replay was copied from.", "example": 42708 } } } ] }, "example": { "id": 42709, "user_id": 2, "replayed_from_order_id": 42708, "type": "postcard", "size": "4x6", "message": "Hey %FIRST_NAME%!,\n\nTHANK YOU for allowing us the opportunity to HELP you with your plan!", "front_image": "https://cdn.thanks.io/letter-backgrounds/bg0.png", "total_estimated_recipients": 1, "authorization_total": 73, "status": "reviewing", "method": "api", "display_status": "Reviewing", "display_trigger": "API", "display_type": "Postcard-4x6", "metadata": { "crm_deal_id": "D-1042" } } } } }, "400": { "description": "The order cannot be replayed. This includes a cancelled order, an order that has not settled yet, an order with no successfully mailed recipients (when `recipients` is not supplied), a charge failure, or a concurrent replay of the same order.", "content": { "application/json": { "examples": { "Not Settled": { "summary": "Order Still Fulfilling", "value": { "status": "Order #42708 is still being fulfilled and cannot be replayed until it has settled.", "message": "Order #42708 is still being fulfilled and cannot be replayed until it has settled.", "failure": true } }, "Charge Failed": { "summary": "Charge Failed During Replay", "value": { "status": "Charge failed during order replay - Please verify your payment information in your thanks.io dashboard", "message": "Charge failed during order replay - Please verify your payment information in your thanks.io dashboard" } } } } } }, "401": { "description": "The authenticated account does not own this order." }, "402": { "description": "API access has been temporarily disabled due to repeated payment failures.", "content": { "application/json": { "example": { "status": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.", "message": "API access has been temporarily disabled due to repeated payment failures. Please update your payment method.", "code": "api_disabled_payment_failures" } } } }, "422": { "description": "Validation failed on the request body — most commonly a recipient without an `address`, or an empty `recipients` array." } } } }, "/order-items/{orderItemId}/invalidate-giftcard": { "parameters": [ { "name": "orderItemId", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the order item whose gift card you want to invalidate. This is the `id` returned by List Order Items and carried by order item webhook events." } ], "put": { "tags": [ "Orders" ], "summary": "Invalidate Gift Card", "description": "Invalidate the gift card on a mailed piece so it can no longer be redeemed, for example when a card was sent by mistake. This does the same as the **Invalidate** button on the Order Details page, and it can't be undone. `PATCH` is accepted as well as `PUT`.\n\nOnly an unredeemed card that hasn't already been invalidated can be invalidated. The order must belong to the authenticated account.\n\nThe response is the updated order item, in the same shape as List Order Items. The redemption code, claim link and rendered card image are never returned.", "responses": { "200": { "description": "The gift card was invalidated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/order-item" } } }, "example": { "data": { "id": 2668662, "status": "Delivered", "delivery_date": "2025-09-15", "scans": 0, "failure": null, "recipient": { "name": "Jane Doe", "company": null, "address": "456 Another St", "address2": "", "city": "Fake City", "province": "NY", "postal_code": "55555", "country": "US", "email": null, "phone": null, "custom1": null, "custom2": null, "custom3": null, "custom4": null, "custom5": null, "custom6": null, "custom7": null, "custom8": null, "custom9": null, "custom10": null }, "giftcard": { "brand": "amazonus", "amount": 2500, "redeemed_at": null, "invalidated_at": "2025-09-20T14:02:11.000000Z" }, "created_at": "2025-09-08T16:05:12.000000Z" } } } } }, "401": { "description": "The access token is missing or invalid, or the order belongs to another account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "errors": { "type": "array", "items": { "type": "string" }, "example": [ "Unauthorized" ] } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The gift card can't be invalidated: it was already redeemed or invalidated, the item isn't on a gift card order, or the item has no gift card.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "failed" }, "errors": { "type": "array", "items": { "type": "string" }, "example": [ "Giftcard has already been redeemed." ] } } }, "examples": { "Already Redeemed": { "value": { "status": "failed", "errors": [ "Giftcard has already been redeemed." ] } }, "Already Invalidated": { "value": { "status": "failed", "errors": [ "Giftcard has already been invalidated." ] } }, "Not a Gift Card Order": { "value": { "status": "failed", "errors": [ "Order is not a giftcard order." ] } } } } } } } } } } }