Skip to main content
API docs by Redocly

Handwrytten API (3.15.0)

About

Send 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.

Test Mode

During development your account can be switched to test mode on the 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.

Client Libraries

If you're working in Python or JavaScript/TypeScript, you can use one of the official client packages instead of making raw API calls:

Authentication

Authenticate by including your API key in the Authorization request header — pass the key directly, with no Bearer: prefix:

Authorization: YOUR_API_KEY

API keys can be created and managed on the Integrations page in your dashboard.

Note: Authentication using login/password via /auth/authorization is deprecated. It remains supported for existing integrations but is not recommended for new ones.

Getting Started

Sign In with Password Deprecated

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.

This endpoint is deprecated and not recommended for new integrations. It remains supported for existing clients authenticating with login/password.

For new integrations, use an API key instead — generate one on the Integrations page in your dashboard, and pass it directly in the Authorization header with no Bearer: prefix.

Authorizations:
ApiKeyAuthuidKey
Request Body schema: application/json
login
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "login": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "uid": "string"
}

Single Step Order

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 page in your dashboard to generate one.

Authorizations:
NoneApiKeyAuth
Request Body schema: application/json
uid
string
Deprecated

Deprecated. Pass your API key in the Authorization header instead.

login
string
Deprecated

Deprecated. Use API key authentication instead.

password
string
Deprecated

Deprecated. Use API key authentication instead.

card_id
required
integer

Id of the card you want to send

denomination_id
integer

Optional. Use if sending a gift card

message
required
string

The body of the message. Use '\n' for new lines

wishes
string

The right-shifted closing part of the note

font_label
required
string

The colloquial name of the font, such as 'Fancy Jenna' or 'Casual David'

credit_card_id
integer

The credit card id to charge for the order.

insert_id
integer

Insert id for the order

couponCode
string

Coupon code

date_send
string

Send date

validate_address
boolean
delivery_confirmation
boolean

Request delivery confirmation for the order

webhook_url
string

Webhook URL

sender_first_name
string
sender_last_name
string
sender_address1
required
string
sender_address2
string
sender_city
required
string
sender_zip
required
string
sender_state
string

Required for US and Canada (country id 1 or 2)

sender_country_id
integer
Default: 1

1 (United States) by default

sender_country
string

United States by default

recipient_first_name
string
recipient_last_name
string
recipient_address1
required
string
recipient_address2
string
recipient_city
required
string
recipient_zip
required
string
recipient_state
string

Required for US and Canada (country id 1 or 2)

recipient_country_id
integer
Default: 1

1 (United States) by default

recipient_country
string

United States by default

client_metadata
string

Order metadata

Responses

Request samples

Content type
application/json
{
  • "uid": "dlqwjkqwdlkjqwdq09302184383",
  • "login": "john@jjf.com",
  • "password": "8yfqwiuy@!$",
  • "card_id": 3404,
  • "denomination_id": 12,
  • "message": "Dear Frank,\nThank you so much for your interest in our services.",
  • "wishes": "All the best,\nJoe",
  • "font_label": "Chill Charity",
  • "credit_card_id": 34124,
  • "insert_id": 0,
  • "couponCode": "string",
  • "date_send": "string",
  • "validate_address": true,
  • "delivery_confirmation": true,
  • "webhook_url": "string",
  • "sender_first_name": "string",
  • "sender_last_name": "string",
  • "sender_address1": "string",
  • "sender_address2": "string",
  • "sender_city": "string",
  • "sender_zip": "string",
  • "sender_state": "string",
  • "sender_country_id": 1,
  • "sender_country": "string",
  • "recipient_first_name": "string",
  • "recipient_last_name": "string",
  • "recipient_address1": "string",
  • "recipient_address2": "string",
  • "recipient_city": "string",
  • "recipient_zip": "string",
  • "recipient_state": "string",
  • "recipient_country_id": 1,
  • "recipient_country": "string",
  • "client_metadata": "string"
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "order_id": 196936,
  • "mail_sent": 0
}

Authentication

Authentication

Sign In with Password Deprecated

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.

This endpoint is deprecated and not recommended for new integrations. It remains supported for existing clients authenticating with login/password.

For new integrations, use an API key instead — generate one on the Integrations page in your dashboard, and pass it directly in the Authorization header with no Bearer: prefix.

Authorizations:
ApiKeyAuthuidKey
Request Body schema: application/json
login
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "login": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "uid": "string"
}

