API & Automation

1. API Endpoint

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

All endpoints listed in this documentation refer to this base URL and build off it. For example, the orders endpoint "orders" can be found at the endpoint: https://api.simplynoted.com/api/orders

2. Authentication

2.1. Retrieve Auth Token

Description: Simply Noted uses API keys as bearer tokens to allow access to the API. You can request an API key from support, support@simplynote.com, or you can get a token from the Account page under "Account Details". Simply Noted expects for the API key to be included in all API requests to the server in a header that looks like the following: Authorization: Bearer TOKEN

3. Users

3.1. Create A User

Description: Users are created through the Simply Noted website. To create an account go to https://simplynoted.com/account/register.

4. Products

4.1. Get All Products

Description: This endpoint gets all products and returns the id, title, and image URL.

Endpoint: /products

Method: GET

Headers:

Name	Value	Required?
Content-Type	application/json	Yes
Authorization	Bearer TOKEN_HERE	Yes

Returns on success:

{
"result": [
{
  "id": 4392451768425,
  "title": "Cactus Thank you",
  "image": "https://cdn.shopify.com/s/files/1/0275/6457/2777/products/Cactus-Thank-You.jpg?v=1574659292"
},
{
  "id": 4392452522089,
  "title": "Cactus Thanks So Much",
  "image": "https://cdn.shopify.com/s/files/1/0275/6457/2777/products/Cactus-Thanks-So-Much.jpg?v=1574659363"
},
{
  "id": 4442013139049,
  "title": "Dark Red Holiday Card",
  "image": "https://cdn.shopify.com/s/files/1/0275/6457/2777/products/Red.HolidayCard.jpg?v=1576524937"
}
],
"errors": []
}

5. Orders

5.1. Create An Order

Description: This endpoint creates an Order. If any required properties are missing an error will be returned.

Endpoint: /orders

Method: POST

Headers:

Name	Value	Required?
Content-Type	application/json	Yes
Authorization	Bearer TOKEN_HERE	Yes

Body:

Key	Type	Required?	Example
productId	String	Yes	"4392452522089"
handwritingStyle	String	Yes	"Tarzan"
customMessage	String	Yes	"This is my custom message"
shippingDate	String	No	"01/01/2020"
templateId	String	No	"12923422089"
returnAddressId	String	No	"ID_OF_RETURN_ADDRESS"
returnAddress	Object<Return Object>	Yes	See Below
recipientData	Array<Recipient Object>	Yes	See Below

Recipient Object:

Key	Type	Required?	Example
First Name	String	No	"John"
Last Name	String	No	"Appleseed"
Email	String	No	"john@simplynoted.com"
Phone	String	No	"+15555551234"
Address	String	Yes	"123 S Street"
Address 2	String	No	"Suite 100"
City	String	Yes	"Metropolis"
State	String	Yes	"Smallville"
Zip	String	Yes	"12345"
Company	String	No	"ACME, Inc."
Custom 1	String	No	"My custom value"
Custom 2	String	No	"Another Ccustom value"
Custom 3	String	No	"And A third"

Return Object:

Key	Type	Required?	Example
firstName	String	Yes	"John"
lastName	String	Yes	"Appleseed"
businessName	String	No	"ACME Inc"
address1	String	Yes	"123 W Elm Street"
address2	String	No	"Unit 123"
city	String	Yes	"Metropolis"
state	String	Yes	"Texas"
zip	String	Yes	"12345"
country	String	Yes	"United States"

Returns on success:

{
"result": "Order created.",
"errors": []
}

Example:

{
"productId": "ID_OF_PRODUCT_YOU_ARE_ORDERING",
"handwritingStyle": "Tarzan",
"customMessage": "This is my custom message",
"shippingDate": "",
"templateId": "ID_OF_THE_TEMPLATE_YOU_WANT_TO_USE",
"recipientData": [
{
  "First Name": "John",
  "Last Name": "Appleseed",
  "Address": "123 S Street",
  "Address 2": "",
  "City": "Metropolis",
  "State": "Smallville",
  "Zip": "12345",
  "Phone": "+15555551234",
  "Email": "john@simplynoted.com",
  "Company": "ACME, Inc.",
  "Custom 1": "",
  "Custom 2": "",
  "Custom 3": "",
}
]
}

6. Payments

Please Note: For security reasons you cannot create or store cedit cards from the Simply Noted API. Credit cards can only be added via SimplyNoted.com. You can set up your stored credit card on your user's account page. https://simplynoted.com/account

To receive bulk discounts and a smoother checkout process please purchase Simply Noted Credits. These credits will be used for purchases made via API with stored credit card information referenced as a fallback when no credits are available. Simply Noted Credits can be purchased HERE.

6.1. Get All Stored Credit Cards

Description: This endpoint retrieves all credit cards stored on your account.

Endpoint: /creditcards

Method: GET

Headers:

Name	Value	Required?
Content-Type	application/json	Yes
Authorization	Bearer TOKEN_HERE	Yes

Returns on success:

{
"result": [
{
  "_id": "4c1aa14ca35a0f00179355b0",
  "cardData": {
    "card_brand": "VISA",
    "last_4": "1111",
    "exp_month": 11,
    "exp_year": 2021,
    "cardholder_name": "Jane Doe",
    "billing_address": {
      "postal_code": "85251",
      "country": "US"
    }
  },
  "updated": "2020-01-12T04:32:12.846Z",
  "created": "2020-01-12T04:32:12.846Z"
}
],
"errors": []
}

7. Templates

7.1. Create A Template

Description: This endpoint creates a Template. If any required properties are missing an error will be returned.

Endpoint: /templates

Method: POST

Headers:

Name	Value	Required?
Content-Type	application/json	Yes
Authorization	Bearer TOKEN_HERE	Yes

Body:

Key	Type	Required?	Example
productId	String	Yes	"4392452522089"
handwritingStyle	String	Yes	"Tarzan"
customMessage	String	Yes	"This is my custom message"

Returns on success:

{
"result": {
"_id": "5e1b61a80d9234514cb1e983a",
"productId": "4460979552361",
"handwritingStyle": "Tarzan",
"customMessage": "This is my custom message",
"ownerId": "5e1a6f1d63458234017a962a3",
"updated": "2020-01-01T00:00:00.000Z",
"created": "2020-01-01T00:00:00.000Z",
"__v": 0
},
"errors": []
}

Example:

{
"productId": "4460979552361",
"handwritingStyle": "Tarzan",
"customMessage": "This is my custom message"
}

7.2. Retrieve All Templates

Description: This endpoint gets all Templates.

Endpoint: /templates

Method: GET

Headers:

Name	Value	Required?
Content-Type	application/json	Yes
Authorization	Bearer TOKEN_HERE	Yes

Returns on success:

{
"result": [
{
  "_id": "5e1b5123fe1a7f10021c2b04",
  "productId": "4460979552361",
  "handwritingStyle": "Tarzan",
  "customMessage": "This is my custom message",
  "ownerId": "5e1a6f1d616d871237a962a3",
  "updated": "2020-01-12T18:00:25.020Z",
  "created": "2020-01-12T18:00:25.020Z",
  "__v": 0
},
{
  "_id": "5e1b61a80d92f711231e983a",
  "productId": "4460979552361",
  "handwritingStyle": "Tarzan",
  "customMessage": "This is my custom message 2",
  "ownerId": "5e1a6f1d616d871237a962a3",
  "updated": "2020-01-12T18:12:56.945Z",
  "created": "2020-01-12T18:12:56.945Z",
  "__v": 0
}
],
"errors": []
}

7.3. Retrieve A Single Template

Description: This endpoint gets a single Template.

Endpoint: /templates/:templateId

Method: GET

Headers:

Name	Value	Required?
Content-Type	application/json	Yes
Authorization	Bearer TOKEN_HERE	Yes

URL Parameters:

Parameter	Type	Required?	Example
templateId	String	Yes	"5e1b5123fe1a7f10021c2b04"

Returns on success:

{
"result": {
"_id": "5e1b5123fe1a7f10021c2b04",
"productId": "4460979552361",
"handwritingStyle": "Tarzan",
"customMessage": "This is my custom message",
"ownerId": "5e1a6f1d616d871237a962a3",
"updated": "2020-01-12T18:00:25.020Z",
"created": "2020-01-12T18:00:25.020Z",
"__v": 0
},
"errors": []
}

7.4. Update A Template

Description: This endpoint updates a Template. If any required properties are missing an error will be returned.

Endpoint: /templates/:templateId

Method: PUT

Headers:

Name	Value	Required?
Content-Type	application/json	Yes
Authorization	Bearer TOKEN_HERE	Yes

URL Parameters:

Parameter	Type	Required?	Example
templateId	String	Yes	"5e1b5123fe1a7f10021c2b04"

Body:

Key	Type	Required?	Example
productId	String	Yes	"4392452522089"
handwritingStyle	String	Yes	"Stitch"
customMessage	String	Yes	"This is my custom message"

Returns on success:

{
"result": {
"productId": "4392452522089",
"handwritingStyle": "Stitch",
"customMessage": "This is my custom message"
},
"errors": []
}

Example:

{
"productId": "4392452522089",
"handwritingStyle": "Stitch",
"customMessage": "This is my custom message"
}

8. Addresses

8.1. Create An Address

Description: This endpoint creates an Address. If any required properties are missing an error will be returned.

Endpoint: /addresses

Method: POST

Headers:

Name	Value	Required?
Content-Type	application/json	Yes
Authorization	Bearer TOKEN_HERE	Yes

Body:

Key	Type	Required?	Example
firstName	String	Yes	"Johnny"
lastName	String	Yes	"Appleseed"
businessName	String	No	"ACME Inc"
address1	String	Yes	"123 S Maple Street"
address2	String	No	"Unit 123"
city	String	Yes	"Metropolis"
state	String	Yes	"Texas"
zip	String	Yes	"12345"
country	String	Yes	"United States"
type	String	Yes	"recipient" OR "return"

Returns on success:

{
  "result": {
    "_id": "5ea1101e9680607558e3ff77",
    "firstName": "Johnny",
    "lastName": "Appleseed",
    "businessName": "ACME Inc",
    "address1": "123 S Maple Street",
    "address2": "Unit 123",
    "city": "Metropolis",
    "state": "Texas",
    "zip": "12345",
    "country": "United States",
    "type": "return"
  },
  "errors": []
}

Example:

{
  "firstName": "Johnny",
  "lastName": "Appleseed",
  "businessName": "ACME Inc",
  "address1": "123 S Maple Street",
  "address2": "Unit 123",
  "city": "Metropolis",
  "state": "Texas",
  "zip": "12345",
  "country": "United States",
  "type": "return"
}

8.2. Retrieve All Addresses

Description: This endpoint gets all Addresses.

Endpoint: /addresses

Method: GET

Headers:

Name	Value	Required?
Content-Type	application/json	Yes
Authorization	Bearer TOKEN_HERE	Yes

URL Parameters:

Name	Type	Value	Required?
type	String	"return" OR "recipient"	No

Returns on success:

{
"result": [
{
  "_id": "5ea1101e9680607558e3ff77",
  "firstName": "Johnny",
  "lastName": "Appleseed",
  "businessName": "ACME Inc",
  "address1": "123 S Maple Street",
  "address2": "Unit 123",
  "city": "Metropolis",
  "state": "Texas",
  "zip": "12345",
  "country": "United States",
  "type": "return"
}
],
"errors": []
}

8.3. Retrieve A Single Address

Description: This endpoint gets a single address.

Endpoint: /addresses/:addressId

Method: GET

Headers:

Name	Value	Required?
Content-Type	application/json	Yes
Authorization	Bearer TOKEN_HERE	Yes

URL Parameters:

Parameter	Type	Required?	Example
addressId	String	Yes	"5ea1101e9680607558e3ff77"

Returns on success:

{
"result": {
  "_id": "5ea1101e9680607558e3ff77",
  "firstName": "Johnny",
  "lastName": "Appleseed",
  "businessName": "ACME Inc",
  "address1": "123 S Maple Street",
  "address2": "Unit 123",
  "city": "Metropolis",
  "state": "Texas",
  "zip": "12345",
  "country": "United States",
  "type": "return"
},
"errors": []
}

8.4. Update An Address

Description: This endpoint updates an address. If any required properties are missing an error will be returned.

Endpoint: /addresses/:addressId

Method: PUT

Headers:

Name	Value	Required?
Content-Type	application/json	Yes
Authorization	Bearer TOKEN_HERE	Yes

URL Parameters:

Parameter	Type	Required?	Example
addressId	String	Yes	"5ea1101e9680607558e3ff77"

Body:

Key	Type	Required?	Example
firstName	String	Yes	"Johnny"
lastName	String	Yes	"Appleseed"
businessName	String	No	"ACME Inc"
address1	String	Yes	"123 S Maple Street"
address2	String	No	"Unit 123"
city	String	Yes	"Metropolis"
state	String	Yes	"Texas"
zip	String	Yes	"12345"
country	String	Yes	"United States"
type	String	Yes	"recipient" OR "return"

Returns on success:

{
"result": {
  "_id": "5ea1101e9680607558e3ff77",
  "firstName": "Johnny",
  "lastName": "Appleseed",
  "businessName": "ACME Inc",
  "address1": "123 S Maple Street",
  "address2": "Unit 123",
  "city": "Metropolis",
  "state": "Texas",
  "zip": "12345",
  "country": "United States",
  "type": "return"
},
"errors": []
}

Example:

{
  "firstName": "Johnny",
  "lastName": "Appleseed",
  "businessName": "ACME Inc",
  "address1": "123 S Maple Street",
  "address2": "Unit 123",
  "city": "Metropolis",
  "state": "Texas",
  "zip": "12345",
  "country": "United States",
  "type": "return"
}

8.5. Delete A Single Address

Description: This endpoint deletes a single address.

Endpoint: /addresses/:addressId

Method: DELETE

Headers:

Name	Value	Required?
Content-Type	application/json	Yes
Authorization	Bearer TOKEN_HERE	Yes

URL Parameters:

Parameter	Type	Required?	Example
addressId	String	Yes	"5ea1101e9680607558e3ff77"

Returns on success:

{
  "result": {
    "deletedCount": 1
  },
  "errors": []
}

9. Available Handwriting Styles

9.1. Examples

Description: Below you can preview the available handwriting styles that can be leveraged by the API.

Tarzan: