API DOCS

Thank you for your interest in the Handwrytten API! By using this API you will have full access to the same range of features found in our apps and website.

1.API Endpoint

The API can be found at: https://api.handwrytten.com/v1/

All commands listed in this API documentation refer to this base URL and build off it.  For example, the login command “auth/authortization” can be found at the endpoint: https://api.handwrytten.com/v1/auth/authorization

2.Profile Commands

2.1.Register

Description: Registers a new account.

Command: /auth/registration

Params:

Parameter Type Required? Example Description
login String Yes “user@example.com” The email address being registered as a new login ID
password String Yes “password” The password of the new account
fname String Yes “Joseph” The first name of the new user
lname String Yes “Smith” The last name of the new user
discount_code String No “Freebie123” A discount code to credit the account with upon signup

Returns on Success:

Parameter Value
Status OK
user_id

Throws:

‘ User exists’

Example:

{
"login": "penbot2000@handwrytten.com",
"password": "B33pB0pB33pB0p!",
"fname": "Penbot",
"lname": "2000",
"discount_code": "fake_discount_code"
}

2.2.Login

Description: Attempts to log in to an existing account

Command: auth/authorization

Params:

Parameter Type Required? Example Description
login String Yes “user@example.com” The email address used as the login ID
password String Yes “password” The password of the account

Returns on success:

Parameter Value
Status OK
user_id
uid
anet_customer_id
free_cards

Throws exceptions:

“Auth error”

“Banned”

“Not Activated”

“Database Error”

2.3.Reset Password

Description: Sends an email to the user to reset the password

Command: auth/resetPasswordRequest

Params:

Parameter Type Required? Example Description
login String Yes “user@example.com” The email address used as the login ID

Returns on Success:

Parameter Value
Status OK

On Failure:

Exceptions:

“login missing”

“No such user”

“banned”

“not activated”

“15 minute interval”

“cannot send email”

2.4.Change Password

Description: Attempts to change the user’s password

Command:  profile/changePassword

Params:

Parameter Type Required? Example Description
old_password String Yes “password” The user’s existing password
new_password String Yes “drowssap” The new password for the account
uid String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the currently logged in user

Returns On Success:

Parameter Value
Status OK

Throws exceptions:

“enter old password”

“enter new password”

“not using password”

2.5.Logout

Description: Logs the user out of the system

Command: profile/logout

Params:

Parameter Type Required? Example Description
uid String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the currently logged in user

Return on Success:

Parameter Value
Status OK

3.Card Commands

3.1.List Card Categories

Description: Returns an array of the card categories

Command: /categories/list

Params:

Parameter Value
UID the UID of the logged in user

Returns:

Parameter Value
Status OK
Categories array

category 1
category 2

3.2.List Cards

Description: Lists cards matching an optionally specified card category or all card categories

Command: /cards/list

Params:

 

Parameter Type Required? Example Description
UID string no 1ajshkjh19817291872d98hjkadsh7ysasd The UID of the currently logged in user.  If not set, only global cards will be returned.

Returns:

Parameter Value
Status OK
cards

 

Array

id
name
cover
cover_width
cover_height
price
category_id
available_free
orientation

Throws:

‘category id error’

3.3.Card Details

Description: Returns all card images and a description of the card

Command: /cards/view

Params:

Parameter Type Required? Example Description
UID

 

string no 1hkjdhuhc8271973be12bjdh12 The UID of the logged in user.  Without it, only publicly available cards will be returned.
card_id

 

int Yes 1 The id of the card to pull details on
lowres

 

int No 0 Set to 1 to request lowres images

Returns:

Parameter Value
Status OK
card

 

Array

id
name
cover
price
category_id
available_free
orientation
description
width
height
images

front

array

image
back

array

image
inside

array

image
envelope

array

image

4.Gift Card Commands

4.1.Card Details

Description: Returns images and details (and associated denominations) of all gift cards

Command: /giftCards/list

Params: None

Returns:

Parameter Value
Status OK
cards

 

Array

id
name
image
denominations

array

id
nominal
price

5.Template Commands

5.1.List Categories

Description

Command: /templateCategories/list

Params: 

Parameter Type Required? Example Description
UID

 

string no 1hkjdhuhc8271973be12bjdh12 The UID of the logged in user.  Without it, only publicly available template categories will be returned.

Returns:

On Success:

Array:

Parameter Value
Status OK
categories

 

Array

id 1
name Love Letter

5.2.List Templates

Description: Lists all of the templates, optionally filtered by category

Command: /templates/list

Params:

Parameter Type Required? Example Description
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user
category_id

 

int No 1 Optional.  The filter for categories. Default to 0

Returns:

On Success:

Array:

Parameter Value
status OK
templates

 

Array

id 1
category_id 1
name Love Letter1
message Oh how I love you…

