The Handwrytten connector lets your AI agent act in each user's Handwrytten account. Each user connects their own Handwrytten API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 47 tools.
- Tools
- 47
- What they doRead · write · destructive
- 28 · 12 · 728 read12 write7 destructive
- Users sign in with
- API key
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Handwrytten connection
In AgentKit > Connections, create a Handwrytten connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'handwrytten'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Handwrytten:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'handwrytten_auth_check',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "handwrytten"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Handwrytten:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="handwrytten_auth_check",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Handwrytten credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolhandwrytten_auth_checkCheck that the API key is valid.Read-onlyCheck Authentication
Check that the API key is valid. Returns the authentication status. Use it as a connection test; use handwrytten_user_get for account details.
Inputs
This tool takes no inputs.
handwrytten_basket_count_getCount the orders currently in the basket.Read-onlyGet Basket Count
Count the orders currently in the basket. Returns the count. Use it before handwrytten_basket_send.
Inputs
This tool takes no inputs.
handwrytten_bundles_listList the bundles (packages shipped with orders) available to the account.Read-onlyList Bundles
List the bundles (packages shipped with orders) available to the account. Returns bundle IDs and contents. Pass an ID as bundle_id when ordering.
Inputs
This tool takes no inputs.
handwrytten_card_dimensions_listList the card sizes and formats (flat or folded) for custom cards.Read-onlyList Card Dimensions
List the card sizes and formats (flat or folded) for custom cards. Returns dimension IDs and sizes. Pass an ID as dimension_id to handwrytten_custom_card_create and handwrytten_preset_covers_list.
Inputs
This tool takes no inputs.
handwrytten_card_getGet one card by ID with its description, price, dimensions and images.Read-onlyGet Card
Get one card by ID with its description, price, dimensions and images. Returns the card object. Get card IDs from handwrytten_cards_list.
Inputs
card_idintegerrequired- ID of the card (stationery design) to use. Get card IDs from handwrytten_cards_list. Example: 3404.
lowresboolean- true returns low-resolution image URLs, which load faster. Example: true.
handwrytten_cards_by_category_listList the available cards grouped into category sections.Read-onlyList Cards by Category
List the available cards grouped into category sections. Returns sections, each with its cards. Use handwrytten_cards_list for a flat list.
Inputs
category_idinteger- Only return cards in this category. Get category IDs from handwrytten_categories_list. Example: 27.
lowresboolean- true returns low-resolution image URLs, which load faster. Example: true.
pageinteger- Page number of results, starting at 0. Example: 0.
with_detailed_imagesboolean- true includes the detailed (all sides) card image URLs in the response. Example: true.
with_imagesboolean- true includes card image URLs in the response. Example: true.
handwrytten_cards_listList the cards (stationery designs) available to the account, including custom cards, optionally for one category.Read-onlyList Cards
List the cards (stationery designs) available to the account, including custom cards, optionally for one category. Returns card IDs, names, prices and image URLs. Use handwrytten_cards_by_category_list for cards grouped by category and handwrytten_card_get for one card.
Inputs
category_idinteger- Only return cards in this category. Get category IDs from handwrytten_categories_list. Example: 27.
lowresboolean- true returns low-resolution image URLs, which load faster. Example: true.
pageinteger- Page number of results, starting at 0. Example: 0.
with_detailed_imagesboolean- true includes the detailed (all sides) card image URLs in the response. Example: true.
with_imagesboolean- true includes card image URLs in the response. Example: true.
handwrytten_categories_listList the card categories (for example Thank You, Birthday, Holiday).Read-onlyList Card Categories
List the card categories (for example Thank You, Birthday, Holiday). Returns category IDs and names. Use the IDs to filter handwrytten_cards_list.
Inputs
This tool takes no inputs.
handwrytten_countries_listList the countries cards can be sent to.Read-onlyList Countries
List the countries cards can be sent to. Returns country IDs and names. Use the IDs as country_id in address tools and handwrytten_states_list.
Inputs
This tool takes no inputs.
handwrytten_custom_image_quality_checkCheck whether an uploaded image is sharp enough to print, optionally on a given card.Read-onlyCheck Custom Image Quality
Check whether an uploaded image is sharp enough to print, optionally on a given card. Returns the quality verdict. Get image IDs from handwrytten_custom_images_list.
Inputs
image_idintegerrequired- ID of an uploaded custom image. Get IDs from handwrytten_custom_images_list. Example: 4410.
card_idinteger- ID of the card (stationery design) to use. Get card IDs from handwrytten_cards_list. Example: 3404.
handwrytten_custom_images_listList the logo and cover images uploaded to the account, optionally only one type.Read-onlyList Custom Images
List the logo and cover images uploaded to the account, optionally only one type. Returns image IDs and URLs. Use the IDs with handwrytten_custom_card_create; images are uploaded in the Handwrytten app.
Inputs
typestring- Kind of record: for images, logo or cover; for prospecting, residential or business. Example: logo.one of
logocover
handwrytten_default_sender_address_getGet the account's default sender (return) address.Read-onlyGet Default Sender Address
Get the account's default sender (return) address. Returns the address object. Use handwrytten_sender_addresses_list for all of them.
Inputs
This tool takes no inputs.
handwrytten_fonts_listList the handwriting styles available for messages.Read-onlyList Fonts
List the handwriting styles available for messages. Returns each font's ID, label and preview. Pass the label to handwrytten_order_single_step_create (font_label) or the ID to handwrytten_basket_order_add (font).
Inputs
This tool takes no inputs.
handwrytten_gift_cards_listList the gift cards that can be enclosed with a card.Read-onlyList Gift Cards
List the gift cards that can be enclosed with a card. Returns gift cards with their denomination IDs and amounts. Pass a denomination ID as denomination_id when ordering.
Inputs
This tool takes no inputs.
handwrytten_inserts_listList the custom inserts (printed material enclosed with cards) on the account.Read-onlyList Inserts
List the custom inserts (printed material enclosed with cards) on the account. Returns insert IDs, names and stock. Pass an ID as insert_id when ordering.
Inputs
include_historicalboolean- If true, includes inserts that are out of stock. Example: true.
handwrytten_order_getGet one order by ID with its card, message, recipient, status and price.Read-onlyGet Order
Get one order by ID with its card, message, recipient, status and price. Returns the order object. Use it to track an order created with handwrytten_order_single_step_create or the basket tools.
Inputs
order_idintegerrequired- ID of the order to get. Example: 305578.
handwrytten_preset_covers_listList the preset cover images for a card dimension.Read-onlyList Preset Covers
List the preset cover images for a card dimension. Returns preset cover IDs and image URLs. Use an ID as preset_cover_id in handwrytten_custom_card_create.
Inputs
dimension_idintegerrequired- Card dimension ID. See /design/dimensions for available options. Example: 1.
handwrytten_prospecting_order_previewPrice a prospecting campaign: a card and message sent to a number of prospects.Read-onlyPreview Prospecting Order
Price a prospecting campaign: a card and message sent to a number of prospects. Returns the price breakdown without placing an order. Use handwrytten_prospecting_order_add to add the campaign to the basket.
Inputs
card_idintegerrequired- ID of the card (stationery design) to use. Get card IDs from handwrytten_cards_list. Example: 3404.
countrystringrequired- Country for prospecting: United States or Canada. Example: United States.
messagestringrequired- The handwritten message text. Use \n for new lines. Example: Dear Frank,\nThank you so much for your business.
recordsintegerrequired- Number of prospects (cards) to send. Example: 5.
return_address_idintegerrequired- ID of the sender (return) address. Get IDs from handwrytten_sender_addresses_list. Example: 88123.
insert_idinteger- ID of a custom insert to enclose with the card. Get IDs from handwrytten_inserts_list. Example: 51.
must_deliver_bystring- Date the cards must arrive by, in MM/DD/YYYY format. Example: 03/15/2026.
shipping_address_idinteger- ID of the address to ship the cards to when they are not mailed directly. Get IDs from handwrytten_sender_addresses_list. Example: 88123.
shipping_method_idinteger- Shipping method. - 1: Mail Normally - 2: Ship: Address, Seal, Stamp - 3: Ship: Cards Only (no envelope) - 4: Ship: Cards Only (blank envelope unsealed) - 5: Ship: Addressed & Unsealed - 6: Ship: Addressed & Sealed. Example: 1.one of
123456 shipping_rate_idinteger- Shipping rate. - 1: Ground - 2: 2-Day - 3: Overnight - 4: Overnight Priority. Example: 1.one of
1234
handwrytten_prospecting_targets_calculateCount the residential or business prospects around an address within a radius, filtered by demographics (home ownership, income, age and more) or business size and industry.Read-onlyCalculate Prospecting Targets
Count the residential or business prospects around an address within a radius, filtered by demographics (home ownership, income, age and more) or business size and industry. Returns the number of matching targets. Use it before handwrytten_prospecting_order_preview and handwrytten_prospecting_order_add.
Inputs
addressstringrequired- Street address to serve as a central point for prospecting search. Example: 9280 South Kyrene Road.
citystringrequired- City. For prospecting tools use the format STATE;City, for example AZ;Tempe. Example: Phoenix.
countrystringrequired- Country for prospecting: United States or Canada. Example: United States.
radiusintegerrequired- Search radius in miles from the central point. Example: 5.
typestringrequired- Kind of record: for images, logo or cover; for prospecting, residential or business. Example: residential.one of
residentialbusiness zipstringrequired- ZIP or postal code. Example: 85004.
h_agestring- Household age for residential search. - 1: 18-24 years old - 2: 25-34 years old - 3: 35-44 years old - 4: 45-54 years old - 5: 55-64 years old - 6: 65-74 years old - 7: 75+ years old If you want to use multiple values, use dash to separate them, for example: "hAge-d": "1-3-4-5". Example: 2-3.
hinc_dstring- Household income for residential search. - 1: Less than $14,999 - 2: $15,000 - $19,999 - 3: $20,000 - $29,999 - 4: $30,000 - $39,999 - 5: $40,000 - $49,999 - 6: $50,000 - $74,999 - 7: $75,000 - $99,999 - 8: $100,000 - $124,999 - 9: $125,000 - $149,999 - 10: $150,000 - $174,999 - 11: $175,000 - $199,999 - 12: $200,000 - $249,999 - 13: $250,000 or more If you want to use multiple values, use dash to separate them, for example: "hinc-d": "2-3-4-5-6". Example: 5-6.
home_dstring- Home value for residential search. - 1: $1 - $49,999 - 2: $50,000 - $99,999 - 3: $100,000 - $149,999 - 4: $150,000 - $199,999 - 5: $200,000 - $249,999 - 6: $250,000 - $299,999 - 7: $300,000 - $349,999 - 8: $350,000 - $399,999 - 9: $400,000 - $449,999 - 10: $450,000 - $499,999 - 11: $500,000 - $574,999 - 12: $575,000 - $649,999 - 13: $650,000 - $724,999 - 14: $725,000 - $799,999 - 15: $800,000 - $899,999 - 16: $900,000 - $999,999 - 17: $1,000,000 - $1,999,999 - 18: $2,000,000 or More If you want to use multiple values, use dash to separate them, for example: "Home-d": "3-4-5-8-9". Example: 3-4.
kidsstring- Children in household for residential search. - 1: 1 child - 2: 2 children - 3: 3 children - 4: 4 children - 5: 5 children - 6: 6 Children - 7: 7 children - 8: 8 children - 9: 9+ children If you want to use multiple values, use dash to separate them, for example: "kids-d": "4-7-8-5". Example: 1.
latitudestring- 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.
longitudestring- 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.
maritalstring- Marital status for residential search. - 1: Unknown - 2: Household contains at least 1 married person - 3: Household contains at least 1 single person - 4: Household contains both married & single persons If you want to use multiple values, use dash to separate them, for example: "marital-d": "1-2". Example: 2.
onestring- Return all or one contact per business. - 0: Return all contacts - 1: Return one contact. Example: 0.one of
01 own_rent_dstring- Home ownership for residential search. - 1: Home owner - 2: Renter If you want to use multiple values, use dash to separate them, for example: "ownRent-d": "1-2". Example: 1.
peoplestring- People in household for residential search. - 1: 1 person - 2: 2 persons - 3: 3 persons - 4: 4 persons - 5: 5 persons - 6: 6 persons - 7: 7 persons - 8: 8 persons - 9: 9+ persons If you want to use multiple values, use dash to separate them, for example: "people-d": "4-5". Example: 2.
res_len_dstring- Length of residency for residential search. - 1: 0-6 months - 2: 7-12 months - 3: 1-2 years - 4: 3-5 years - 5: 6-10 years - 6: 11-15 years - 7: 16-20 years - 8: 20+ years If you want to use multiple values, use dash to separate them, for example: "resLen-d": "1-3-4-5-8". Example: 1-2.
salestring- Annual sales volume for business search. - 1: $1,000 - $499,999 - 2: $500,000 - $999,999 - 3: $1,000,000 - $2,499,999 - 4: $2,500,000 - $4,999,999 - 5: $5,000,000 - $9,999,999 - 6: $10,000,000 - $19,999,999 - 7: $20,000,000 - $49,999,999 - 8: $50,000,000 - $99,999,999 - 9: $100,000,000 - $499,999,999 - 10: $500,000,000 - $999,999,999 - 11: Over $1 billion If you want to use multiple values, use dash to separate them, for example: "sale-d": "6-7-8". Example: 1-2.
sicstring- Industry code for business search. Use dash to separate multiple codes, for example: "sic": "17-9999-729924". Example: 17-9999.
staffstring- Staff size for business search. - 1: 1 - 4 - 2: 5 - 9 - 3: 10 - 19 - 4: 20 - 49 - 5: 50 - 99 - 6: 100 - 249 - 7: 250 - 499 - 8: 500 - 999 - 9: 1,000 - 4,999 - 10: 5,000 - 9,999 - 11: 10,000 + If you want to use multiple values, use dash to separate them, for example: "staff-d": "2-6-8". Example: 2-3.
worth_dstring- Net worth for residential search. - 1: Less than $25,000 - 2: $25,000 - $49,999 - 3: $50,000 - $74,999 - 4: $75,000 - $99,999 - 5: $100,000 - $149,999 - 6: $150,000 - $249,999 - 7: $250,000 - $499,999 - 8: $500,000 - $749,999 - 9: $750,000 - $999,999 - 10: $1,000,000 or more If you want to use multiple values, use dash to separate them, for example: "worth-d": "6-8-9". Example: 4-5.
handwrytten_qr_code_frames_listList the decorative frames available around QR codes.Read-onlyList QR Code Frames
List the decorative frames available around QR codes. Returns frame IDs and previews. Use an ID as qr_code_frame_id in handwrytten_custom_card_create.
Inputs
This tool takes no inputs.
handwrytten_qr_code_stats_getGet scan statistics for the account's QR codes.Read-onlyGet QR Code Statistics
Get scan statistics for the account's QR codes. Returns scan counts per code. Use handwrytten_qr_codes_list for the codes themselves.
Inputs
This tool takes no inputs.
handwrytten_qr_codes_listList the QR codes created on the account.Read-onlyList QR Codes
List the QR codes created on the account. Returns QR code IDs, names and target URLs. Use an ID as qr_code_id in handwrytten_custom_card_create.
Inputs
This tool takes no inputs.
handwrytten_recipients_listList the recipient addresses saved in the address book.Read-onlyList Recipient Addresses
List the recipient addresses saved in the address book. Returns address IDs, names and addresses. Use the IDs as address_id or address_ids in handwrytten_basket_order_add.
Inputs
This tool takes no inputs.
handwrytten_sender_addresses_listList the sender (return) addresses saved on the account.Read-onlyList Sender Addresses
List the sender (return) addresses saved on the account. Returns address IDs and addresses. Use an ID as return_address_id when ordering; use handwrytten_default_sender_address_get for the default one.
Inputs
This tool takes no inputs.
handwrytten_signatures_listList the custom handwritten signatures saved on the account.Read-onlyList Signatures
List the custom handwritten signatures saved on the account. Returns signature IDs and previews. Use the IDs with handwrytten_prospecting_order_add.
Inputs
This tool takes no inputs.
handwrytten_stamp_options_listList the stamp options for US orders.Read-onlyList Stamp Options
List the stamp options for US orders. Returns option IDs, names and prices. Pass an ID as stamp_option_id when ordering.
Inputs
This tool takes no inputs.
handwrytten_states_listList the states or provinces of a country.Read-onlyList States
List the states or provinces of a country. Returns state codes and names. Get country IDs from handwrytten_countries_list (1 is the United States).
Inputs
country_idintegerrequired- Handwrytten country ID: 1 is the United States, 2 is Canada. Get other IDs from handwrytten_countries_list. Example: 1.
handwrytten_user_getGet the account behind the API key: name, email, credit balance, test-mode flag and default settings.Read-onlyGet User
Get the account behind the API key: name, email, credit balance, test-mode flag and default settings. Returns the user object. Use it to check the credit balance or confirm which account is connected.
Inputs
This tool takes no inputs.
handwrytten_basket_order_addAdd an order for a card to the basket without paying, for one saved address (address_id), several (address_ids) or inline addresses with per-recipient messages (addresses).WriteAdd Order to Basket
Add an order for a card to the basket without paying, for one saved address (address_id), several (address_ids) or inline addresses with per-recipient messages (addresses). Returns the basket order IDs. Use handwrytten_basket_send to pay for and submit everything in the basket. Get card IDs from handwrytten_cards_list and font IDs from handwrytten_fonts_list.
Inputs
card_idintegerrequired- ID of the card (stationery design) to use. Get card IDs from handwrytten_cards_list. Example: 3404.
address_idinteger- ID of the saved address to act on. Get recipient IDs from handwrytten_recipients_list and sender IDs from handwrytten_sender_addresses_list. Example: 90211.
address_idsarray- IDs of several saved recipient addresses to send the card to, one order each. Use instead of address_id or addresses. Get IDs from handwrytten_recipients_list. Example: [90211, 90212]
addressesarray- 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. Example: [{"first_name": "Frank", "last_name": "Jones", "address1": "1600 Main Street", "city": "Phoenix", "state": "AZ", "zip": "85004", "country_id": 1, "message": ...
auto_font_sizeboolean- true lets Handwrytten shrink the font so a long message fits the card. Example: true.
bundle_idinteger- Bundle to ship with the order. Use GET /bundles/list to fetch the available bundles. Example: 7.
check_quantityboolean- check cards and inserts quantity in stock, return insufficient quantity error in case of low stock. Example: true.
client_metadatastring- Your own reference stored with the order and returned in order details and webhooks, such as a CRM contact ID. Example: crm-contact-48213.
coupon_codestring- Coupon code to apply to the order price. Example: SPRING10.
delivery_confirmationinteger- Delivery confirmation option for the order: 0 — none, 1 — delivery confirmation, 2 — CASS validation only. Example: 0.one of
012 denomination_idinteger- Gift card denomination ID to enclose with the card. Get IDs from handwrytten_gift_cards_list. Example: 12.
fontstring- Handwriting font ID (slug) for the message, such as hwDavid. Get IDs from handwrytten_fonts_list. Example: hwDavid.
font_sizeinteger- Font size in points for the handwritten message. Leave empty for the default size. Example: 13.
for_freeboolean- true to place the order without charge where the account allows free orders (for example promotional credit). Usually leave empty. Example: true.
insert_idinteger- ID of a custom insert to enclose with the card. Get IDs from handwrytten_inserts_list. Example: 51.
quantityinteger- Number of identical cards to send to each recipient. Defaults to 1. Example: 1.
return_address_idinteger- ID of the sender (return) address. Get IDs from handwrytten_sender_addresses_list. Example: 88123.
stamp_option_idinteger- Stamp option to use. Applies to US orders; ignored for international. Use GET /shipping/stampOptions to fetch the available options. Example: 2.
handwrytten_basket_sendPay for and submit every order currently in the basket, using account credit first and then the card on file or credit_card_id.WriteSend Basket
Pay for and submit every order currently in the basket, using account credit first and then the card on file or credit_card_id. Returns the submitted order IDs and charges. Orders spend account credit or charge a card unless the account is in test mode (handwrytten_test_mode_set). Add orders first with handwrytten_basket_order_add or handwrytten_prospecting_order_add.
Inputs
check_quantityboolean- check cards and inserts quantity in stock, return insufficient quantity error in case of low stock. Example: true.
coupon_codestring- Coupon code to apply to the order price. Example: SPRING10.
credit_card_idinteger- If provided, it is the id number of the credit card on file to be charged. Example: 34124.
notesobject- dictionary of order notes, order id is used as a key. Example: {"196936": "Deliver before the holidays"}
price_structureobject- Expected structure price by types of payment. If the structure does not match during the calculation, an error will be returned. Example: {"credit": 3.25}
handwrytten_custom_card_createCreate a custom card from uploaded or preset covers plus header, footer, inside and back text or logos; with is_update true and card_id it updates an existing custom card.WriteCreate or Update Custom Card
Create a custom card from uploaded or preset covers plus header, footer, inside and back text or logos; with is_update true and card_id it updates an existing custom card. Returns the card ID. Get dimension IDs from handwrytten_card_dimensions_list, images from handwrytten_custom_images_list and fonts from handwrytten_fonts_list.
Inputs
namestringrequired- Name to save the record under. Example: Frank Jones.
back_alignstring- Horizontal alignment of the back content: left, center or right. Example: left.one of
leftcenterright back_cover_idinteger- ID of an uploaded cover image (type: cover) for the back surface. Example: 4409.
back_font_colorstring- Hex color of the back text, such as #000000. Example: #000000.
back_font_idinteger- Font ID for the back text. See /fonts/listForCustomizer. Example: 1.
back_font_sizeinteger- Font size of the back text in points. Example: 16.
back_logo_idinteger- ID of the logo image (type: logo) for the back. Used when back_type is 'logo'. Example: 4410.
back_size_percentinteger- Size of the back logo as a percentage of the surface. Example: 24.
back_textstring- Back text. Used when back_type is 'text'. Example: 123.
back_typestring- What the back surface shows: text or logo. Example: text.one of
textlogo back_vertical_alignstring- Vertical alignment on the back surface: top, center or bottom. Example: top.one of
topcenterbottom card_idinteger- ID of the card (stationery design) to use. Get card IDs from handwrytten_cards_list. Example: 3404.
cover_idinteger- ID of the uploaded cover image (type: cover) to use as the front of the card. Example: 4409.
cover_size_percentinteger- Size of the cover image as a percentage of the card front. Example: 84.
dimension_idinteger- Card size and format. See /cards/listDimensions for available options. Example: 1.
footer_alignstring- Horizontal alignment of the footer content: left, center or right. Example: left.one of
leftcenterright footer_font_colorstring- Hex color of the footer text, such as #000000. Example: #000000.
footer_font_idinteger- Font ID for the footer text. See /fonts/listForCustomizer. Example: 1.
footer_font_sizeinteger- Font size of the footer text in points. Example: 16.
footer_logo_idinteger- ID of the logo image (type: logo) for the footer. Used when footer_type is 'logo'. Example: 4410.
footer_logo_size_percentinteger- Size of the footer logo as a percentage of its area. Example: 50.
footer_textstring- Footer text. Used when footer_type is 'text'. Example: footer text.
footer_typestring- Whether the footer uses text or a logo image. Example: text.one of
textlogo header_alignstring- Horizontal alignment of the header content: left, center or right. Example: left.one of
leftcenterright header_font_colorstring- Hex color of the header text, such as #000000. Example: #000000.
header_font_idinteger- Font ID for the header text. See /fonts/listForCustomizer. Example: 1.
header_font_sizeinteger- Font size of the header text in points. Example: 16.
header_logo_idinteger- ID of the logo image (type: logo) for the header. Used when header_type is 'logo'. Example: 4410.
header_logo_size_percentinteger- Size of the header logo as a percentage of its area. Example: 50.
header_textstring- Header text. Used when header_type is 'text'. Example: Header text.
header_typestring- Whether the header uses text or a logo image. Foldable cards only. Example: text.one of
textlogo is_updateboolean- Set to true to update an existing custom card. Must be combined with card_id. Example: false.
main_alignstring- Horizontal alignment of the inside top content: left, center or right. Example: left.one of
leftcenterright main_font_colorstring- Hex color of the inside top text, such as #000000. Example: #000000.
main_font_idinteger- Font ID for the inside top text. See /fonts/listForCustomizer. Example: 1.
main_font_sizeinteger- Font size of the inside top text in points. Example: 50.
main_logo_idinteger- ID of the logo image (type: logo) for the inside top. Used when main_type is 'logo'. Example: 4410.
main_logo_size_percentinteger- Size of the inside top logo as a percentage of its area. Example: 50.
main_textstring- Inside top text. Used when main_type is 'text'. Example: Thank you for choosing us!.
main_typestring- Content type for the inside top surface. Foldable cards only. Example: text.one of
textlogo preset_back_cover_idinteger- ID of a preset cover for the back surface. See /cards/listPresetCovers. Example: 12.
preset_cover_idinteger- ID of a preset cover to use instead of a custom uploaded image. See /cards/listPresetCovers. Example: 12.
qr_code_alignstring- Horizontal alignment of the QR code: left, center or right. Example: left.one of
leftcenterright qr_code_frame_idinteger- ID of the QR code frame. See /qrCode/frames for available frames. Example: 3.
qr_code_idinteger- ID of the QR code to include. See /qrCode for available QR codes. Example: 234.
qr_code_locationstring- Where the QR code goes: header or footer. Example: header.one of
headerfooter qr_code_size_percentinteger- Size of the QR code as a percentage of its area. Example: 20.
handwrytten_default_sender_address_setMake a saved sender address the account default.WriteSet Default Sender Address
Make a saved sender address the account default. Returns the result. Get address IDs from handwrytten_sender_addresses_list.
- Idempotent
Inputs
address_idintegerrequired- ID of the sender address to make the default. Get it from handwrytten_sender_addresses_list. Example: 88123.
handwrytten_order_single_step_createCreate and submit one handwritten card order in a single call, giving the card, font, message, sender and recipient addresses.WriteSend Single Card Order
Create and submit one handwritten card order in a single call, giving the card, font, message, sender and recipient addresses. Returns the order ID and status. Use it for one card to one recipient; use handwrytten_basket_order_add plus handwrytten_basket_send for several orders paid together. Orders spend account credit or charge a card unless the account is in test mode (handwrytten_test_mode_set). Get card IDs from handwrytten_cards_list and font labels from handwrytten_fonts_list.
Inputs
card_idintegerrequired- ID of the card (stationery design) to use. Get card IDs from handwrytten_cards_list. Example: 3404.
font_labelstringrequired- The colloquial name of the font, such as 'Fancy Jenna' or 'Casual David'. Example: Chill Charity.
messagestringrequired- The handwritten message text. Use \n for new lines. Example: Dear Frank,\nThank you so much for your business.
recipient_address1stringrequired- The recipient's street address, first line. Example: 1600 Main Street.
recipient_citystringrequired- The recipient's city. Example: Phoenix.
recipient_zipstringrequired- The recipient's ZIP or postal code. Example: 85004.
sender_address1stringrequired- The sender's street address, first line. Example: 9280 South Kyrene Road.
sender_citystringrequired- The sender's city. Example: Tempe.
sender_zipstringrequired- The sender's ZIP or postal code. Example: 85284.
bundle_idinteger- Bundle to ship with the order. Use GET /bundles/list to fetch the available bundles. Example: 7.
client_metadatastring- Your own reference stored with the order and returned in order details and webhooks, such as a CRM contact ID. Example: crm-contact-48213.
coupon_codestring- Coupon code to apply to the order price. Example: SPRING10.
credit_card_idinteger- The credit card id to charge for the order. Example: 34124.
date_sendstring- Date to send the card, as YYYY-MM-DD. Leave empty to send as soon as possible. Example: 2026-02-01.
delivery_confirmationinteger- Delivery confirmation option for the order: 0 — none, 1 — delivery confirmation, 2 — CASS validation only. Example: 0.one of
012 denomination_idinteger- Gift card denomination ID to enclose with the card. Get IDs from handwrytten_gift_cards_list. Example: 12.
insert_idinteger- ID of a custom insert to enclose with the card. Get IDs from handwrytten_inserts_list. Example: 51.
recipient_address2string- The recipient's street address, second line (suite, apartment). Example: Apt 4.
recipient_business_namestring- The recipient's business name. Example: Jones Plumbing.
recipient_countrystring- The recipient's country name (default United States). Example: United States.
recipient_country_idinteger- The recipient's Handwrytten country ID (1 United States, 2 Canada; default 1); see handwrytten_countries_list. Example: 1.
recipient_first_namestring- The recipient's first name. Example: Frank.
recipient_last_namestring- The recipient's last name. Example: Jones.
recipient_statestring- The recipient's state or province code; required for the United States and Canada. Example: AZ.
sender_address2string- The sender's street address, second line (suite, apartment). Example: Suite 134.
sender_business_namestring- The sender's business name. Example: Acme Realty.
sender_countrystring- The sender's country name (default United States). Example: United States.
sender_country_idinteger- The sender's Handwrytten country ID (1 United States, 2 Canada; default 1); see handwrytten_countries_list. Example: 1.
sender_first_namestring- The sender's first name. Example: Joe.
sender_last_namestring- The sender's last name. Example: Smith.
sender_statestring- The sender's state or province code; required for the United States and Canada. Example: AZ.
stamp_option_idinteger- Stamp option to use. Applies to US orders; ignored for international. Use GET /shipping/stampOptions to fetch the available options. Example: 2.
validate_addressboolean- true checks the recipient address before accepting the order. Example: true.
webhook_urlstring- URL Handwrytten calls when the order status changes. Example: https://example.com/hooks/handwrytten.
wishesstring- The closing (sign-off) written right-aligned under the message, such as All the best, Joe. Use \n for new lines. Example: All the best,\nJoe.
handwrytten_prospecting_order_addAdd a prospecting campaign to the basket: cards to residential or business prospects around an address, with a message, font and return address.WriteAdd Prospecting Order to Basket
Add a prospecting campaign to the basket: cards to residential or business prospects around an address, with a message, font and return address. Returns the basket order. Call handwrytten_basket_send to pay and submit it. Count prospects first with handwrytten_prospecting_targets_calculate.
Inputs
addressstringrequired- Street address to serve as a central point for prospecting search. Example: 9280 South Kyrene Road.
card_idintegerrequired- ID of the card (stationery design) to use. Get card IDs from handwrytten_cards_list. Example: 3404.
citystringrequired- City. For prospecting tools use the format STATE;City, for example AZ;Tempe. Example: Phoenix.
countrystringrequired- Country for prospecting: United States or Canada. Example: United States.
fontstringrequired- Handwriting font ID (slug) for the message, such as hwDavid. Get IDs from handwrytten_fonts_list. Example: hwDavid.
messagestringrequired- The handwritten message text. Use \n for new lines. Example: Dear Frank,\nThank you so much for your business.
radiusintegerrequired- Search radius in miles from the central point. Example: 5.
recordsintegerrequired- Number of prospects (cards) to send. Example: 5.
return_address_idintegerrequired- ID of the sender (return) address. Get IDs from handwrytten_sender_addresses_list. Example: 88123.
zipstringrequired- ZIP or postal code. Example: 85004.
font_sizeinteger- Font size in points for the handwritten message. Leave empty for the default size. Example: 13.
h_agestring- Household age for residential search. Use dash to separate multiple values. Example: 2-3.
hinc_dstring- Household income for residential search. Use dash to separate multiple values. Example: 5-6.
home_dstring- Home value for residential search. Use dash to separate multiple values. Example: 3-4.
insert_idinteger- ID of a custom insert to enclose with the card. Get IDs from handwrytten_inserts_list. Example: 51.
kidsstring- Children in household for residential search. Use dash to separate multiple values. Example: 1.
latitudestring- 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.
longitudestring- 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.
maritalstring- Marital status for residential search. Use dash to separate multiple values. Example: 2.
maskboolean- If no data was found at the address, try searching by geodata. Example: true.
must_deliver_bystring- Date the cards must arrive by, in MM/DD/YYYY format. Example: 03/15/2026.
own_rent_dstring- Home ownership for residential search. Use dash to separate multiple values. Example: 1.
peoplestring- People in household for residential search. Use dash to separate multiple values. Example: 2.
res_len_dstring- Length of residency for residential search. Use dash to separate multiple values. Example: 1-2.
search_valuestring- The address text used for the prospecting search, as shown in the Handwrytten app. Example: 9280 South Kyrene Road, Tempe, AZ.
shipping_address_idinteger- ID of the address to ship the cards to when they are not mailed directly. Get IDs from handwrytten_sender_addresses_list. Example: 88123.
shipping_method_idinteger- Shipping method. - 1: Mail Normally - 2: Ship: Address, Seal, Stamp - 3: Ship: Cards Only (no envelope) - 4: Ship: Cards Only (blank envelope unsealed) - 5: Ship: Addressed & Unsealed - 6: Ship: Addressed & Sealed. Example: 1.one of
123456 shipping_rate_idinteger- Shipping rate. - 1: Ground - 2: 2-Day - 3: Overnight - 4: Overnight Priority. Example: 1.one of
1234 signature_idinteger- ID of a custom signature to add. Get IDs from handwrytten_signatures_list. Example: 512.
signature2_idinteger- ID of a second custom signature. Get IDs from handwrytten_signatures_list. Example: 513.
wishesstring- The closing (sign-off) written right-aligned under the message, such as All the best, Joe. Use \n for new lines. Example: All the best,\nJoe.
worth_dstring- Net worth for residential search. Use dash to separate multiple values. Example: 4-5.
handwrytten_qr_code_createCreate a trackable QR code that points to a URL, for printing on custom cards.WriteCreate QR Code
Create a trackable QR code that points to a URL, for printing on custom cards. Returns the QR code ID. Use handwrytten_qr_code_stats_get for scan counts.
Inputs
namestringrequired- Name to save the record under. Example: Frank Jones.
urlstringrequired- Destination URL the QR code points to. Example: https://www.example.com/offer.
handwrytten_recipient_createSave a new recipient address to the address book.WriteAdd Recipient Address
Save a new recipient address to the address book. Returns the new address ID. Get country IDs from handwrytten_countries_list.
Inputs
address1stringrequired- Street address, first line. Example: 1600 Main Street.
citystringrequired- City. For prospecting tools use the format STATE;City, for example AZ;Tempe. Example: Phoenix.
country_idstringrequired- Handwrytten country ID: 1 is the United States, 2 is Canada. Get other IDs from handwrytten_countries_list. Example: 1.
first_namestringrequired- First name of the person at the address. Example: Frank.
zipstringrequired- ZIP or postal code. Example: 85004.
address2string- Street address, second line (suite, apartment). Example: Apt 4.
birthdaystring- Birthday of the recipient as YYYY-MM-DD, for birthday campaigns. Example: 1985-04-12.
last_namestring- Last name of the person at the address. Example: Jones.
namestring- Name to save the record under. Example: Frank Jones.
statestring- State or province code, required for the United States and Canada, for example AZ. Example: AZ.
handwrytten_recipient_updateUpdate a saved recipient address.WriteUpdate Recipient Address
Update a saved recipient address. Returns the result. Get address IDs from handwrytten_recipients_list.
- Idempotent
Inputs
address_idstringrequired- ID of the saved address to act on. Get recipient IDs from handwrytten_recipients_list and sender IDs from handwrytten_sender_addresses_list. Example: 90211.
address1string- Street address, first line. Example: 1600 Main Street.
address2string- Street address, second line (suite, apartment). Example: Apt 4.
birthdaystring- Birthday of the recipient as YYYY-MM-DD, for birthday campaigns. Example: 1985-04-12.
business_namestring- Business name printed on the address. Example: Jones Plumbing.
citystring- City. For prospecting tools use the format STATE;City, for example AZ;Tempe. Example: Phoenix.
country_idstring- Handwrytten country ID: 1 is the United States, 2 is Canada. Get other IDs from handwrytten_countries_list. Example: 1.
first_namestring- First name of the person at the address. Example: Frank.
last_namestring- Last name of the person at the address. Example: Jones.
namestring- Name to save the record under. Example: Frank Jones.
statestring- State or province code, required for the United States and Canada, for example AZ. Example: AZ.
zipstring- ZIP or postal code. Example: 85004.
handwrytten_sender_address_createSave a new sender (return) address, optionally as the default.WriteAdd Sender Address
Save a new sender (return) address, optionally as the default. Returns the new address ID. Get country IDs from handwrytten_countries_list.
Inputs
address1stringrequired- Street address, first line. Example: 1600 Main Street.
citystringrequired- City. For prospecting tools use the format STATE;City, for example AZ;Tempe. Example: Phoenix.
country_idstringrequired- Handwrytten country ID: 1 is the United States, 2 is Canada. Get other IDs from handwrytten_countries_list. Example: 1.
zipstringrequired- ZIP or postal code. Example: 85004.
address2string- Street address, second line (suite, apartment). Example: Apt 4.
business_namestring- Business name printed on the address. Example: Jones Plumbing.
defaultboolean- true makes this the account's default sender address. Example: true.
first_namestring- First name of the person at the address. Example: Frank.
last_namestring- Last name of the person at the address. Example: Jones.
namestring- Name to save the record under. Example: Frank Jones.
statestring- State or province code, required for the United States and Canada, for example AZ. Example: AZ.
handwrytten_sender_address_updateUpdate a saved sender (return) address.WriteUpdate Sender Address
Update a saved sender (return) address. Returns the result. Get address IDs from handwrytten_sender_addresses_list.
- Idempotent
Inputs
address1string- Street address, first line. Example: 1600 Main Street.
address2string- Street address, second line (suite, apartment). Example: Apt 4.
citystring- City. For prospecting tools use the format STATE;City, for example AZ;Tempe. Example: Phoenix.
statestring- State or province code, required for the United States and Canada, for example AZ. Example: AZ.
zipstring- ZIP or postal code. Example: 85004.
handwrytten_test_mode_setSwitch the account into test mode (1) or back to live mode (0).WriteSet Test Mode
Switch the account into test mode (1) or back to live mode (0). In test mode orders are accepted but not fulfilled and payments are only authorized. Returns the new mode. Use it before trying the order tools.
- Idempotent
Inputs
test_modeintegerrequired- 1 turns test mode on (orders are not fulfilled or charged), 0 returns to live mode. Example: 1.one of
01
handwrytten_basket_clearRemove every order from the basket without sending them.DestructiveClear Basket
Remove every order from the basket without sending them. Returns the result. Use it to discard orders added with handwrytten_basket_order_add.
- Idempotent
Inputs
This tool takes no inputs.
handwrytten_custom_card_deleteDelete a custom card created on the account.DestructiveDelete Custom Card
Delete a custom card created on the account. Returns the result. Get custom card IDs from handwrytten_cards_list.
- Idempotent
Inputs
card_idintegerrequired- ID of the custom card to delete. Get it from handwrytten_cards_list. Example: 305578.
handwrytten_custom_image_deleteDelete an uploaded logo or cover image.DestructiveDelete Custom Image
Delete an uploaded logo or cover image. Returns the result. Get image IDs from handwrytten_custom_images_list.
- Idempotent
Inputs
image_idintegerrequired- ID of an uploaded custom image. Get IDs from handwrytten_custom_images_list. Example: 4410.
handwrytten_order_cancelCancel an order that is paid but not yet processed.DestructiveCancel Order
Cancel an order that is paid but not yet processed. Returns the result; processed orders cannot be cancelled and return a 400 error. Get order IDs from the order tools.
- Idempotent
Inputs
order_idintegerrequired- ID of the order. Get it from the order or basket tools. Example: 725563.
handwrytten_qr_code_deleteDelete a QR code.DestructiveDelete QR Code
Delete a QR code. Returns the result. Get IDs from handwrytten_qr_codes_list.
- Idempotent
Inputs
qr_code_idstringrequired- ID of the QR code to delete. Get it from handwrytten_qr_codes_list. Example: 234.
handwrytten_recipients_deleteDelete one recipient address (address_id) or several (address_ids) from the address book.DestructiveDelete Recipient Addresses
Delete one recipient address (address_id) or several (address_ids) from the address book. Returns the result. Get IDs from handwrytten_recipients_list.
- Idempotent
Inputs
address_idnumber- ID of the saved address to act on. Get recipient IDs from handwrytten_recipients_list and sender IDs from handwrytten_sender_addresses_list. Example: 90211.
address_idsarray- IDs of several saved recipient addresses to send the card to, one order each. Use instead of address_id or addresses. Get IDs from handwrytten_recipients_list. Example: [90211, 90212]
handwrytten_sender_addresses_deleteDelete one sender address (id) or several (address_ids).DestructiveDelete Sender Addresses
Delete one sender address (id) or several (address_ids). Returns the result. Get IDs from handwrytten_sender_addresses_list.
- Idempotent
Inputs
address_idinteger- ID of one sender address to delete. Use address_ids for several. Get IDs from handwrytten_sender_addresses_list. Example: 88123.
address_idsarray- IDs of several saved recipient addresses to send the card to, one order each. Use instead of address_id or addresses. Get IDs from handwrytten_recipients_list. Example: [90211, 90212]
No tools match.