{ "openapi": "3.0.0", "info": { "title": "Handwrytten API", "version": "3.15.0", "description": "## About\nSend personalized, handwritten cards to anyone using the Handwrytten API. Choose from a variety of handwriting styles, customize cards with your logo, and automate your card-sending workflow at any scale.\n## Test Mode\nDuring development your account can be switched to test mode on the [Integrations](https://app.handwrytten.com/integrations) page in your dashboard. In test mode, orders are accepted normally but are not fulfilled. Payments are authorized but not captured, so any pending charge will drop off without posting. Just make sure to switch back to live mode before going live.\n## Client Libraries\nIf you're working in Python or JavaScript/TypeScript, you can use one of the official client packages instead of making raw API calls:\n- **Python:** [`handwrytten` on PyPI](https://pypi.org/project/handwrytten/)\n- **JavaScript/TypeScript:** [`handwrytten` on npm](https://www.npmjs.com/package/handwrytten)\nDocumentation for each package is available on the respective package page.\n## Authentication\nAuthenticate by including your API key in the `Authorization` request header — pass the key directly, with no `Bearer:` prefix:\n```\nAuthorization: YOUR_API_KEY\n```\nAPI keys can be created and managed on the [Integrations](https://app.handwrytten.com/integrations) page in your dashboard.\n> **Note:** Authentication using login/password via `/auth/authorization` is deprecated. It remains supported for existing integrations but is not recommended for new ones." }, "servers": [ { "url": "https://api.handwrytten.com/v2", "description": "Production Server v2" }, { "url": "https://api2.handwrytten.com/api/v1/user/", "description": "Production Server v2" } ], "security": [ { "ApiKeyAuth": [] }, { "uidKey": [] } ], "tags": [ { "name": "Getting Started" }, { "name": "Authentication", "description": "Authentication" }, { "name": "Cards", "description": "Cards" }, { "name": "Orders", "description": "Order management" }, { "name": "Basket", "description": "Shopping basket" }, { "name": "Address Book", "description": "Address management" }, { "name": "QR Codes", "description": "QR code management" }, { "name": "Prospecting", "description": "Outbound prospecting campaigns" } ], "paths": { "/auth/authorization": { "post": { "summary": "Sign In with Password", "deprecated": true, "description": "Authenticates with login/password and returns a `uid` token, which can then be passed in subsequent API calls either in the `Authorization` header or as a `uid` parameter in the request body.\n\nThis endpoint is deprecated and not recommended for new integrations. It remains supported for existing clients authenticating with login/password.\n\nFor new integrations, use an API key instead — generate one on the [Integrations](https://app.handwrytten.com/integrations) page in your dashboard, and pass it directly in the `Authorization` header with no `Bearer:` prefix.", "tags": [ "Getting Started", "Authentication" ], "operationId": "auth_authorization", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "login", "password" ], "properties": { "login": { "type": "string" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "uid": { "type": "string", "description": "User's auth token" } } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 401 ] }, "status": { "type": "string", "enum": [ "error" ] }, "message": { "type": "string", "enum": [ "Login data is invalid.", "Password is incorrect.", "Your account is not activated. Check your email.", "Your account is blocked." ] } } } } } } } } }, "/checkauth/auth": { "get": { "tags": [ "Authentication" ], "summary": "Check Authentication", "description": "Verifies that the provided API key or token is valid. Useful for validating a saved API key before storing it, or checking whether a `uid` token is still active before making other calls.", "operationId": "checkauth_auth", "responses": { "200": { "description": "successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "login": { "type": "string", "example": "example@example.com" }, "has_no_password": { "type": "boolean" }, "last": { "type": "string", "enum": [ "google", "facebook", "email" ] }, "test_mode": { "type": "integer", "enum": [ 0, 1 ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/auth/getUser": { "get": { "summary": "Get User Info", "description": "Returns profile and account information for the user associated with the API key, including name, email, billing address, and credits. Most integrations won't need this — the main use case is checking remaining credits.", "tags": [ "Authentication" ], "operationId": "auth_getUser", "parameters": [ { "in": "header", "name": "Authorization", "description": "User's token or API key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 200 ] }, "status": { "type": "string", "enum": [ "ok" ] }, "id": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/setTestMode": { "post": { "summary": "Toggle Test Mode", "description": "Switches test mode on or off for the user associated with the API key. Pass `1` to enable test mode or `0` to return to live mode.\n\nIn test mode, orders are accepted and processed normally but are not fulfilled. Credit balances are checked but not deducted, and payments are authorized but not captured — any pending charge will drop off without posting.", "tags": [ "Authentication" ], "operationId": "auth_setTestMode", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "test_mode": { "type": "integer", "enum": [ 0, 1 ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 200 ] }, "status": { "type": "string", "enum": [ "ok" ] }, "test_mode": { "type": "integer", "enum": [ 0, 1 ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/logout": { "post": { "tags": [ "Authentication" ], "summary": "Log Out", "deprecated": true, "description": "Invalidates a `uid` token obtained via the deprecated login/password authentication. Tokens expire automatically, but this call can be used to force-invalidate one immediately if needed for security reasons.\n\nNot applicable when using API key authentication.", "operationId": "auth_logout", "security": [ {}, { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "uid" ], "properties": { "uid": { "type": "string", "example": "7f736a7b02bd460ca1953d926716bb51" } } } } } }, "responses": { "200": { "description": "successful logout" } } } }, "/orders/singleStepOrder": { "post": { "summary": "Single Step Order", "description": "Creates and submits a complete order in a single API call. This is the most commonly used endpoint — for most integrations, it's the only one you'll need.\n\nRequires an API key in the `Authorization` header. See the [Integrations](https://app.handwrytten.com/integrations) page in your dashboard to generate one.", "tags": [ "Getting Started", "Orders" ], "operationId": "single_step_order", "security": [ {}, { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "font_label", "card_id", "message", "sender_address1", "sender_city", "sender_zip", "recipient_address1", "recipient_city", "recipient_zip" ], "properties": { "uid": { "type": "string", "deprecated": true, "description": "Deprecated. Pass your API key in the `Authorization` header instead.", "example": "dlqwjkqwdlkjqwdq09302184383" }, "login": { "type": "string", "deprecated": true, "description": "Deprecated. Use API key authentication instead.", "example": "john@jjf.com" }, "password": { "type": "string", "deprecated": true, "description": "Deprecated. Use API key authentication instead.", "example": "8yfqwiuy@!$" }, "card_id": { "type": "integer", "description": "Id of the card you want to send", "example": 3404 }, "denomination_id": { "type": "integer", "description": "Optional. Use if sending a gift card", "example": 12 }, "message": { "type": "string", "description": "The body of the message. Use '\\n' for new lines", "example": "Dear Frank,\nThank you so much for your interest in our services." }, "wishes": { "type": "string", "description": "The right-shifted closing part of the note", "example": "All the best,\nJoe" }, "font_label": { "type": "string", "description": "The colloquial name of the font, such as 'Fancy Jenna' or 'Casual David'", "example": "Chill Charity" }, "credit_card_id": { "type": "integer", "description": "The credit card id to charge for the order.", "example": 34124 }, "insert_id": { "type": "integer", "description": "Insert id for the order" }, "couponCode": { "type": "string", "description": "Coupon code" }, "date_send": { "type": "string", "description": "Send date" }, "validate_address": { "type": "boolean" }, "webhook_url": { "type": "string", "description": "Webhook URL" }, "sender_first_name": { "type": "string" }, "sender_last_name": { "type": "string" }, "sender_address1": { "type": "string" }, "sender_address2": { "type": "string" }, "sender_city": { "type": "string" }, "sender_zip": { "type": "string" }, "sender_state": { "type": "string", "description": "Required for US and Canada (country id 1 or 2)" }, "sender_country_id": { "type": "integer", "default": 1, "example": 1, "description": "1 (United States) by default" }, "sender_country": { "type": "string", "description": "United States by default" }, "recipient_first_name": { "type": "string" }, "recipient_last_name": { "type": "string" }, "recipient_address1": { "type": "string" }, "recipient_address2": { "type": "string" }, "recipient_city": { "type": "string" }, "recipient_zip": { "type": "string" }, "recipient_state": { "type": "string", "description": "Required for US and Canada (country id 1 or 2)" }, "recipient_country_id": { "type": "integer", "default": 1, "example": 1, "description": "1 (United States) by default" }, "recipient_country": { "type": "string", "description": "United States by default" }, "client_metadata": { "type": "string", "description": "Order metadata" } } } } } }, "responses": { "200": { "description": "successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "order_id": { "type": "integer", "example": 196936 }, "mail_sent": { "type": "integer", "enum": [ 0, 1 ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 400 }, "error": { "type": "string", "description": "error description", "enum": [ "font label error", "card id error", "Card not found", "You have a message that is too long for the card. Either shorten your message or choose another card", "Sender address: {error details}", "Error saving sender address.", "Recipient address: {error details}", "Error saving recipient address.", "no such card", "no such gift card", "error placing order", "no such insert", "Coupon already used", "Coupon already expired", "addresses count error", "card is not available for free", "no free cards", "cannot buy", "no return info", "no such address", "no such country", "no credit cards", "credit_card id error", "no such credit card", "[response from Authorize.Net]", "error processing payment", "Oops! Please check sender name", "Oops! Please check sender address", "Oops! Please check sender city", "Oops! Please check sender ZIP code", "Oops! Please check sender country", "Oops! Please check recipient name", "Oops! Please check recipient address", "Oops! Please check recipient city", "Oops! Please check recipient ZIP code", "Oops! Please check recipient country" ] } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 401 }, "error": { "type": "string", "description": "error description", "enum": [ "no uid" ] } } } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 500 }, "message": { "type": "string", "description": "error description", "enum": [ "error placing main order", "error placing child orders", "error placing order", "error placing order (saving from address)", "error placing order (saving to address)" ] } } } } } } } } }, "/orders/placeBasket": { "post": { "tags": [ "Orders" ], "summary": "Add Order to Basket", "description": "Adds an order to the basket without submitting. Supports both single and bulk recipients. Once all orders are added, call `/basket/send` to process payment and submit the orders.", "operationId": "place_basket", "security": [ {}, { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "uid": { "type": "string", "deprecated": true, "description": "Deprecated. Pass your API key in the `Authorization` header instead." }, "card_id": { "type": "integer", "description": "The ID of the card to send.", "example": 13 }, "return_address_id": { "type": "integer", "description": "If not provided, the account's default return address will be used." }, "address_id": { "type": "integer", "description": "A single address id to send an order to. Alternatively, use an array of addresses.", "deprecated": true }, "address_ids": { "type": "array", "description": "Required if addresses is not present", "items": { "type": "integer" } }, "addresses": { "type": "array", "description": "Required if address_ids is not present, for bulk order, from `bulk_address_parse_xls` request. Contains both the addresses and the message to send.", "items": { "type": "object", "properties": { "to_first_name": { "type": "string", "example": "Joe" }, "to_last_name": { "type": "string", "example": "Smith" }, "to_business_name": { "type": "string", "example": "Smith Actuators" }, "to_address1": { "type": "string", "example": "123 Main Street" }, "to_address2": { "type": "string", "example": "Suite 321" }, "to_city": { "type": "string", "example": "Chicago" }, "to_state": { "type": "string", "example": "IL" }, "to_zip": { "type": "string", "example": "60614" }, "to_country": { "type": "string", "example": "United States" }, "return_first_name": { "type": "string", "example": "Ronnie" }, "return_last_name": { "type": "string", "example": "Return" }, "return_business_name": { "type": "string", "example": "Return Reversals Inc" }, "return_address1": { "type": "string", "example": "321 East St" }, "return_address2": { "type": "string", "example": "Apt 201" }, "return_city": { "type": "string", "example": "Phoenix" }, "return_state": { "type": "string", "example": "AZ" }, "return_zip": { "type": "string", "example": "85258" }, "return_country": { "type": "string", "example": "United States" }, "message": { "type": "string", "example": "Dear Joe,\nThanks for all the fish." }, "wishes": { "type": "string", "description": "The right-shifted closing part of the note", "example": "All the best,\nRonnie" }, "signature_id": { "type": "integer", "description": "signature ID for wishes block", "example": 12 }, "date_send": { "type": "string", "example": "2019-07-22T03:45:09.000Z" }, "signature2_id": { "type": "integer", "description": "signature ID for main block" } } } }, "font": { "type": "string", "description": "font id", "example": "hwDavid" }, "font_size": { "type": "integer", "example": 13 }, "auto_font_size": { "type": "boolean" }, "for_free": { "type": "boolean" }, "couponCode": { "type": "string" }, "denomination_id": { "type": "integer" }, "insert_id": { "type": "integer" }, "quantity": { "type": "integer", "deprecated": true }, "check_quantity": { "type": "boolean", "description": "check cards and inserts quantity in stock, return `insufficient quantity` error in case of low stock" }, "client_metadata": { "type": "string", "description": "Card metadata" } } } } } }, "responses": { "200": { "description": "successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "order_id": { "type": "integer", "example": 725563 } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 400 }, "error": { "type": "string", "description": "error description", "enum": [ "no uid", "card id error", "not found", "address error", "message error", "font error", "insufficient quantity", "no such card", "no such gift card", "no such insert", "Coupon already used", "Coupon already expired", "addresses count error", "card is not available for free", "no free cards", "cannot buy", "no return info", "no such address", "no such country" ] } } } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "integer", "example": 500 }, "message": { "type": "string", "description": "error description", "enum": [ "error placing order (recipient address not found)", "error placing main order", "error placing child orders", "error placing order", "error placing order (saving from address)", "error placing order (saving to address)" ] } } } } } } } } }, "/orders/details": { "get": { "tags": [ "Orders" ], "summary": "Order Details", "description": "Returns full details for a given order, including status, recipient address, card, pricing, and delivery information. Most commonly used to check order status or delivery confirmation status (if delivery confirmation was added to the order).", "operationId": "order_details", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Order id", "required": true, "schema": { "type": "integer", "example": 725563 } } ], "responses": { "200": { "description": "Order details", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "order": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "example": 725563 }, "basket_id": { "type": "integer", "format": "int64", "example": 196936 }, "for_free": { "type": "boolean" }, "date_created": { "type": "integer", "format": "int64", "example": 1549260840 }, "message": { "type": "string", "example": "TEST! This is a test message." }, "message_orig": { "type": "string", "example": "TEST! This is a test message." }, "font": { "type": "string", "example": "hwWill" }, "fontInfo": { "$ref": "#/components/schemas/FontInfoVerbose" }, "address_from": { "$ref": "#/components/schemas/Address" }, "address_to": { "type": "object", "nullable": true }, "price": { "type": "integer", "format": "int64", "example": 7 }, "used_credit": { "type": "integer", "format": "int64", "example": 7 }, "payed": { "type": "integer", "format": "int64", "example": 0 }, "status": { "type": "string", "example": "suspended" }, "date_day": { "type": "string", "example": "4" }, "date_month": { "type": "string", "example": "Feb" }, "date_year": { "type": "string", "example": "2019" }, "date_send": { "type": "string", "format": "date", "example": "2024-02-04T00:00:00.000Z" }, "card_category_name": { "type": "string", "example": "Birthday" }, "card_name": { "type": "string", "example": "So Glad You Were Born!" }, "card_cover": { "type": "string", "example": "https://d3e924qpzqov0g.cloudfront.net/cardimages/201811260603_Glad-you-were-born-4.25x5x5-500.jpg" }, "multiaddress": { "type": "integer", "format": "int64", "example": 1 }, "is_bulk": { "type": "integer", "format": "int64", "example": 1 }, "delivery_cost": { "type": "integer", "format": "int64", "example": 0 }, "notes": { "type": "string", "nullable": true }, "test_mode": { "type": "integer", "format": "int64", "example": 0 }, "tax": { "type": "string", "nullable": true }, "refund_status": { "type": "integer", "format": "int64", "example": -2 }, "wishes": { "type": "string", "description": "wishes as part of the signature in the letter" }, "signature_id": { "type": "integer", "description": "signature ID for wishes block" }, "signature_preview": { "type": "string", "description": "URL" }, "signature2_id": { "type": "integer", "description": "signature ID for main block" }, "signature2_preview": { "type": "string", "description": "URL" }, "card": { "type": "object", "properties": { "id": { "type": "integer", "example": 44 }, "name": { "type": "string", "example": "So Glad You Were Born!" }, "cover": { "type": "string" }, "price": { "type": "integer", "example": 14 }, "price_orig": { "type": "integer", "example": 0 }, "category_id": { "type": "integer", "example": 7 }, "quantity": { "type": "integer", "example": 2 }, "delivery_cost": { "type": "integer", "example": 0 } } }, "card_dimensions": { "type": "object", "properties": { "closed_width": { "type": "string", "example": "4.25" }, "closed_height": { "type": "string", "example": "5.5" }, "margin_top": { "type": "string", "example": "0.25" }, "margin_right": { "type": "string", "example": "0.25" }, "margin_bottom": { "type": "string", "example": "0.25" }, "margin_left": { "type": "string", "example": "0.25" }, "font_size": { "type": "string", "example": "32" }, "half_inside": { "type": "string" } } }, "quantity": { "type": "integer", "example": 2 }, "childs": { "type": "array", "description": "*NOTE*: List only 5 child orders, use `list_childs` request to get all child orders", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 725564 }, "message": { "type": "string" }, "address_to": { "$ref": "#/components/schemas/Address" }, "status": { "type": "string", "example": "suspended" }, "delivery_cost": { "type": "integer", "example": 0 }, "price": { "type": "number", "example": 3.5 }, "used_credit": { "type": "number", "example": 3.5 }, "tax": { "type": "string", "nullable": true }, "address_from": { "$ref": "#/components/schemas/Address" } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 404 }, "error": { "type": "string", "description": "error description", "enum": [ "order not found" ] } } } } } }, "422": { "description": "no order id", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 422 }, "error": { "type": "string", "description": "error description", "enum": [ "request error" ] } } } } } } } } }, "/orders/cancel": { "post": { "tags": [ "Orders" ], "summary": "Cancel Order", "description": "Cancel order by order id. Only orders with status `paid` can be canceled. Orders that have already been processed cannot be canceled and will return 400 error.", "operationId": "order_cancel", "security": [ {}, { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "uid": { "type": "string", "deprecated": true, "description": "Deprecated. Pass your API key in the `Authorization` header instead." }, "order_id": { "type": "integer", "description": "The ID of the order to cancel.", "example": 725563 } } } } } }, "responses": { "200": { "description": "successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "httpCode": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "no such order" } } } } } } } } }, "/basket/send": { "post": { "tags": [ "Basket" ], "summary": "Send Basket", "description": "Submits all orders currently in the basket for processing. Credits are applied first; if the order total exceeds the available credit balance, the remainder is charged to the credit card on file or the one provided in the request.", "operationId": "basket_send", "security": [ {}, { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "uid": { "type": "string", "deprecated": true, "description": "Deprecated. Pass your API key in the `Authorization` header instead." }, "couponCode": { "type": "string" }, "credit_card_id": { "type": "integer", "description": "If provided, it is the id number of the credit card on file to be charged.", "example": 344 }, "check_quantity": { "type": "boolean", "description": "check cards and inserts quantity in stock, return `insufficient quantity` error in case of low stock" }, "notes": { "type": "object", "description": "dictionary of order notes, order id is used as a key", "additionalProperties": { "type": "string", "description": "order note" }, "example": { "196936": "note 1", "196937": "note 2" } }, "price_structure": { "type": "object", "description": "Expected structure price by types of payment. If the structure does not match during the calculation, an error will be returned", "properties": { "coupon": { "type": "number", "example": 10 }, "credit1": { "type": "number", "example": 5 }, "credit2": { "type": "number", "example": 3.45 }, "money": { "type": "number", "example": 1.12 } } } } } } } }, "responses": { "200": { "description": "successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "items": { "type": "object", "description": "dictionary of order objects, order id is used as a key", "additionalProperties": { "type": "object", "properties": { "id": { "type": "string", "example": "9513" }, "card_id": { "type": "string", "example": "863" }, "order_id": { "type": "string", "example": "44369" }, "is_bulk": { "type": "string", "example": "0" }, "denomination_id": { "type": "string", "example": "13" }, "message": { "type": "string", "example": "Hello!" }, "wishes": { "type": "string", "example": "best regards" }, "signature": { "$ref": "#/components/schemas/Signature" }, "signature2": { "$ref": "#/components/schemas/Signature" }, "for_free": { "type": "string", "example": "0" }, "price": { "type": "string", "example": "1" }, "discount_code": { "type": "string", "nullable": true }, "font": { "type": "string", "example": "hwJenna" }, "quantity": { "type": "string", "example": "1" }, "date_to_send": { "type": "string", "nullable": true }, "delivery_cost": { "type": "string", "example": "0.55" }, "intl_quantity": { "type": "string", "nullable": true }, "addressId": { "type": "string", "example": "108883" }, "address_to": { "$ref": "#/components/schemas/Address" }, "address_from": { "$ref": "#/components/schemas/Address" }, "denomination": { "$ref": "#/components/schemas/Denomination" }, "giftCard": { "$ref": "#/components/schemas/GiftCard" }, "fontInfo": { "$ref": "#/components/schemas/FontInfo" }, "date_day": { "type": "string", "example": "22" }, "date_month": { "type": "string", "example": "Jul 2019" }, "date_send": { "type": "string", "format": "date", "example": "2019-07-23T00:00:00.000Z" }, "card_category_name": { "type": "string", "example": "Birthday" }, "card_name": { "type": "string", "example": "Ivan1" }, "card_cover": { "type": "string" }, "local_total": { "type": "number", "example": 26.55 }, "local_total_cards_only": { "type": "number", "example": 1.55 }, "payed": { "type": "number", "example": 26.55 }, "used_credit": { "type": "string", "example": "0" }, "note": { "type": "string", "nullable": true } } } } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 400 }, "error": { "type": "string", "description": "error description", "enum": [ "test mode error", "invalid coupon code", "Coupon already used", "Coupon already expired", "credit_card id error", "no such credit card", "[response from Authorize.Net]", "Can't get transaction id with card payment.", "insufficient quantity", "Something went wrong with your payment method. Please refresh the page and try again" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/basket/clear": { "post": { "tags": [ "Basket" ], "summary": "Clear Basket", "description": "Removes all items from the basket. Returns the list of items that were cleared.", "operationId": "basket_clear", "security": [ {}, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "item": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 9517 }, "card_id": { "type": "integer", "example": 89 }, "order_id": { "type": "integer", "example": 44373 }, "is_bulk": { "type": "integer", "enum": [ 0, 1 ] }, "denomination_id": { "type": "integer", "nullable": true }, "message": { "type": "string", "example": "Dear XXX. May your birthday and every day be filled" }, "wishes": { "type": "string", "nullable": true }, "for_free": { "type": "integer", "enum": [ 0, 1 ] }, "price": { "type": "string", "example": "3.75" }, "discount_code": { "type": "string", "nullable": true }, "font": { "type": "string", "example": "hwBlaire" }, "quantity": { "type": "integer", "example": 1 }, "date_to_send": { "type": "string", "nullable": true }, "delivery_cost": { "type": "string", "example": "1.80" }, "shipping_fee": { "type": "string", "example": "0.00" }, "intl_quantity": { "type": "integer", "nullable": true }, "cass_token": { "type": "string", "nullable": true }, "cass_presorted": { "type": "string", "nullable": true }, "cass_invalid_orders_url": { "type": "string", "nullable": true } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/basket/count": { "get": { "tags": [ "Basket" ], "summary": "Basket Item Count", "description": "Get the number of items in the user's basket.", "operationId": "basket_count", "security": [ {}, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "basket items count", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "count": { "type": "integer", "example": 11 } } } } } } } } }, "/cards/list": { "get": { "tags": [ "Cards" ], "summary": "List Cards", "description": "Get a list of all cards available to the user, including any custom or privately-available cards.", "operationId": "cards_list", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "category_id", "in": "query", "description": "Category ID", "required": false, "schema": { "type": "integer" } }, { "name": "with_images", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "with_detailed_images", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "page number, numeration starts with 0", "required": false, "schema": { "type": "integer" } }, { "name": "lowres", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "cards list", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "cards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 36 }, "name": { "type": "string", "example": "Birthday Wishes" }, "description": { "type": "string" }, "cover": { "type": "string" }, "cover_width": { "type": "integer", "example": 355 }, "cover_height": { "type": "integer", "example": 250 }, "inside_image": { "type": "string" }, "price": { "type": "number", "example": 3.7 }, "category_id": { "type": "integer", "example": 7 }, "category_name": { "type": "string", "example": "Birthday" }, "category_taxonomy": { "type": "string", "example": "NONE" }, "available_free": { "type": "boolean" }, "orientation": { "type": "string", "example": "P" }, "characters": { "type": "integer", "example": 340 }, "isCustom": { "type": "boolean" }, "customCardInfo": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "card_id": { "type": "string" }, "cover_id": { "type": "string" }, "logo_id": { "type": "string", "nullable": true }, "header_text": { "type": "string" }, "footer_text": { "type": "string", "nullable": true }, "header_font_size": { "type": "string" }, "footer_font_size": { "type": "string" }, "header_font_id": { "type": "string" }, "footer_font_id": { "type": "string" }, "header_align": { "type": "string" }, "footer_align": { "type": "string" }, "canvas_data": { "type": "string", "nullable": true }, "cover_size_percent": { "type": "string" }, "logo_size_percent": { "type": "string" } } }, "closed_height": { "type": "number", "example": 3.88 }, "closed_width": { "type": "integer", "example": 4 }, "open_height": { "type": "number", "example": 3.88 }, "open_width": { "type": "number", "example": 7.75 }, "margin_top": { "type": "number", "example": 0.25 }, "margin_right": { "type": "number", "example": 0.25 }, "margin_bottom": { "type": "number", "example": 0.25 }, "margin_left": { "type": "number", "example": 0.25 }, "font_size": { "type": "integer", "example": 30 }, "details_size": { "type": "string", "example": "4″ x 3.88″" }, "details_envelope": { "type": "string" }, "details_author": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "is_last": { "type": "boolean", "description": "Whether this is the last page of results." }, "next": { "type": "integer", "nullable": true, "description": "Next page number, or null if this is the last page." }, "per_page": { "type": "integer", "example": 1000, "description": "Number of cards returned per page." } } } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 400 }, "error": { "type": "string", "enum": [ "category id error" ] } } } } } } } } }, "/cards/list/sections": { "get": { "tags": [ "Cards" ], "summary": "List Cards by Categories", "description": "Get a list of cards available to the user, grouped by categories.", "operationId": "cards_listSections", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "category_id", "in": "query", "description": "Category ID", "required": false, "schema": { "type": "integer" } }, { "name": "with_images", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "with_detailed_images", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "page number, numeration starts with 0", "required": false, "schema": { "type": "integer" } }, { "name": "lowres", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "cards sections list", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "cards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 7, "description": "Category id" }, "key": { "type": "string", "example": "Birthday", "description": "Category name" }, "value": { "type": "array", "items": { "type": "object", "description": "Card object (same structure as /cards/list)" } } } } }, "discount": { "type": "integer", "example": 0 } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 400 }, "error": { "type": "string", "enum": [ "category id error" ] } } } } } } } } }, "/cards/view": { "get": { "tags": [ "Cards" ], "summary": "Card Details", "description": "Get detailed information about a card.", "operationId": "cards_view", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "card_id", "in": "query", "description": "Card ID", "required": true, "schema": { "type": "integer" } }, { "name": "lowres", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "detail information about card", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "card": { "type": "object", "properties": { "id": { "type": "integer", "example": 36 }, "name": { "type": "string", "example": "Birthday Wishes" }, "cover": { "type": "string" }, "cover_width": { "type": "integer", "example": 355 }, "cover_height": { "type": "integer", "example": 250 }, "price": { "type": "number", "example": 3.7 }, "category_id": { "type": "integer", "example": 7 }, "category_name": { "type": "string", "example": "Birthday" }, "available_free": { "type": "boolean" }, "orientation": { "type": "string", "example": "P" }, "description": { "type": "string" }, "width": { "type": "integer", "example": 34 }, "height": { "type": "integer", "example": 10 }, "characters": { "type": "integer", "example": 340 }, "closed_height": { "type": "number", "example": 3.88 }, "closed_width": { "type": "integer", "example": 4 }, "open_height": { "type": "number", "example": 3.88 }, "open_width": { "type": "number", "example": 7.75 }, "margin_top": { "type": "number", "example": 0.25 }, "margin_right": { "type": "number", "example": 0.25 }, "margin_bottom": { "type": "number", "example": 0.25 }, "margin_left": { "type": "number", "example": 0.25 }, "font_size": { "type": "integer", "example": 30 }, "details_size": { "type": "string", "example": "4″ x 3.88″" }, "details_envelope": { "type": "string", "nullable": true }, "details_author": { "type": "string", "nullable": true }, "isCustomized": { "type": "boolean" }, "images": { "type": "object", "properties": { "front": { "type": "array", "items": { "type": "object", "properties": { "image": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } }, "inside": { "type": "array", "items": { "type": "object", "properties": { "image": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } }, "envelope": { "type": "array", "items": { "type": "object", "properties": { "image": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } }, "back": { "type": "array", "items": { "type": "object", "properties": { "image": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } } } } } } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 400 }, "error": { "type": "string", "enum": [ "card id error", "no such card" ] } } } } } } } } }, "/cards/uploadCustomLogo": { "post": { "summary": "Upload Custom Image", "description": "Uploads an image for use in a custom card. Use `type: cover` for the card design image printed on the outside, or `type: logo` for a logo placed in the header, footer, or inside of a card. Returns the image ID and URL to use in subsequent custom card calls.", "operationId": "customCards_uploadImage", "security": [ {}, { "ApiKeyAuth": [] } ], "tags": [ "Custom Cards" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "type": { "type": "string", "description": "The type of the image.", "enum": [ "logo", "cover" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "id": { "type": "integer", "example": 614861 }, "image_url": { "type": "string", "example": "https://d3e924qpzqov0g.cloudfront.net/cardimages/customCards/5ce10b5664_cover_e3c221a9bd.jpg" } } } } } } } } }, "/cards/checkUploadedCustomLogo": { "post": { "summary": "Check Image Quality", "description": "Validates the print quality of an uploaded image. Returns a warning if the image resolution is below recommended, or an error if it is too low to use. Call this after uploading a cover image to catch quality issues before creating a card.", "operationId": "customCards_checkImage", "tags": [ "Custom Cards" ], "security": [ {}, { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "image_id" ], "properties": { "image_id": { "type": "integer" }, "card_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "warning": { "type": "string", "example": "This image may appear blurry as it is less than the recommended resolution." }, "error": { "type": "string", "example": "This image is less than recommended resolution. Please upload another image." } } } } } } } } }, "/cards/listCustomUserImages": { "get": { "summary": "List Custom Images", "description": "List all custom images uploaded by the user.", "operationId": "customCards_listImages", "security": [ {}, { "ApiKeyAuth": [] } ], "tags": [ "Custom Cards" ], "parameters": [ { "name": "type", "in": "query", "description": "The type of the image.", "required": false, "schema": { "type": "string", "enum": [ "logo", "cover" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 123456 }, "image_url": { "type": "string", "example": "https://d3e924qpzqov0g.cloudfront.net/cardimages/customCards/example_cover.jpg" }, "thumbnail_url": { "type": "string", "nullable": true }, "user_id": { "type": "integer", "example": 10000 }, "type": { "type": "string", "enum": [ "logo", "cover" ] }, "image": { "type": "string", "example": "customCards/example_cover.jpg" } } } } } } } } } } } }, "/cards/deleteCustomLogo": { "post": { "summary": "Delete Custom Image", "description": "Delete a custom uploaded image.", "operationId": "customCards_deleteImage", "security": [ {}, { "ApiKeyAuth": [] } ], "tags": [ "Custom Cards" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "image_id" ], "properties": { "image_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" } } } } } } } } }, "/design/dimensions": { "get": { "summary": "List Card Dimensions", "description": "Returns available card sizes and formats. Use the `id` (dimension_id) when creating a custom card. The `format` field indicates whether the card is flat (front and back) or folded (four surfaces: front, back, inside top, inside bottom).", "operationId": "customCards_listDimensions", "tags": [ "Custom Cards" ], "security": [ {}, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "nullable": true }, "orientation": { "type": "string", "enum": [ "landscape", "portrait" ], "example": "landscape" }, "open_width": { "type": "string", "example": "7.000" }, "open_height": { "type": "string", "example": "5.000" }, "format": { "type": "string", "enum": [ "flat", "folded" ], "example": "flat" } } } } } } } } } } } }, "/design/presetImages": { "get": { "summary": "List Preset Cover Images", "description": "Returns preset cover images available for a given card dimension. Use `preset_cover_id` or `preset_back_cover_id` in the Create Custom Card call to use one of these instead of a custom uploaded image.", "operationId": "customCards_listPresetImages", "tags": [ "Custom Cards" ], "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dimension_id", "in": "query", "required": true, "description": "Card dimension ID. See /design/dimensions for available options.", "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 50 }, "type": { "type": "string", "enum": [ "front", "back" ], "example": "front" }, "sort_no": { "type": "integer", "example": 0 }, "status": { "type": "integer", "enum": [ 0, 1 ], "example": 1 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-10-17 11:13:09" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-10-17 11:13:09" }, "url": { "type": "string", "example": "https://d3e924qpzqov0g.cloudfront.net/cardimages/preset/example.jpg" } } } } } } } } } } } }, "/cards/createCustomCard": { "post": { "summary": "Create Custom Card", "description": "Creates a custom card using previously uploaded images and configuration. Use `dimension_id` to select the card size and format — see /cards/listDimensions for available options. Flat cards (e.g. dimension_id 1) have a front and back surface. Foldable cards (e.g. dimension_id 3) have four surfaces: front, back, inside top (main), and inside bottom (header/footer).\n\nInstead of a custom uploaded cover, a preset cover can be used via `preset_cover_id` — see /cards/listPresetCovers for available presets.\n\nTo update an existing custom card, pass `is_update: true` along with the existing `card_id`.\n\nThe returned `card_id` can be used in orders like any other card.", "operationId": "customCards_create", "tags": [ "Custom Cards" ], "security": [ {}, { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "card_id": { "type": "integer", "description": "Required when updating an existing custom card (is_update: true). The ID of the card to update.", "example": 305578 }, "name": { "type": "string", "description": "The name of the custom card.", "example": "My Custom Card" }, "dimension_id": { "type": "integer", "description": "Card size and format. See /cards/listDimensions for available options.", "example": 1 }, "is_update": { "type": "boolean", "description": "Set to true to update an existing custom card. Must be combined with card_id.", "example": false }, "cover_id": { "type": "integer", "nullable": true, "description": "ID of the uploaded cover image (type: cover) to use as the front of the card." }, "preset_cover_id": { "type": "integer", "nullable": true, "description": "ID of a preset cover to use instead of a custom uploaded image. See /cards/listPresetCovers." }, "cover_size_percent": { "type": "integer", "example": 84 }, "header_type": { "type": "string", "enum": [ "text", "logo" ], "description": "Whether the header uses text or a logo image. Foldable cards only.", "example": "text" }, "header_text": { "type": "string", "description": "Header text. Used when header_type is 'text'.", "example": "Header text" }, "header_font_size": { "type": "integer", "example": 16 }, "header_font_color": { "type": "string", "description": "Hex color code.", "example": "#000000" }, "header_font_id": { "type": "integer", "description": "Font ID for the header text. See /fonts/listForCustomizer.", "example": 1 }, "header_align": { "type": "string", "enum": [ "left", "center", "right" ], "example": "center" }, "header_logo_id": { "type": "integer", "nullable": true, "description": "ID of the logo image (type: logo) for the header. Used when header_type is 'logo'." }, "header_logo_size_percent": { "type": "integer", "example": 50 }, "footer_type": { "type": "string", "enum": [ "text", "logo" ], "description": "Whether the footer uses text or a logo image.", "example": "text" }, "footer_text": { "type": "string", "description": "Footer text. Used when footer_type is 'text'.", "example": "footer text" }, "footer_font_size": { "type": "integer", "example": 16 }, "footer_font_color": { "type": "string", "description": "Hex color code.", "example": "#000000" }, "footer_font_id": { "type": "integer", "description": "Font ID for the footer text. See /fonts/listForCustomizer.", "example": 1 }, "footer_align": { "type": "string", "enum": [ "left", "center", "right" ], "example": "center" }, "footer_logo_id": { "type": "integer", "nullable": true, "description": "ID of the logo image (type: logo) for the footer. Used when footer_type is 'logo'." }, "footer_logo_size_percent": { "type": "integer", "example": 50 }, "main_type": { "type": "string", "enum": [ "text", "logo" ], "description": "Content type for the inside top surface. Foldable cards only.", "example": "logo" }, "main_text": { "type": "string", "description": "Inside top text. Used when main_type is 'text'." }, "main_font_size": { "type": "integer", "example": 50 }, "main_font_color": { "type": "string", "description": "Hex color code.", "example": "#000000" }, "main_font_id": { "type": "integer", "description": "Font ID for the inside top text. See /fonts/listForCustomizer.", "example": 1 }, "main_align": { "type": "string", "enum": [ "left", "center", "right" ], "example": "left" }, "main_logo_id": { "type": "integer", "nullable": true, "description": "ID of the logo image (type: logo) for the inside top. Used when main_type is 'logo'." }, "main_logo_size_percent": { "type": "integer", "example": 50 }, "back_type": { "type": "string", "enum": [ "text", "logo" ], "description": "Content type for the back surface.", "example": "logo" }, "back_text": { "type": "string", "description": "Back text. Used when back_type is 'text'.", "example": "123" }, "back_font_size": { "type": "integer", "example": 16 }, "back_font_color": { "type": "string", "description": "Hex color code.", "example": "#000000" }, "back_font_id": { "type": "integer", "description": "Font ID for the back text. See /fonts/listForCustomizer.", "example": 1 }, "back_align": { "type": "string", "enum": [ "left", "center", "right" ], "example": "center" }, "back_vertical_align": { "type": "string", "enum": [ "top", "center", "bottom" ], "example": "center" }, "back_logo_id": { "type": "integer", "nullable": true, "description": "ID of the logo image (type: logo) for the back. Used when back_type is 'logo'." }, "back_size_percent": { "type": "integer", "example": 24 }, "back_cover_id": { "type": "integer", "nullable": true, "description": "ID of an uploaded cover image (type: cover) for the back surface." }, "preset_back_cover_id": { "type": "integer", "nullable": true, "description": "ID of a preset cover for the back surface. See /cards/listPresetCovers." }, "qr_code_id": { "type": "integer", "description": "ID of the QR code to include. See /qrCode for available QR codes.", "example": 234 }, "qr_code_size_percent": { "type": "integer", "nullable": true }, "qr_code_align": { "type": "string", "enum": [ "left", "center", "right" ], "example": "left" }, "qr_code_location": { "type": "string", "enum": [ "header", "footer" ], "example": "footer" }, "qr_code_frame_id": { "type": "integer", "nullable": true, "description": "ID of the QR code frame. See /qrCode/frames for available frames." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "card_id": { "type": "integer", "example": 305570 }, "category_id": { "type": "integer", "example": 27, "description": "Always 27 — all custom cards are placed in the user's private Custom Cards category." } } } } } } } } }, "/design/delete": { "post": { "summary": "Delete Custom Card", "description": "Deletes a custom card created by the user.", "operationId": "customCards_delete", "tags": [ "Custom Cards" ], "security": [ {}, { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "description": "ID of the custom card to delete.", "example": 305578 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/categories/list": { "get": { "tags": [ "Cards" ], "summary": "List Categories", "description": "Get list of available card categories.", "operationId": "categories_list", "security": [ {}, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "category list", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 27 }, "name": { "type": "string", "example": "Customizable Cards" }, "checked": { "type": "boolean" }, "taxonomy": { "type": "string", "example": "CUSTOMIZED" }, "icon": { "type": "string", "nullable": true }, "slug": { "type": "string", "example": "custom_cards" }, "meta_title": { "type": "string", "example": "Customizable Cards" }, "meta_description": { "type": "string", "example": "Customizable Cards" } } } } } } } } } } } }, "/countries/list": { "get": { "summary": "List Countries", "description": "Returns the list of all supported countries, including available states/provinces and delivery costs.", "operationId": "countries_list", "tags": [ "Address Book" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "number", "example": 200 }, "status": { "type": "string", "example": "OK" }, "countries": { "type": "array", "description": "list of countries", "items": { "$ref": "#/components/schemas/Country" } } }, "example": { "httpCode": 200, "status": "OK", "countries": [ { "id": 1, "name": "United States", "delivery_cost": 12, "aliases": "US", "states": [ { "id": 1, "short_name": "AK", "name": "Alaska" } ] } ] } } } } } } } }, "/countries/listStates": { "get": { "summary": "List States", "description": "Returns the list of states or provinces for a given country. Only applicable to countries that have states/provinces in the system (currently the United States, Canada, and Mexico).", "operationId": "states_list", "tags": [ "Address Book" ], "parameters": [ { "in": "query", "name": "country_id", "required": true, "description": "Country ID. Use the List Countries endpoint to get available country IDs.", "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "number", "example": 200 }, "status": { "type": "string", "example": "OK" }, "states": { "type": "array", "description": "list of states", "items": { "$ref": "#/components/schemas/State" } } }, "example": { "states": [ { "id": 1, "name": "Alaska", "short_name": "AK" } ] } } } } }, "400": { "description": "INVALID DATA", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 400 ] }, "status": { "type": "string", "example": "error" }, "message": { "type": "string", "enum": [ "country id error" ] } } } } } } } } }, "/fonts/list": { "get": { "tags": [ "Fonts" ], "summary": "List Fonts", "description": "Returns the list of available handwriting styles for use in orders. The `id` field is the font identifier to use in order calls; `label` is the human-readable name. Note: this endpoint returns order fonts only — card customizer fonts are a separate call.", "operationId": "fonts_list", "security": [ {}, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "fonts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "hwJeff" }, "label": { "type": "string", "example": "Proper Jeff" }, "image": { "type": "string", "example": "https://d3e924qpzqov0g.cloudfront.net/fontsImages/5c9084be4292dhwJeff.jpg" }, "path": { "type": "string", "example": "https://d3e924qpzqov0g.cloudfront.net/fonts/5c9084be2c120hwJeff.ttf" }, "last_used": { "type": "string", "example": "hwJeff" }, "line_spacing": { "type": "number", "example": 0.6 } } } } } } } } } } } }, "/giftCards/list": { "get": { "tags": [ "Gift Cards" ], "summary": "List Gift Cards", "description": "Get list of gift cards and available denominations for purchase and inclusion in order.", "operationId": "giftCards_list", "security": [ {}, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Gift Cards List", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "gcards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Target Gift Card" }, "image": { "type": "string", "description": "url", "example": "https://d3e924qpzqov0g.cloudfront.net/cardimages/201411040641_target.png" }, "denominations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "nominal": { "type": "integer", "example": 25 }, "price": { "type": "number", "example": 29.95 } } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/inserts/list": { "get": { "tags": [ "Inserts" ], "summary": "List Inserts", "description": "Get list of custom inserts available for the account.", "operationId": "inserts_list", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "include_historical", "schema": { "type": "boolean" }, "description": "If true, includes inserts that are out of stock." } ], "responses": { "200": { "description": "Inserts list", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "inserts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 3 }, "user_id": { "type": "integer", "example": 10339 }, "name": { "type": "string", "example": "Usual Insert" }, "price": { "type": "number", "example": 1 }, "group_id": { "type": "integer", "nullable": true } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/profile/addRecipient": { "post": { "summary": "Add Recipient Address", "description": "Add a new recipient address to user's Address Book.", "tags": [ "Address Book" ], "operationId": "profile_addRecipient", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string" }, "country_id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "zip": { "type": "string" }, "birthday": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "number", "example": 200 }, "status": { "type": "string", "example": "OK" }, "address_id": { "type": "number", "example": 108926 } } } } } }, "400": { "description": "INVALID DATA", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 400 ] }, "status": { "type": "string", "example": "error" }, "message": { "type": "string", "enum": [ "Error verifying the address.", "The address you have entered cannot be found.", "Error response from shippingapis", "Invalid Zip Code.", "Invalid State.", "Looks like the address you entered is incorrect. Please check Address 2.", "More information is needed (such as an apartment, suite, or box number) to match to a specific address." ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/profile/updateRecipient": { "put": { "summary": "Update Recipient Address", "description": "Update a recipient address in Address Book.", "tags": [ "Address Book" ], "operationId": "profile_updateRecipient", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address_id": { "type": "string", "description": "ID of the address in the address book. You can get it using `List Recipient Addresses` call." }, "state": { "type": "string" }, "country_id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string" }, "business_name": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "zip": { "type": "string" }, "birthday": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "number", "example": 200 }, "status": { "type": "string", "example": "OK" }, "address_id": { "type": "number", "example": 108926 } } } } } }, "400": { "description": "INVALID DATA", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 400 ] }, "status": { "type": "string", "example": "error" }, "message": { "type": "string", "enum": [ "Error verifying the address.", "The address you have entered cannot be found.", "Error response from shippingapis", "Invalid Zip Code.", "Invalid State.", "Looks like the address you entered is incorrect. Please check Address 2.", "More information is needed (such as an apartment, suite, or box number) to match to a specific address." ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/profile/deleteRecipient": { "post": { "summary": "Delete Recipient Address", "tags": [ "Address Book" ], "operationId": "profile_deleteRecipient", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address_id": { "type": "number" }, "address_ids": { "type": "array", "items": { "type": "integer" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "number", "example": 200 }, "status": { "type": "string", "example": "OK" }, "address_id": { "type": "number", "example": 108926 }, "address_ids": { "type": "array", "items": { "type": "integer" } } } } } } }, "400": { "description": "INVALID DATA", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 400 ] }, "status": { "type": "string", "example": "error" }, "message": { "type": "string", "enum": [ "Address id error", "no such address." ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/profile/recipientsList": { "get": { "summary": "List Recipient Addresses", "description": "Get list of recipient addresses in user's Address Book.", "tags": [ "Address Book" ], "operationId": "profile_recipientsList", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "number", "example": 200 }, "status": { "type": "string", "example": "OK" }, "addresses": { "type": "array", "description": "recipients addresses list", "items": { "$ref": "#/components/schemas/Address" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/profile/createAddress": { "post": { "summary": "Add Sender Address", "description": "Add a new sender address to user's Address Book.", "tags": [ "Address Book" ], "operationId": "profile_createAddress", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "default": { "type": "boolean" }, "name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "business_name": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "number", "example": 200 }, "status": { "type": "string", "example": "OK" }, "address": { "$ref": "#/components/schemas/Address" } } } } } }, "400": { "description": "INVALID DATA", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 400 ] }, "status": { "type": "string", "example": "error" }, "message": { "type": "string", "enum": [ "Error verifying the address.", "The address you have entered cannot be found.", "Error response from shippingapis", "Invalid Zip Code.", "Invalid State.", "Looks like the address you entered is incorrect. Please check Address 2.", "More information is needed (such as an apartment, suite, or box number) to match to a specific address." ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/profile/updateAddress": { "put": { "summary": "Update Sender Address", "description": "Update a sender address in user's Address Book.", "tags": [ "Address Book" ], "operationId": "profile_updateAddress", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "zip": { "type": "string" }, "state": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "number", "example": 200 }, "status": { "type": "string", "example": "OK" }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "country_obj": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "delivery_cost": { "type": "integer" } } } } } } } } } } }, "400": { "description": "INVALID DATA", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 400 ] }, "status": { "type": "string", "example": "error" }, "message": { "type": "string", "enum": [ "Error verifying the address.", "The address you have entered cannot be found.", "Error response from shippingapis", "Invalid Zip Code.", "Invalid State.", "Looks like the address you entered is incorrect. Please check Address 2.", "More information is needed (such as an apartment, suite, or box number) to match to a specific address." ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/profile/deleteAddress": { "post": { "summary": "Delete Sender Address", "description": "Delete a sender address from user's Address Book.", "tags": [ "Address Book" ], "operationId": "profile_deleteAddress", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "address_ids": { "type": "array", "items": { "type": "integer" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "number", "example": 200 }, "status": { "type": "string", "example": "OK" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/profile/listAddresses": { "get": { "summary": "List Sender Addresses", "tags": [ "Address Book" ], "operationId": "profile_listAddresses", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "number", "example": 200 }, "status": { "type": "string", "example": "OK" }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/profile/address": { "get": { "tags": [ "Address Book" ], "summary": "Default Sender Address Info", "description": "Get user's default sender address.", "operationId": "profile_address", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "number", "example": 200 }, "status": { "type": "string", "example": "OK" }, "billing_info": { "type": "object", "properties": { "address": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" }, "country_id": { "type": "integer" } } }, "subscription": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "delivery_cost": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/profile/setDefaultAddress": { "post": { "summary": "Set Default Sender Address", "description": "Set user's default sender address.", "tags": [ "Address Book" ], "operationId": "profile_setDefaultAddress", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "number", "example": 200 }, "status": { "type": "string", "example": "OK" } } } } } }, "400": { "description": "INVALID DATA", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 400 ] }, "status": { "type": "string", "example": "error" }, "message": { "type": "string", "enum": [ "bad id." ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/profile/signatures": { "get": { "summary": "List Signatures", "description": "Returns the list of signatures available to the user. Signature IDs can be used in order calls to include a signature in the message or wishes fields.", "tags": [ "Signatures" ], "operationId": "signatures_list", "security": [ {}, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "number", "example": 200 }, "status": { "type": "string", "example": "OK" }, "signatures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "preview": { "type": "string", "description": "img url" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/qrCode": { "get": { "summary": "List QR Codes", "description": "Get a list of QR Codes on the account.", "operationId": "qrCodes_list", "tags": [ "QR Codes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "name": { "type": "string", "example": "QR Code Name" }, "url": { "type": "string", "example": "https://d3e924qpzqov0g.cloudfront.net/qrCodes/3aeb3d94-310e-4dec-abaf-98ec281eef88_qr_code.png" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "summary": "Create QR Code", "description": "Create a new QR Code.", "operationId": "createQrCode", "tags": [ "QR Codes" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "QR Code Name" }, "url": { "type": "string", "example": "https://www.handwrytten.com" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "id": { "type": "integer", "example": 123 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/qrCode/{id}": { "delete": { "summary": "Delete QR Code", "description": "Delete a QR Code.", "operationId": "deleteQrCode", "tags": [ "QR Codes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/qrCode/dashboard": { "get": { "summary": "QR Code Statistics", "description": "Get the statistics for the QR Codes on the account.", "operationId": "getDashboard", "tags": [ "QR Codes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "scans": { "type": "array", "items": { "$ref": "#/components/schemas/Scan" } }, "recent_scans": { "type": "array", "items": { "$ref": "#/components/schemas/Scan" } }, "statistics": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "example": "2021-12-31" }, "quantity": { "type": "integer", "example": 123 }, "formatted_date": { "type": "string", "example": "May 17" } } } }, "total_links": { "type": "integer", "example": 123 }, "total_scans": { "type": "integer", "example": 123 }, "total_unique_scans": { "type": "integer", "example": 123 }, "total_pending_scans": { "type": "integer", "example": 123 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/qrCode/frames": { "get": { "summary": "List QR Code Frames", "description": "Get a list of available QR Code frames.", "operationId": "qrCodes_listFrames", "security": [ {}, { "ApiKeyAuth": [] } ], "tags": [ "QR Codes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "example": 200 }, "status": { "type": "string", "example": "ok" }, "frames": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 7 }, "type": { "type": "string", "example": "header" }, "user_group_id": { "type": "integer", "example": 1 }, "url": { "type": "string", "example": "https://d3e924qpzqov0g.cloudfront.net/frames/1716381805559_frame.png" }, "position_x": { "type": "string", "example": "50.00" }, "position_y": { "type": "string", "example": "80.00" }, "qr_code_size": { "type": "string", "example": "68.00" }, "aspect_ratio": { "type": "string", "example": "1.2214" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/outbound/calcTargets": { "post": { "summary": "Calculate Targets", "description": "Calculate targets for prospecting campaign.", "operationId": "outbound_calctargets", "tags": [ "Prospecting" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "Outbound prospecting type: residential or business.", "enum": [ "residential", "business" ], "example": "residential" }, "address": { "type": "string", "description": "Street address to serve as a central point for prospecting search.", "example": "9280 South Kyrene Road" }, "city": { "type": "string", "description": "Format: `STATE;City`", "example": "AZ;Tempe" }, "zip": { "type": "string", "description": "Postal code", "example": "85284" }, "country": { "type": "string", "description": "`United States` or `Canada`", "example": "United States" }, "radius": { "type": "integer", "description": "Search radius in miles from the central point.", "example": 5 }, "latitude": { "type": "string", "description": "Latitude to serve as a central point for prospecting search. If not using latitude and longitude, set them to `1`. We use them for a secondary search if nothing was found at the address.", "example": "1" }, "longitude": { "type": "string", "description": "Longitude to serve as a central point for prospecting search. If not using latitude and longitude, set them to `1`. We use them for a secondary search if nothing was found at the address.", "example": "1" }, "ownRent-d": { "type": "string", "description": "Home ownership for residential search.\n\n- `1`: Home owner\n- `2`: Renter\n\nIf you want to use multiple values, use dash to separate them, for example: `\"ownRent-d\": \"1-2\"`", "example": "" }, "hinc-d": { "type": "string", "description": "Household income for residential search.\n\n- `1`: Less than $14,999\n- `2`: $15,000 - $19,999\n- `3`: $20,000 - $29,999\n- `4`: $30,000 - $39,999\n- `5`: $40,000 - $49,999\n- `6`: $50,000 - $74,999\n- `7`: $75,000 - $99,999\n- `8`: $100,000 - $124,999\n- `9`: $125,000 - $149,999\n- `10`: $150,000 - $174,999\n- `11`: $175,000 - $199,999\n- `12`: $200,000 - $249,999\n- `13`: $250,000 or more\n\nIf you want to use multiple values, use dash to separate them, for example: `\"hinc-d\": \"2-3-4-5-6\"`", "example": "" }, "worth-d": { "type": "string", "description": "Net worth for residential search.\n\n- `1`: Less than $25,000\n- `2`: $25,000 - $49,999\n- `3`: $50,000 - $74,999\n- `4`: $75,000 - $99,999\n- `5`: $100,000 - $149,999\n- `6`: $150,000 - $249,999\n- `7`: $250,000 - $499,999\n- `8`: $500,000 - $749,999\n- `9`: $750,000 - $999,999\n- `10`: $1,000,000 or more\n\nIf you want to use multiple values, use dash to separate them, for example: `\"worth-d\": \"6-8-9\"`", "example": "" }, "Home-d": { "type": "string", "description": "Home value for residential search.\n\n- `1`: $1 - $49,999\n- `2`: $50,000 - $99,999\n- `3`: $100,000 - $149,999\n- `4`: $150,000 - $199,999\n- `5`: $200,000 - $249,999\n- `6`: $250,000 - $299,999\n- `7`: $300,000 - $349,999\n- `8`: $350,000 - $399,999\n- `9`: $400,000 - $449,999\n- `10`: $450,000 - $499,999\n- `11`: $500,000 - $574,999\n- `12`: $575,000 - $649,999\n- `13`: $650,000 - $724,999\n- `14`: $725,000 - $799,999\n- `15`: $800,000 - $899,999\n- `16`: $900,000 - $999,999\n- `17`: $1,000,000 - $1,999,999\n- `18`: $2,000,000 or More\n\nIf you want to use multiple values, use dash to separate them, for example: `\"Home-d\": \"3-4-5-8-9\"`", "example": "" }, "resLen-d": { "type": "string", "description": "Length of residency for residential search.\n\n- `1`: 0-6 months\n- `2`: 7-12 months\n- `3`: 1-2 years\n- `4`: 3-5 years\n- `5`: 6-10 years\n- `6`: 11-15 years\n- `7`: 16-20 years\n- `8`: 20+ years\n\nIf you want to use multiple values, use dash to separate them, for example: `\"resLen-d\": \"1-3-4-5-8\"`", "example": "" }, "hAge": { "type": "string", "description": "Household age for residential search.\n\n- `1`: 18-24 years old\n- `2`: 25-34 years old\n- `3`: 35-44 years old\n- `4`: 45-54 years old\n- `5`: 55-64 years old\n- `6`: 65-74 years old\n- `7`: 75+ years old\n\nIf you want to use multiple values, use dash to separate them, for example: `\"hAge-d\": \"1-3-4-5\"`", "example": "" }, "people": { "type": "string", "description": "People in household for residential search.\n\n- `1`: 1 person\n- `2`: 2 persons\n- `3`: 3 persons\n- `4`: 4 persons\n- `5`: 5 persons\n- `6`: 6 persons\n- `7`: 7 persons\n- `8`: 8 persons\n- `9`: 9+ persons\n\nIf you want to use multiple values, use dash to separate them, for example: `\"people-d\": \"4-5\"`", "example": "" }, "kids": { "type": "string", "description": "Children in household for residential search.\n\n- `1`: 1 child\n- `2`: 2 children\n- `3`: 3 children\n- `4`: 4 children\n- `5`: 5 children\n- `6`: 6 Children\n- `7`: 7 children\n- `8`: 8 children\n- `9`: 9+ children\n\nIf you want to use multiple values, use dash to separate them, for example: `\"kids-d\": \"4-7-8-5\"`", "example": "" }, "marital": { "type": "string", "description": "Marital status for residential search.\n\n- `1`: Unknown\n- `2`: Household contains at least 1 married person\n- `3`: Household contains at least 1 single person\n- `4`: Household contains both married & single persons\n\nIf you want to use multiple values, use dash to separate them, for example: `\"marital-d\": \"1-2\"`", "example": "" }, "staff": { "type": "string", "description": "Staff size for business search.\n\n- `1`: 1 - 4\n- `2`: 5 - 9\n- `3`: 10 - 19\n- `4`: 20 - 49\n- `5`: 50 - 99\n- `6`: 100 - 249\n- `7`: 250 - 499\n- `8`: 500 - 999\n- `9`: 1,000 - 4,999\n- `10`: 5,000 - 9,999\n- `11`: 10,000 +\n\nIf you want to use multiple values, use dash to separate them, for example: `\"staff-d\": \"2-6-8\"`", "example": "" }, "sale": { "type": "string", "description": "Annual sales volume for business search.\n\n- `1`: $1,000 - $499,999\n- `2`: $500,000 - $999,999\n- `3`: $1,000,000 - $2,499,999\n- `4`: $2,500,000 - $4,999,999\n- `5`: $5,000,000 - $9,999,999\n- `6`: $10,000,000 - $19,999,999\n- `7`: $20,000,000 - $49,999,999\n- `8`: $50,000,000 - $99,999,999\n- `9`: $100,000,000 - $499,999,999\n- `10`: $500,000,000 - $999,999,999\n- `11`: Over $1 billion\n\nIf you want to use multiple values, use dash to separate them, for example: `\"sale-d\": \"6-7-8\"`", "example": "" }, "one": { "type": "string", "description": "Return all or one contact per business.\n\n- `0`: Return all contacts\n- `1`: Return one contact.", "enum": [ "0", "1" ], "example": "" }, "sic": { "type": "string", "description": "Industry code for business search. Use dash to separate multiple codes, for example: `\"sic\": \"17-9999-729924\"`", "example": "" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 200 ] }, "status": { "type": "string", "enum": [ "ok" ] }, "total_records": { "type": "string", "description": "Number of addresses found" }, "mask": { "type": "boolean", "enum": [ true, false ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "440": { "description": "Login Timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 440 ] }, "status": { "type": "string", "enum": [ "error" ] }, "message": { "type": "string", "description": "Error message", "enum": [ "Session has been expired." ] } } } } } } } } }, "/outbound/process": { "post": { "summary": "Preview Order", "description": "Preview prospecting campaign order pricing.", "operationId": "outbound_process", "tags": [ "Prospecting" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "card_id", "country", "message", "records", "return_address_id" ], "properties": { "card_id": { "type": "integer", "description": "ID of card", "example": 60559 }, "country": { "type": "string", "description": "`United States` or `Canada`", "example": "United States" }, "insert_id": { "type": "integer", "description": "ID of the insert", "example": null }, "message": { "type": "string", "description": "Handwrytten message on the card", "example": "" }, "must_deliver_by": { "type": "string", "description": "Format: `MM/DD/YYYY`", "example": "" }, "records": { "type": "integer", "description": "Number of cards to send", "example": 5 }, "return_address_id": { "type": "integer", "description": "ID of the return address", "example": null }, "shipping_address_id": { "type": "integer", "description": "ID of the shipping address", "example": null }, "shipping_method_id": { "type": "integer", "description": "Shipping method.\n\n- `1`: Mail Normally\n- `2`: Ship: Address, Seal, Stamp\n- `3`: Ship: Cards Only (no envelope)\n- `4`: Ship: Cards Only (blank envelope unsealed)\n- `5`: Ship: Addressed & Unsealed\n- `6`: Ship: Addressed & Sealed", "enum": [ 1, 2, 3, 4, 5, 6 ], "example": 1 }, "shipping_rate_id": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Shipping rate.\n\n- `1`: Ground\n- `2`: 2-Day\n- `3`: Overnight\n- `4`: Overnight Priority", "example": null } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 200 ] }, "status": { "type": "string", "enum": [ "ok" ] }, "prices": { "type": "object", "properties": { "tax": { "type": "number", "description": "Taxes" }, "card_price": { "type": "number", "description": "Total cards cost" }, "postage_price": { "type": "number", "description": "Postage cost" }, "insert_price": { "type": "number", "description": "Inserts cost" }, "shipping_price": { "type": "number", "description": "Shipping cost" }, "without_tax": { "type": "number", "description": "Total order cost" }, "total": { "type": "number", "description": "Total order cost with taxes" } } }, "quantity": { "type": "integer", "description": "Number of cards" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "440": { "$ref": "#/components/responses/440" } } } }, "/outbound/addToBasket": { "post": { "summary": "Create Order", "description": "Add prospecting campaign order to basket. Use `Send Basket` call to submit all orders in basket for processing.", "operationId": "outbound_addtobasket", "tags": [ "Prospecting" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "card_id", "message", "records", "return_address_id", "font" ], "properties": { "address": { "type": "string", "description": "Street address to serve as a central point for prospecting search.", "example": "9280 South Kyrene Road" }, "city": { "type": "string", "description": "Format: `STATE;City`", "example": "AZ;Tempe" }, "zip": { "type": "string", "description": "Postal code", "example": "85284" }, "country": { "type": "string", "description": "`United States` or `Canada`", "example": "United States" }, "radius": { "type": "integer", "description": "Search radius in miles from the central point.", "example": 5 }, "latitude": { "type": "string", "description": "Latitude to serve as a central point for prospecting search. If not using latitude and longitude, set them to `1`. We use them for a secondary search if nothing was found at the address.", "example": "1" }, "longitude": { "type": "string", "description": "Longitude to serve as a central point for prospecting search. If not using latitude and longitude, set them to `1`. We use them for a secondary search if nothing was found at the address.", "example": "1" }, "mask": { "type": "boolean", "description": "If no data was found at the address, try searching by geodata" }, "ownRent-d": { "type": "string", "description": "Home ownership for residential search. Use dash to separate multiple values.", "example": "" }, "hinc-d": { "type": "string", "description": "Household income for residential search. Use dash to separate multiple values.", "example": "" }, "worth-d": { "type": "string", "description": "Net worth for residential search. Use dash to separate multiple values.", "example": "" }, "Home-d": { "type": "string", "description": "Home value for residential search. Use dash to separate multiple values.", "example": "" }, "resLen-d": { "type": "string", "description": "Length of residency for residential search. Use dash to separate multiple values.", "example": "" }, "hAge": { "type": "string", "description": "Household age for residential search. Use dash to separate multiple values.", "example": "" }, "people": { "type": "string", "description": "People in household for residential search. Use dash to separate multiple values.", "example": "" }, "kids": { "type": "string", "description": "Children in household for residential search. Use dash to separate multiple values.", "example": "" }, "marital": { "type": "string", "description": "Marital status for residential search. Use dash to separate multiple values.", "example": "" }, "card_id": { "type": "integer", "description": "ID of card", "example": 60559 }, "insert_id": { "type": "integer", "description": "ID of the insert", "example": null }, "message": { "type": "string", "description": "Handwrytten message on the card", "example": "Hi {{firstname}},\n\nWelcome to the neighborhood!" }, "wishes": { "type": "string", "description": "Handwrytten signoff on the card", "example": "Best wishes,\nYour friendly realtor" }, "signature_id": { "type": "integer", "description": "ID of the custom signature", "example": null }, "signature2_id": { "type": "integer", "description": "ID of the custom signature #2", "example": null }, "search_value": { "type": "string", "description": "Search value" }, "must_deliver_by": { "type": "string", "description": "Format: `MM/DD/YYYY`", "example": "" }, "records": { "type": "integer", "description": "Number of cards to send", "example": 5 }, "return_address_id": { "type": "integer", "description": "ID of the return address", "example": null }, "shipping_address_id": { "type": "integer", "description": "ID of the shipping address", "example": null }, "shipping_method_id": { "type": "integer", "description": "Shipping method.\n\n- `1`: Mail Normally\n- `2`: Ship: Address, Seal, Stamp\n- `3`: Ship: Cards Only (no envelope)\n- `4`: Ship: Cards Only (blank envelope unsealed)\n- `5`: Ship: Addressed & Unsealed\n- `6`: Ship: Addressed & Sealed", "enum": [ 1, 2, 3, 4, 5, 6 ], "example": 1 }, "shipping_rate_id": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Shipping rate.\n\n- `1`: Ground\n- `2`: 2-Day\n- `3`: Overnight\n- `4`: Overnight Priority", "example": null }, "font": { "type": "string", "description": "Handwriting font slug", "example": "hwBlaire" }, "font_size": { "type": "integer", "description": "Font size", "example": null } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 200 ] }, "status": { "type": "string", "enum": [ "ok" ] }, "order_id": { "type": "integer", "description": "ID of order in basket" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "440": { "$ref": "#/components/responses/440" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "name": "Authorization", "in": "header" }, "uidKey": { "type": "apiKey", "name": "Authorization", "in": "header" } }, "schemas": { "Address": { "type": "object", "description": "An address", "properties": { "id": { "type": "integer", "format": "int32", "minimum": 0 }, "type": { "type": "string", "enum": [ "user_from", "user_to", "order_from", "order_to" ] }, "user_id": { "type": "integer" }, "order_id": { "type": "integer" }, "name": { "type": "string" }, "business_name": { "type": "string" }, "address1": { "type": "string", "format": "address" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "integer" }, "date_created": { "type": "string", "format": "date-time" }, "date_updated": { "type": "string", "format": "date-time" }, "basket_id": { "type": "integer" }, "country": { "type": "string" }, "delivery_cost": { "type": "number", "format": "float" }, "country_id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "birthday": { "type": "string", "format": "date" }, "anniversary": { "type": "string", "format": "date" }, "address_id": { "type": "integer" }, "ext_id": { "type": "integer" }, "country_obj": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "delivery_cost": { "type": "number" } } } }, "example": { "id": 123, "type": "user_from", "user_id": 12345, "order_id": null, "name": "John Smith", "business_name": "Handwrytten", "address1": "9280 S. Kyrene Rd.", "address2": "Suite", "city": "Tempe", "state": "AZ", "zip": 85284, "date_created": "2023-01-01T01:02:03.000Z", "date_updated": null, "basket_id": null, "country": "United States", "delivery_cost": 0.63, "country_id": 1, "first_name": "John", "last_name": "Smith", "birthday": null, "anniversary": null, "address_id": null, "ext_id": null, "country_obj": { "id": 1, "name": "United States", "delivery_cost": 0.63 } } }, "Country": { "type": "object", "properties": { "id": { "type": "string", "example": "1" }, "name": { "type": "string", "example": "United States" }, "delivery_cost": { "type": "string", "example": "0.63" }, "aliases": { "type": "string", "example": "USA United States of America" }, "states": { "$ref": "#/components/schemas/State" } } }, "State": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Alaska" }, "short_name": { "type": "string", "example": "AK" } } }, "FontInfo": { "type": "object", "properties": { "id": { "type": "string", "example": "hwJenna" }, "label": { "type": "string", "example": "Fancy Jenna" } } }, "FontInfoVerbose": { "type": "object", "properties": { "id": { "type": "string", "example": "astDunn" }, "label": { "type": "string", "example": "Casual David" }, "font_file": { "type": "string", "example": "https://d3e924qpzqov0g.cloudfront.net/fonts/568f998821ed25667bcbe3f1b6astDunn.ttf" }, "image": { "type": "string", "example": "https://d3e924qpzqov0g.cloudfront.net/fontsImages/568f99883e6845667bcbe3f297casualdavid.jpg" }, "sort": { "type": "string", "example": "0" }, "on_custom": { "type": "string", "example": "0" }, "font_eot_file": { "type": "string", "nullable": true }, "font_name": { "type": "string", "example": "astDunn" }, "visible": { "type": "string", "example": "1" }, "user_group_id": { "type": "string", "nullable": true } } }, "GiftCard": { "type": "object", "properties": { "id": { "type": "string", "example": "10" }, "image": { "type": "string", "example": "https://d3e924qpzqov0g.cloudfront.net/cardimages/201412220728_FootLocker25.png" }, "name": { "type": "string", "example": "Foot Locker Gift Card" } } }, "Denomination": { "type": "object", "properties": { "id": { "type": "string", "example": "13" }, "nominal": { "type": "string", "example": "25" }, "price": { "type": "string", "example": "25" } } }, "Signature": { "type": "object", "properties": { "id": { "type": "integer", "example": 128 }, "name": { "type": "string", "example": "My Signature", "nullable": true }, "code": { "type": "string", "example": "" }, "preview": { "type": "string", "example": "https://d3e924qpzqov0g.cloudfront.net/signatures/example.png" } } }, "Template": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "example": 17 }, "category_id": { "type": "integer", "format": "int64", "example": 1 }, "name": { "type": "string", "example": "Thank You Gift - Missed Attendance" }, "message": { "type": "string", "example": "Dear XXX Thank you so much for the generous gift. Both XXX and I are sure to use it for years to come. We are so sorry you weren't able to join us for our special day but we appreciate your thoughtfulness and generosity. We hope to celebrate with you soon. All the best XXXX" }, "wishes": { "type": "string", "nullable": true, "example": "best rigardz" }, "signature": { "$ref": "#/components/schemas/Signature", "description": "signature in wishes", "nullable": true }, "signature2": { "$ref": "#/components/schemas/Signature", "description": "signature in message", "nullable": true } } }, "Scan": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "ip_address": { "type": "string", "example": "8.8.8.8" }, "geolocation": { "type": "object", "properties": { "city": { "type": "string", "example": "Mountain View" }, "country": { "type": "object", "properties": { "name": { "type": "string", "example": "United States" }, "iso_code": { "type": "string", "example": "US" } } }, "location": { "type": "object", "properties": { "latitude": { "type": "string", "example": "37.3860517" }, "longitude": { "type": "string", "example": "-122.0838511" }, "time_zone": { "type": "string", "example": "America/Los_Angeles" } } }, "postal_code": { "type": "string", "example": "94043" }, "subdivision": { "type": "object", "properties": { "name": { "type": "string", "example": "California" }, "iso_code": { "type": "string", "example": "CA" } } }, "organization": { "type": "string", "example": "Google LLC" } } }, "datetime": { "type": "string", "example": "2021-12-31" }, "from_name": { "type": "string", "example": "John Doe" }, "to_name": { "type": "string", "example": "Jane Doe" }, "url": { "type": "string", "example": "https://www.handwrytten.com" }, "card_id": { "type": "string", "example": "123" }, "card_name": { "type": "string", "example": "Happy Birthday" } } }, "Standard": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "../schemas/Common.json#/OK" } } } }, "Unauthorized": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "BadRequest": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "BadRequestError": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 400 ] }, "status": { "type": "string", "enum": [ "error" ] }, "message": { "type": "string" } }, "example": { "httpCode": 400, "status": "error", "message": "Invalid request" } }, "UnauthorizedError": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 401 ], "description": "Http status code" }, "status": { "type": "string", "enum": [ "error" ] }, "message": { "type": "string" } }, "example": { "httpCode": 401, "status": "error", "message": "no auth" } } }, "responses": { "440": { "description": "Login Timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "httpCode": { "type": "integer", "enum": [ 440 ] }, "status": { "type": "string", "enum": [ "error" ] }, "message": { "type": "string", "description": "Error message", "enum": [ "Session has been expired." ] } } } } } }, "BadRequest": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "Unauthorized": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } } } } }