All integrations

Handwrytten

MARKETING · MARKETING

Order real handwritten cards, mailed from the account they connected.

Connecting Handwrytten in practice

Handwrytten writes and posts physical cards, so a bad call costs postage rather than a row: POST /orders/singleStepOrder creates and submits a whole order in one request, charging a stored credit card id, and the only rehearsal space is an account-level test mode that authorizes payment without capturing it and accepts orders without fulfilling them. Test mode is a property of the account, not of the request.

Scopes that draw scrutiny

  • Authorization: <API key> Sent raw, with no Bearer prefix, and created on the Integrations page. The same key that lists fonts also places orders that cost real money.
  • login and password via /auth/authorization Deprecated username-and-password authentication that remains supported for existing integrations, so a credential removed from one path may still work through the other.

Worth knowing

  • Because test mode is toggled per account — on the Integrations page or through POST /auth/setTestMode — a staging agent and a production agent sharing one account cannot differ.
  • singleStepOrder requires font_label, card_id, message and both addresses, and font_label is the colloquial font name such as "Chill Charity" rather than an id, so it has to be resolved from GET /fonts/list before the first order.
  • sender_state and recipient_state are required only for country ids 1 and 2 (United States and Canada), and stamp_option_id applies to US orders and is ignored internationally — so validation rules change with the destination.
  • The spec lists two production servers, api.handwrytten.com/v2 and api2.handwrytten.com/api/v1/user/, so the base URL depends on the endpoint rather than on a version you pick once.

Checked against Handwrytten API documentation (2026-09-29), OpenAPI specification (2026-09-29)

Acts as the person, not as itself

Each user connects their own account. Every call carries both identities — the agent and the person it is acting for — so the agent can never reach past what that individual can already do.

Credentials never touch the agent

Tokens live in the vault and attach server-side at call time. The agent holds a session, not a secret, and revoking access does not mean rotating a key.

Every call on the record

Who asked, which agent acted, which action ran, and the verdict that let it through — one audit trail across every integration, not one per vendor.

What an agent can do

Each action is granted on its own. An agent allowed to read is not thereby allowed to write, and the scope beside each row is what the acting user must have connected for it to run at all.

handwrytten_delete_qrcode_by_idWRITE

Delete a QR Code. Handwrytten DELETE /v2/qrCode/{id}.

api
handwrytten_get_auth_getuserREAD

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. Handwrytten GET /v2/auth/getUser.

api
handwrytten_get_basket_countREAD

Get the number of items in the user's basket. Handwrytten GET /v2/basket/count.

api
handwrytten_get_bundles_listREAD

Returns the list of active, in-stock bundles — physical items (such as a box of cookies) shipped to your recipient together with your card. The `id` field is what's passed as `bundle_id` on order calls. Handwrytten GET /v2/bundles/list.

api
handwrytten_get_cards_listREAD

Get a list of all cards available to the user, including any custom or privately-available cards. Handwrytten GET /v2/cards/list.

api
handwrytten_get_cards_list_sectionsREAD

Get a list of cards available to the user, grouped by categories. Handwrytten GET /v2/cards/list/sections.

api
handwrytten_get_cards_listcustomuserimagesREAD

List all custom images uploaded by the user. Handwrytten GET /v2/cards/listCustomUserImages.

api
handwrytten_get_cards_viewREAD

Get detailed information about a card. Handwrytten GET /v2/cards/view.

api
handwrytten_get_categories_listREAD

Get list of available card categories. Handwrytten GET /v2/categories/list.

api
handwrytten_get_checkauth_authREAD

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. Handwrytten GET /v2/checkauth/auth.

api
handwrytten_get_countries_listREAD

Returns the list of all supported countries, including available states/provinces and delivery costs. Handwrytten GET /v2/countries/list.

api
handwrytten_get_countries_liststatesREAD

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). Handwrytten GET /v2/countries/listStates.

api
handwrytten_get_design_dimensionsREAD

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). Handwrytten GET /v2/design/dimensions.

api
handwrytten_get_design_presetimagesREAD

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. Handwrytten GET /v2/design/presetImages.

api
handwrytten_get_fonts_listREAD

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. Handwrytten GET /v2/fonts/list.

api
handwrytten_get_giftcards_listREAD

Get list of gift cards and available denominations for purchase and inclusion in order. Handwrytten GET /v2/giftCards/list.

api
handwrytten_get_inserts_listREAD

Get list of custom inserts available for the account. Handwrytten GET /v2/inserts/list.

api
handwrytten_get_orders_detailsREAD

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). Handwrytten GET /v2/orders/details.

api
handwrytten_get_profile_addressREAD

Get user's default sender address. Handwrytten GET /v2/profile/address.

api
handwrytten_get_profile_listaddressesREAD

List Sender Addresses. Handwrytten GET /v2/profile/listAddresses.

api
handwrytten_get_profile_recipientslistREAD

Get list of recipient addresses in user's Address Book. Handwrytten GET /v2/profile/recipientsList.

api
handwrytten_get_profile_signaturesREAD

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. Handwrytten GET /v2/profile/signatures.

api
handwrytten_get_qrcodeREAD

Get a list of QR Codes on the account. Handwrytten GET /v2/qrCode.

api
handwrytten_get_qrcode_dashboardREAD

Get the statistics for the QR Codes on the account. Handwrytten GET /v2/qrCode/dashboard.

api
handwrytten_get_qrcode_framesREAD

Get a list of available QR Code frames. Handwrytten GET /v2/qrCode/frames.

api
handwrytten_get_shipping_stampoptionsREAD

Returns the list of available stamp options. The `id` field is what's passed as `stamp_option_id` on order calls. Stamp options apply to US orders; the field is ignored for international destinations. Handwrytten GET /v2/shipping/stampOptions.

api
handwrytten_post_auth_settestmodeWRITE

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. In test mode, orders are accepted and processed normally but are not fulfilled. Handwrytten POST /v2/auth/setTestMode.

api
handwrytten_post_basket_clearWRITE

Removes all items from the basket. Returns the list of items that were cleared. Handwrytten POST /v2/basket/clear.

api
handwrytten_post_basket_sendWRITE

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. Handwrytten POST /v2/basket/send.

api
handwrytten_post_cards_checkuploadedcustomlogoWRITE

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. Handwrytten POST /v2/cards/checkUploadedCustomLogo.

api
handwrytten_post_cards_createcustomcardWRITE

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. Handwrytten POST /v2/cards/createCustomCard.

api
handwrytten_post_cards_deletecustomlogoWRITE

Delete a custom uploaded image. Handwrytten POST /v2/cards/deleteCustomLogo.

api
handwrytten_post_design_deleteWRITE

Deletes a custom card created by the user. Handwrytten POST /v2/design/delete.

api
handwrytten_post_orders_cancelWRITE

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. Handwrytten POST /v2/orders/cancel.

api
handwrytten_post_orders_placebasketWRITE

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. Handwrytten POST /v2/orders/placeBasket.

api
handwrytten_post_orders_singlesteporderWRITE

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. Requires an API key in the `Authorization` header. See the [Integrations](https://app.handwrytten.com/integrations) page in your dashboard to generate one. Handwrytten POST /v2/orders/singleStepOrder.

api
handwrytten_post_outbound_addtobasketWRITE

Add prospecting campaign order to basket. Use `Send Basket` call to submit all orders in basket for processing. Handwrytten POST /v2/outbound/addToBasket.

api
handwrytten_post_outbound_calctargetsWRITE

Calculate targets for prospecting campaign. Handwrytten POST /v2/outbound/calcTargets.

api
handwrytten_post_outbound_processWRITE

Preview prospecting campaign order pricing. Handwrytten POST /v2/outbound/process.

api
handwrytten_post_profile_addrecipientWRITE

Add a new recipient address to user's Address Book. Handwrytten POST /v2/profile/addRecipient.

api
handwrytten_post_profile_createaddressWRITE

Add a new sender address to user's Address Book. Handwrytten POST /v2/profile/createAddress.

api
handwrytten_post_profile_deleteaddressWRITE

Delete a sender address from user's Address Book. Handwrytten POST /v2/profile/deleteAddress.

api
handwrytten_post_profile_deleterecipientWRITE

Delete Recipient Address. Handwrytten POST /v2/profile/deleteRecipient.

api
handwrytten_post_profile_setdefaultaddressWRITE

Set user's default sender address. Handwrytten POST /v2/profile/setDefaultAddress.

api
handwrytten_post_profile_updaterecipientWRITE

Update a recipient address in Address Book. Handwrytten POST /v2/profile/updateRecipient.

api
handwrytten_post_qrcodeWRITE

Create a new QR Code. Handwrytten POST /v2/qrCode.

api
handwrytten_put_profile_updateaddressWRITE

Update a sender address in user's Address Book. Handwrytten PUT /v2/profile/updateAddress.

api

Put Handwrytten behind one governed endpoint.

Same permissions, same audit trail, whatever else you connect next.