Check Authentication

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.

Authorizations:
ApiKeyAuthuidKey

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "login": "example@example.com",
  • "has_no_password": true,
  • "last": "google",
  • "test_mode": 0
}

Get User Info

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.

Authorizations:
ApiKeyAuthuidKey
header Parameters
Authorization
required
string

User's token or API key

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "id": 0
}

Toggle Test Mode

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. Credit balances are checked but not deducted, and payments are authorized but not captured — any pending charge will drop off without posting.

Authorizations:
ApiKeyAuthuidKey
Request Body schema: application/json
required
test_mode
integer
Enum: 0 1

Responses

Request samples

Content type
application/json
{
  • "test_mode": 0
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "test_mode": 0
}

Log Out Deprecated

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.

Not applicable when using API key authentication.

Authorizations:
NoneApiKeyAuth
Request Body schema: application/json
uid
required
string

Responses

Request samples

Content type
application/json
{
  • "uid": "7f736a7b02bd460ca1953d926716bb51"
}

Cards

Cards

List Cards

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

Authorizations:
NoneApiKeyAuth
query Parameters
category_id
integer

Category ID

with_images
boolean
with_detailed_images
boolean
page
integer

page number, numeration starts with 0

lowres
boolean

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "cards": [
    ],
  • "pagination": {
    }
}

List Cards by Categories

Get a list of cards available to the user, grouped by categories.

Authorizations:
NoneApiKeyAuth
query Parameters
category_id
integer

Category ID

with_images
boolean
with_detailed_images
boolean
page
integer

page number, numeration starts with 0

lowres
boolean

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "cards": [
    ],
  • "discount": 0
}

Card Details

Get detailed information about a card.

Authorizations:
NoneApiKeyAuth
query Parameters
card_id
required
integer

Card ID

lowres
boolean

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "card": {
    }
}

List Categories

Get list of available card categories.

Authorizations:
NoneApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "categories": [
    ]
}

Orders

Order management

Single Step Order

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 page in your dashboard to generate one.

Authorizations:
NoneApiKeyAuth
Request Body schema: application/json
uid
string
Deprecated

Deprecated. Pass your API key in the Authorization header instead.

login
string
Deprecated

Deprecated. Use API key authentication instead.

password
string
Deprecated

Deprecated. Use API key authentication instead.

card_id
required
integer

Id of the card you want to send

denomination_id
integer

Optional. Use if sending a gift card

message
required
string

The body of the message. Use '\n' for new lines

wishes
string

The right-shifted closing part of the note

font_label
required
string

The colloquial name of the font, such as 'Fancy Jenna' or 'Casual David'

credit_card_id
integer

The credit card id to charge for the order.

insert_id
integer

Insert id for the order

couponCode
string

Coupon code

date_send
string

Send date

validate_address
boolean
delivery_confirmation
boolean

Request delivery confirmation for the order

webhook_url
string

Webhook URL

sender_first_name
string
sender_last_name
string
sender_address1
required
string
sender_address2
string
sender_city
required
string
sender_zip
required
string
sender_state
string

Required for US and Canada (country id 1 or 2)

sender_country_id
integer
Default: 1

1 (United States) by default

sender_country
string

United States by default

recipient_first_name
string
recipient_last_name
string
recipient_address1
required
string
recipient_address2
string
recipient_city
required
string
recipient_zip
required
string
recipient_state
string

Required for US and Canada (country id 1 or 2)

recipient_country_id
integer
Default: 1

1 (United States) by default

recipient_country
string

United States by default

client_metadata
string

Order metadata

Responses

Request samples

Content type
application/json
{
  • "uid": "dlqwjkqwdlkjqwdq09302184383",
  • "login": "john@jjf.com",
  • "password": "8yfqwiuy@!$",
  • "card_id": 3404,
  • "denomination_id": 12,
  • "message": "Dear Frank,\nThank you so much for your interest in our services.",
  • "wishes": "All the best,\nJoe",
  • "font_label": "Chill Charity",
  • "credit_card_id": 34124,
  • "insert_id": 0,
  • "couponCode": "string",
  • "date_send": "string",
  • "validate_address": true,
  • "delivery_confirmation": true,
  • "webhook_url": "string",
  • "sender_first_name": "string",
  • "sender_last_name": "string",
  • "sender_address1": "string",
  • "sender_address2": "string",
  • "sender_city": "string",
  • "sender_zip": "string",
  • "sender_state": "string",
  • "sender_country_id": 1,
  • "sender_country": "string",
  • "recipient_first_name": "string",
  • "recipient_last_name": "string",
  • "recipient_address1": "string",
  • "recipient_address2": "string",
  • "recipient_city": "string",
  • "recipient_zip": "string",
  • "recipient_state": "string",
  • "recipient_country_id": 1,
  • "recipient_country": "string",
  • "client_metadata": "string"
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "order_id": 196936,
  • "mail_sent": 0
}

Add Order to Basket

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.

Authorizations:
NoneApiKeyAuth
Request Body schema: application/json
uid
string
Deprecated

Deprecated. Pass your API key in the Authorization header instead.

card_id
integer

The ID of the card to send.

return_address_id
integer

If not provided, the account's default return address will be used.

address_id
integer
Deprecated

A single address id to send an order to. Alternatively, use an array of addresses.

address_ids
Array of integers

Required if addresses is not present

Array of objects

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.

font
string

font id

font_size
integer
auto_font_size
boolean
for_free
boolean
couponCode
string
denomination_id
integer
insert_id
integer
quantity
integer
Deprecated
check_quantity
boolean

check cards and inserts quantity in stock, return insufficient quantity error in case of low stock

delivery_confirmation
boolean

Request delivery confirmation for the order

client_metadata
string

Card metadata

Responses

Request samples

Content type
application/json
{
  • "uid": "string",
  • "card_id": 13,
  • "return_address_id": 0,
  • "address_id": 0,
  • "address_ids": [
    ],
  • "addresses": [
    ],
  • "font": "hwDavid",
  • "font_size": 13,
  • "auto_font_size": true,
  • "for_free": true,
  • "couponCode": "string",
  • "denomination_id": 0,
  • "insert_id": 0,
  • "quantity": 0,
  • "check_quantity": true,
  • "delivery_confirmation": true,
  • "client_metadata": "string"
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "order_id": 725563
}

Order Details

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).

Authorizations:
NoneApiKeyAuth
query Parameters
id
required
integer
Example: id=725563

Order id

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "order": {
    }
}

Cancel Order

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.

Authorizations:
NoneApiKeyAuth
Request Body schema: application/json
uid
string
Deprecated

Deprecated. Pass your API key in the Authorization header instead.

order_id
integer

The ID of the order to cancel.

Responses

Request samples

Content type
application/json
{
  • "uid": "string",
  • "order_id": 725563
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok"
}

Basket

Shopping basket

Send Basket

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.

Authorizations:
NoneApiKeyAuth
Request Body schema: application/json
uid
string
Deprecated

Deprecated. Pass your API key in the Authorization header instead.

couponCode
string
credit_card_id
integer

If provided, it is the id number of the credit card on file to be charged.

check_quantity
boolean

check cards and inserts quantity in stock, return insufficient quantity error in case of low stock

object

dictionary of order notes, order id is used as a key

object

Expected structure price by types of payment. If the structure does not match during the calculation, an error will be returned

Responses

Request samples

Content type
application/json
{
  • "uid": "string",
  • "couponCode": "string",
  • "credit_card_id": 344,
  • "check_quantity": true,
  • "notes": {
    },
  • "price_structure": {
    }
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "items": {
    }
}

Clear Basket

Removes all items from the basket. Returns the list of items that were cleared.

Authorizations:
NoneApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "item": [
    ]
}

Basket Item Count

Get the number of items in the user's basket.

Authorizations:
NoneApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "count": 11
}

Address Book

Address management

List Countries

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

Authorizations:
ApiKeyAuthuidKey

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "OK",
  • "countries": [
    ]
}

List States

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).

Authorizations:
ApiKeyAuthuidKey
query Parameters
country_id
required
integer
Example: country_id=1

Country ID. Use the List Countries endpoint to get available country IDs.

Responses

Response samples

Content type
application/json
{
  • "states": [
    ]
}

Add Recipient Address

Add a new recipient address to user's Address Book.

Authorizations:
ApiKeyAuthuidKey
Request Body schema: application/json
required
state
string
country_id
string
first_name
string
last_name
string
name
string
address1
string
address2
string
city
string
zip
string
birthday
string

Responses

Request samples

Content type
application/json
{
  • "state": "string",
  • "country_id": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "name": "string",
  • "address1": "string",
  • "address2": "string",
  • "city": "string",
  • "zip": "string",
  • "birthday": "string"
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "OK",
  • "address_id": 108926
}

Update Recipient Address

Update a recipient address in Address Book.

Authorizations:
ApiKeyAuthuidKey
Request Body schema: application/json
required
address_id
string

ID of the address in the address book. You can get it using List Recipient Addresses call.

state
string
country_id
string
first_name
string
last_name
string
name
string
business_name
string
address1
string
address2
string
city
string
zip
string
birthday
string

Responses

Request samples

Content type
application/json
{
  • "address_id": "string",
  • "state": "string",
  • "country_id": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "name": "string",
  • "business_name": "string",
  • "address1": "string",
  • "address2": "string",
  • "city": "string",
  • "zip": "string",
  • "birthday": "string"
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "OK",
  • "address_id": 108926
}

Delete Recipient Address

Authorizations:
ApiKeyAuthuidKey
Request Body schema: application/json
required
address_id
number
address_ids
Array of integers

Responses

Request samples

Content type
application/json
{
  • "address_id": 0,
  • "address_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "OK",
  • "address_id": 108926,
  • "address_ids": [
    ]
}

List Recipient Addresses

Get list of recipient addresses in user's Address Book.

Authorizations:
ApiKeyAuthuidKey

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "OK",
  • "addresses": [
    ]
}

Add Sender Address

Add a new sender address to user's Address Book.

Authorizations:
ApiKeyAuthuidKey
Request Body schema: application/json
required
default
boolean
name
string
first_name
string
last_name
string
business_name
string
address1
string
address2
string
city
string
state
string
zip
string
country_id
string

Responses

Request samples

Content type
application/json
{
  • "default": true,
  • "name": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "business_name": "string",
  • "address1": "string",
  • "address2": "string",
  • "city": "string",
  • "state": "string",
  • "zip": "string",
  • "country_id": "string"
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "OK",
  • "address": {
    }
}

Update Sender Address

Update a sender address in user's Address Book.

Authorizations:
ApiKeyAuthuidKey
Request Body schema: application/json
required
address1
string
address2
string
city
string
zip
string
state
string

Responses

Request samples

Content type
application/json
{
  • "address1": "string",
  • "address2": "string",
  • "city": "string",
  • "zip": "string",
  • "state": "string"
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "OK",
  • "addresses": [
    ]
}

Delete Sender Address

Delete a sender address from user's Address Book.

Authorizations:
ApiKeyAuthuidKey
Request Body schema: application/json
required
id
integer
address_ids
Array of integers

Responses

Request samples

Content type
application/json
{
  • "id": 0,
  • "address_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "OK"
}

List Sender Addresses

Authorizations:
ApiKeyAuthuidKey

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "OK",
  • "addresses": [
    ]
}

Default Sender Address Info

Get user's default sender address.

Authorizations:
ApiKeyAuthuidKey

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "OK",
  • "billing_info": {
    },
  • "subscription": {
    }
}

Set Default Sender Address

Set user's default sender address.

Authorizations:
ApiKeyAuthuidKey
Request Body schema: application/json
required
id
integer

Responses

Request samples

Content type
application/json
{
  • "id": 0
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "OK"
}

QR Codes

QR code management

List QR Codes

Get a list of QR Codes on the account.

Authorizations:
ApiKeyAuthuidKey

Responses

Response samples

Content type
application/json
{}

Create QR Code

Create a new QR Code.

Authorizations:
ApiKeyAuthuidKey
Request Body schema: application/json
name
string
url
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "id": 123
}

Delete QR Code

Delete a QR Code.

Authorizations:
ApiKeyAuthuidKey
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok"
}

QR Code Statistics

Get the statistics for the QR Codes on the account.

Authorizations:
ApiKeyAuthuidKey

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "scans": [
    ],
  • "recent_scans": [
    ],
  • "statistics": [
    ],
  • "total_links": 123,
  • "total_scans": 123,
  • "total_unique_scans": 123,
  • "total_pending_scans": 123
}

List QR Code Frames

Get a list of available QR Code frames.

Authorizations:
NoneApiKeyAuth

Responses

Response samples

Content type
application/json
{}

Prospecting

Outbound prospecting campaigns

Calculate Targets

Calculate targets for prospecting campaign.

Authorizations:
ApiKeyAuthuidKey
Request Body schema: application/json
type
string
Enum: "residential" "business"

Outbound prospecting type: residential or business.

address
string

Street address to serve as a central point for prospecting search.

city
string

Format: STATE;City

zip
string

Postal code

country
string

United States or Canada

radius
integer

Search radius in miles from the central point.

latitude
string

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.

longitude
string

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.

ownRent-d
string

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"

hinc-d
string

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"

worth-d
string

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"

Home-d
string

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"

resLen-d
string

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"

hAge
string

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"

people
string

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"

kids
string

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"

marital
string

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"

staff
string

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"

sale
string

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"

one
string
Enum: "0" "1"

Return all or one contact per business.

  • 0: Return all contacts
  • 1: Return one contact.
sic
string

Industry code for business search. Use dash to separate multiple codes, for example: "sic": "17-9999-729924"

Responses

Request samples

Content type
application/json
{
  • "type": "residential",
  • "address": "9280 South Kyrene Road",
  • "city": "AZ;Tempe",
  • "zip": "85284",
  • "country": "United States",
  • "radius": 5,
  • "latitude": "1",
  • "longitude": "1",
  • "ownRent-d": "",
  • "hinc-d": "",
  • "worth-d": "",
  • "Home-d": "",
  • "resLen-d": "",
  • "hAge": "",
  • "people": "",
  • "kids": "",
  • "marital": "",
  • "staff": "",
  • "sale": "",
  • "one": "",
  • "sic": ""
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "total_records": "string",
  • "mask": true
}

Preview Order

Preview prospecting campaign order pricing.

Authorizations:
ApiKeyAuthuidKey
Request Body schema: application/json
card_id
required
integer

ID of card

country
required
string

United States or Canada

insert_id
integer

ID of the insert

message
required
string

Handwrytten message on the card

must_deliver_by
string

Format: MM/DD/YYYY

records
required
integer

Number of cards to send

return_address_id
required
integer

ID of the return address

shipping_address_id
integer

ID of the shipping address

shipping_method_id
integer
Enum: 1 2 3 4 5 6

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
shipping_rate_id
integer
Enum: 1 2 3 4

Shipping rate.

  • 1: Ground
  • 2: 2-Day
  • 3: Overnight
  • 4: Overnight Priority

Responses

Request samples

Content type
application/json
{
  • "card_id": 60559,
  • "country": "United States",
  • "insert_id": null,
  • "message": "",
  • "must_deliver_by": "",
  • "records": 5,
  • "return_address_id": null,
  • "shipping_address_id": null,
  • "shipping_method_id": 1,
  • "shipping_rate_id": null
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "prices": {
    },
  • "quantity": 0
}

Create Order

Add prospecting campaign order to basket. Use Send Basket call to submit all orders in basket for processing.

Authorizations:
ApiKeyAuthuidKey
Request Body schema: application/json
address
string

Street address to serve as a central point for prospecting search.

city
string

Format: STATE;City

zip
string

Postal code

country
string

United States or Canada

radius
integer

Search radius in miles from the central point.

latitude
string

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.

longitude
string

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.

mask
boolean

If no data was found at the address, try searching by geodata

ownRent-d
string

Home ownership for residential search. Use dash to separate multiple values.

hinc-d
string

Household income for residential search. Use dash to separate multiple values.

worth-d
string

Net worth for residential search. Use dash to separate multiple values.

Home-d
string

Home value for residential search. Use dash to separate multiple values.

resLen-d
string

Length of residency for residential search. Use dash to separate multiple values.

hAge
string

Household age for residential search. Use dash to separate multiple values.

people
string

People in household for residential search. Use dash to separate multiple values.

kids
string

Children in household for residential search. Use dash to separate multiple values.

marital
string

Marital status for residential search. Use dash to separate multiple values.

card_id
required
integer

ID of card

insert_id
integer

ID of the insert

message
required
string

Handwrytten message on the card

wishes
string

Handwrytten signoff on the card

signature_id
integer

ID of the custom signature

signature2_id
integer

ID of the custom signature #2

search_value
string

Search value

must_deliver_by
string

Format: MM/DD/YYYY

records
required
integer

Number of cards to send

return_address_id
required
integer

ID of the return address

shipping_address_id
integer

ID of the shipping address

shipping_method_id
integer
Enum: 1 2 3 4 5 6

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
shipping_rate_id
integer
Enum: 1 2 3 4

Shipping rate.

  • 1: Ground
  • 2: 2-Day
  • 3: Overnight
  • 4: Overnight Priority
font
required
string

Handwriting font slug

font_size
integer

Font size

Responses

Request samples

Content type
application/json
{
  • "address": "9280 South Kyrene Road",
  • "city": "AZ;Tempe",
  • "zip": "85284",
  • "country": "United States",
  • "radius": 5,
  • "latitude": "1",
  • "longitude": "1",
  • "mask": true,
  • "ownRent-d": "",
  • "hinc-d": "",
  • "worth-d": "",
  • "Home-d": "",
  • "resLen-d": "",
  • "hAge": "",
  • "people": "",
  • "kids": "",
  • "marital": "",
  • "card_id": 60559,
  • "insert_id": null,
  • "message": "Hi {{firstname}},\n\nWelcome to the neighborhood!",
  • "wishes": "Best wishes,\nYour friendly realtor",
  • "signature_id": null,
  • "signature2_id": null,
  • "search_value": "string",
  • "must_deliver_by": "",
  • "records": 5,
  • "return_address_id": null,
  • "shipping_address_id": null,
  • "shipping_method_id": 1,
  • "shipping_rate_id": null,
  • "font": "hwBlaire",
  • "font_size": null
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "order_id": 0
}

Custom Cards

Upload Custom Image

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.

Authorizations:
NoneApiKeyAuth
Request Body schema: multipart/form-data
file
required
string <binary>
type
string
Enum: "logo" "cover"

The type of the image.

Responses

Response samples

Content type
application/json
{}

Check Image Quality

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.

Authorizations:
NoneApiKeyAuth
Request Body schema: application/json
image_id
required
integer
card_id
integer

Responses

Request samples

Content type
application/json
{
  • "image_id": 0,
  • "card_id": 0
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "warning": "This image may appear blurry as it is less than the recommended resolution.",
  • "error": "This image is less than recommended resolution. Please upload another image."
}

List Custom Images

List all custom images uploaded by the user.

Authorizations:
NoneApiKeyAuth
query Parameters
type
string
Enum: "logo" "cover"

The type of the image.

Responses

Response samples

Content type
application/json
{}

Delete Custom Image

Delete a custom uploaded image.

Authorizations:
NoneApiKeyAuth
Request Body schema: application/json
image_id
required
integer

Responses

Request samples

Content type
application/json
{
  • "image_id": 0
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok"
}

List Card Dimensions

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).

Authorizations:
NoneApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "dimensions": [
    ]
}

List Preset Cover Images

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.

Authorizations:
NoneApiKeyAuth
query Parameters
dimension_id
required
integer
Example: dimension_id=1

Card dimension ID. See /design/dimensions for available options.

Responses

Response samples

Content type
application/json
{}

Create Custom Card

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).

Instead of a custom uploaded cover, a preset cover can be used via preset_cover_id — see /cards/listPresetCovers for available presets.

To update an existing custom card, pass is_update: true along with the existing card_id.

The returned card_id can be used in orders like any other card.

Authorizations:
NoneApiKeyAuth
Request Body schema: application/json
card_id
integer

Required when updating an existing custom card (is_update: true). The ID of the card to update.

name
required
string

The name of the custom card.

dimension_id
integer

Card size and format. See /cards/listDimensions for available options.

is_update
boolean

Set to true to update an existing custom card. Must be combined with card_id.

cover_id
integer or null

ID of the uploaded cover image (type: cover) to use as the front of the card.

preset_cover_id
integer or null

ID of a preset cover to use instead of a custom uploaded image. See /cards/listPresetCovers.

cover_size_percent
integer
header_type
string
Enum: "text" "logo"

Whether the header uses text or a logo image. Foldable cards only.

header_text
string

Header text. Used when header_type is 'text'.

header_font_size
integer
header_font_color
string

Hex color code.

header_font_id
integer

Font ID for the header text. See /fonts/listForCustomizer.

header_align
string
Enum: "left" "center" "right"
header_logo_id
integer or null

ID of the logo image (type: logo) for the header. Used when header_type is 'logo'.

header_logo_size_percent
integer
footer_type
string
Enum: "text" "logo"

Whether the footer uses text or a logo image.

footer_text
string

Footer text. Used when footer_type is 'text'.

footer_font_size
integer
footer_font_color
string

Hex color code.

footer_font_id
integer

Font ID for the footer text. See /fonts/listForCustomizer.

footer_align
string
Enum: "left" "center" "right"
footer_logo_id
integer or null

ID of the logo image (type: logo) for the footer. Used when footer_type is 'logo'.

footer_logo_size_percent
integer
main_type
string
Enum: "text" "logo"

Content type for the inside top surface. Foldable cards only.

main_text
string

Inside top text. Used when main_type is 'text'.

main_font_size
integer
main_font_color
string

Hex color code.

main_font_id
integer

Font ID for the inside top text. See /fonts/listForCustomizer.

main_align
string
Enum: "left" "center" "right"
main_logo_id
integer or null

ID of the logo image (type: logo) for the inside top. Used when main_type is 'logo'.

main_logo_size_percent
integer
back_type
string
Enum: "text" "logo"

Content type for the back surface.

back_text
string

Back text. Used when back_type is 'text'.

back_font_size
integer
back_font_color
string

Hex color code.

back_font_id
integer

Font ID for the back text. See /fonts/listForCustomizer.

back_align
string
Enum: "left" "center" "right"
back_vertical_align
string
Enum: "top" "center" "bottom"
back_logo_id
integer or null

ID of the logo image (type: logo) for the back. Used when back_type is 'logo'.

back_size_percent
integer
back_cover_id
integer or null

ID of an uploaded cover image (type: cover) for the back surface.

preset_back_cover_id
integer or null

ID of a preset cover for the back surface. See /cards/listPresetCovers.

qr_code_id
integer

ID of the QR code to include. See /qrCode for available QR codes.

qr_code_size_percent
integer or null
qr_code_align
string
Enum: "left" "center" "right"
qr_code_location
string
Enum: "header" "footer"
qr_code_frame_id
integer or null

ID of the QR code frame. See /qrCode/frames for available frames.

Responses

Request samples

Content type
application/json
{
  • "card_id": 305578,
  • "name": "My Custom Card",
  • "dimension_id": 1,
  • "is_update": false,
  • "cover_id": 0,
  • "preset_cover_id": 0,
  • "cover_size_percent": 84,
  • "header_type": "text",
  • "header_text": "Header text",
  • "header_font_size": 16,
  • "header_font_color": "#000000",
  • "header_font_id": 1,
  • "header_align": "center",
  • "header_logo_id": 0,
  • "header_logo_size_percent": 50,
  • "footer_type": "text",
  • "footer_text": "footer text",
  • "footer_font_size": 16,
  • "footer_font_color": "#000000",
  • "footer_font_id": 1,
  • "footer_align": "center",
  • "footer_logo_id": 0,
  • "footer_logo_size_percent": 50,
  • "main_type": "logo",
  • "main_text": "string",
  • "main_font_size": 50,
  • "main_font_color": "#000000",
  • "main_font_id": 1,
  • "main_align": "left",
  • "main_logo_id": 0,
  • "main_logo_size_percent": 50,
  • "back_type": "logo",
  • "back_text": "123",
  • "back_font_size": 16,
  • "back_font_color": "#000000",
  • "back_font_id": 1,
  • "back_align": "center",
  • "back_vertical_align": "center",
  • "back_logo_id": 0,
  • "back_size_percent": 24,
  • "back_cover_id": 0,
  • "preset_back_cover_id": 0,
  • "qr_code_id": 234,
  • "qr_code_size_percent": 0,
  • "qr_code_align": "left",
  • "qr_code_location": "footer",
  • "qr_code_frame_id": 0
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "card_id": 305570,
  • "category_id": 27
}

Delete Custom Card

Deletes a custom card created by the user.

Authorizations:
NoneApiKeyAuth
Request Body schema: application/json
id
required
integer

ID of the custom card to delete.

Responses

Request samples

Content type
application/json
{
  • "id": 305578
}

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok"
}

Fonts

List Fonts

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.

Authorizations:
NoneApiKeyAuth

Responses

Response samples

Content type
application/json
{}

Gift Cards

List Gift Cards

Get list of gift cards and available denominations for purchase and inclusion in order.

Authorizations:
NoneApiKeyAuth

Responses

Response samples

Content type
application/json
{}

Inserts

List Inserts

Get list of custom inserts available for the account.

Authorizations:
NoneApiKeyAuth
query Parameters
include_historical
boolean

If true, includes inserts that are out of stock.

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "ok",
  • "inserts": [
    ]
}

Signatures

List Signatures

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.

Authorizations:
NoneApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "httpCode": 200,
  • "status": "OK",
  • "signatures": [
    ]
}