5.3.Template Details

Description: Get all info on a template

Command: /templates/view

Params:

Parameter Type Required? Example Description
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user
template_id

 

int Yes 1 The template you are pulling

Returns On Success:

Parameter Value
Status OK
Template

 

Array

id 1
category_id 1
name
message

Throws:

‘template id error’

‘access denied’

‘no such template’

5.4.Create Template

Description: Creates a new template for the user

Command: /templates/create

Params:

Parameter Type Required? Example Description
name

 

String Yes “FollowUp” The name of the template
message String Yes “This is the body of the messag” The actual message in the template
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user

Returns on Success:

Parameter Value
status OK
template_id

 

id  of template

Throws:

‘name error’

‘message error’

‘error saving template’

5.5.Update Template

Description: Updates an Existing Template in the User’s Account

Command: /templates/update

Params:

Parameter Type Required? Example Description
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user
template_id Int Yes 1 The id of the template to update
name

 

String Yes “FollowUp” The name of the template
message String Yes “This is the body of the messag” The actual message in the template

Returns on Success:

Parameter Value
status OK
template

 

array

id
category_id
name
message

Throws:

‘nothing to update’

‘no such template’

‘access denied’

‘template id error’

5.6.Delete Template

Description: Deletes an Existing Template in the User’s Account

Command: /templates/delete

Params:

Parameter Type Required? Example Description
template_id Int Yes 1 The id of the template to delete
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user

Returns on Success:

Parameter Value
status OK

Throws:

‘template id error’

‘no such template’

‘access denied’

6.Credit Card Commands

This section covers listing a deleting credit cards from a user’s account.

Please note: for security reasons, credit cards can only be added via Handwrytten.com, or official Handwrytten apps including iPhone, Android and Salesforce.com

6.1.List Credit Cards

Description: Lists Descriptions of Existing Credit Cards in the User’s Account

Command: /api/creditCards/list

Params:

Parameter Type Required? Example Description
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user

Returns on Success:

Parameter Value
status OK
credit_cards array

id the credit card id
anet_profile_id internal to Handwrytten.  Please ignore
type the type of credit card
card_number the last 4 digits of the number
expiration_date the expiration date
discount_credit Any discount credits on the account

7.Country Commands

Handwrytten now supports international orders.  As such, an optional “Country ID” can be included with addresses.  To get a list of country IDs, please use the “Countries/List” command.

7.1.List Countries

Description: Lists the countries Handwritten can mail to, and their associated country ID:

Command: /countries/list

Returns:  Array of countries, and the additional delivery cost of each.

{"countries":
  [
     {"id":"1","name":"United States","delivery_cost":"0.00","aliases":"USA\nU.S.A.\nUnited States of America"},
     {"id":"2","name":"Canada","delivery_cost":"1.00","aliases":""},
     {"id":"3","name":"Mexico","delivery_cost":"1.00","aliases":"MX"},
     {"id":"4","name":"United Kingdom","delivery_cost":"1.00","aliases":"U.K.\nEngland"},
     {"id":"5","name":"Australia","delivery_cost":"1.00","aliases":""},
     {"id":"6","name":"New Zealand","delivery_cost":"1.00","aliases":""},
     ...
  }
}

8.User Address Commands

8.1.Get User Address

Description: Gets the user’s address (return address)

Command: /profile/address

Params:

Parameter Type Required? Example Description
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user

Returns on Success:

Parameter Value
status OK
address array

name
business_name
address1
address2
city
state
zip

OR NULL

Throws: none

8.2.Update User Address

Description: Updates the user’s address (return address)

Command: /api/profile/updateAddress

Params:

Parameter Type Required? Example Description
name String Yes “Joe Smith”
business_name String No “Acme Anvils”
address1 String Yes “123 Main Street”
address2 String No “Suite 123”
city String Yes “Chicago”
state String Yes “IL”
zip String Yes “60657”
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user

Returns on Success:

Parameter Value
status OK

Throws:

‘name error’

‘address1 error’

‘city error’

‘state error’

‘zip error’

9.Recipient Address Commands

9.1.List Recipient Addresses

Description: Gets the list of recipients of a user

Command: /api/profile/recipientsList

Params:

Parameter Type Required? Example Description
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user

Returns on Success:

Parameter Value
status OK
address array of

id
name
business_name
address1
address2
city
state
zip

Throws: nothing

9.2.Add Recipient Address

Description: Add a new name to the user’s recipient list

Command: /api/profile/addRecipient

Params:

Parameter Type Required? Example Description
name String Yes “Joe Smith”
business_name String No “Acme Anvils”
address1 String Yes “123 Main Street”
address2 String No “Suite 123”
city String Yes “Chicago”
state String Yes “IL”
zip String Yes “60657”
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user

Returns on Success:

Parameter Value
status OK

Throws:

‘name error’

‘address1 error’

‘city error’

‘state error’

‘zip error’

9.3.Delete Recipient Address

Description: Deletes a recipient

Command: /api/profile/deleteRecipient

Params:

Parameter Type Required? Example Description
address_id Int Yes 1
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user

Returns on Success:

Parameter Value
status OK
address array of

id
name
address1
address2
city
state
zip

Throws: nothing

9.4.Update Recipient Address

Description: Update an existing address in the user’s recipient list

Command: /api/profile/updateRecipient

Params:

Parameter Type Required? Example Description
address_id Int Yes 1 The id of the address to remove
name String Yes “Joe Smith”
business_name String No “123 Main Street”
address1 String Yes “123 Main Street”
address2 String No “Suite 123”
city String Yes “Chicago”
state String Yes “IL”
zip String Yes “60657”
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user

Returns on Success:

Parameter Value
status OK
address_id

Throws:

‘address_id error;

‘name error’

‘address1 error’

‘city error’

‘state error’

‘zip error’

10.Order Commands

10.1.New Order

Description: Creates an order in the system.  It won’t be shipped until “Process Order” is called

Command:  /api/orders/place                       

Params:

Parameter Type Required? Example Description
card_id Int Yes 1 The id of the card being used
denomination_id Int No 1 The id of the gift card denomination (if used).  Defaults to 0 for no gift card
address_id Int Yes 3 The address to send the card to
message String Yes “Hello this is the text of the card” The message of the card
font String Yes “astDunn” Can be “astDunn” (Casual David), “astMensikTom (Messy Michael), “astUribe” (Fancy Jenna)
for_free Int No 1 Set to 1 if the card should be sent for free, defaults to 0
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user

Returns on Success:

Parameter Value
status OK
order_id

Throws:

‘no such card’

‘card is not available for free’

‘no free cards’

‘cannot buy’

‘no such gift card’

‘no return info’

‘no such address’

‘error placing order’

‘error placing order (saving to address)’

10.2.Process Order

Description: Processes an existing new order

Command:  /api/orders/pay

Params:

Parameter Type Required? Example Description
order_id Int Yes 1 The id of the order being processed
credit_card_id Int Yes 1 The id of the credit card
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user

Returns on Success:

Parameter Value
status OK

Throws:

‘error processing payment’

10.3.List Past Orders

Description: Lists old orders placed by the user

Command: api/orders/list

Params:

Parameter Type Required? Example Description
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user

Returns on Success:

Parameter Value
status OK
orders array

id
for_free
date_created
message
card

id
name
cover
price
cover_id

address_from

name
address1
address2
city
state
zip

address_to

name
address1
address2
city
state
zip

denomination

giftcard_id
name
image
denomination

Throws: none

10.4.Single Step Order

Description: Send a new order to a new recipient in one single step

Command: api/orders/singleStepOrder

Params:

Parameter Type Required? Example Description
uid

 

String Yes “33ce76fede1a31d5ee823179f78d9882” The UID of the logged in user
card_id Int Yes 1 The id of the card being used
denomination_id Int No 1 The id of the gift card denomination (if used).  Defaults to 0 for no gift card
message String Yes “Hello this is the text of the card” The message of the card
font_label String Yes “Fancy Jenn” Can be “Casual David” or any other font listed on site.  Please note this is the LABEL and different from other API calls
sender_name String Yes “Joe Smith”
sender_business_name String No “Joe Smith”
sender_address1 String Yes “123 Main Street”
sender_address2 String No “Suite 123”
sender_city String Yes “Chicago”
sender_state String Yes “IL”
sender_zip String Yes “60657”
recipient_name String Yes “Joe Smith”
recipient_business_name String No “Joe Smith”
recipient_address1 String Yes “123 Main Street”
recipient_address2 String No “Suite 123”
recipient_city String Yes “Chicago”
recipient_state String Yes “IL”
recipient_zip String Yes “60657”
credit_card_id Int Yes

Returns on Success:

Parameter Value
status OK
orders array

id
for_free
date_created
message
card

id
name
cover
price
cover_id

address_from

name
address1
address2
city
state
zip

address_to

name
address1
address2
city
state
zip

denomination

giftcard_id
name
image
denomination

Throws:

‘no such card’

‘card is not available for free’

‘no free cards’

‘cannot buy’

‘no such gift card’

‘no return info’

‘no such address’

‘error placing order’

‘error placing order (saving to address)’

Suggest Edit

© 2018 Handwrytten    |    5150 N. 16th St., Suite B-146, Phoenix, AZ 85016    |    +1 (888) 284-5197    |    contact@handwrytten.com

Google Play and the Google Play logo are trademarks of Google LLC.