INTRODUCTION

Welcome to the Sparky API!

If you’re looking to integrate your application with Sparky services or create your own application in concert with data inside of Sparky, you’re in the right place. We’re happy to have you!

License

This API and API documentation are a product produced by Copywell, all rights reserved 2021.

API Access Tokens

Sparky API is currently operating in a beta capacity, and as a result API keys are not yet publicly available. If you wish to request one, please email your Copywell Respresentative.

Looking for access? Please submit your information below and we will be in touch.


MAKING REQUESTS

All URL endpoints start with https://sparkystudio.com/api/v1/ URLs are HTTPS only.

To make any request against the API, use your client ID in the URL as such, replacing the 9999 placeholders to form something like. https://sparkystudio.com/api/v1/9999/fulfillment

You will also be provided an authorization token that will need to be passed in the header information of your request.

Example using cURL
curl --location --request POST 'https://sparkystudio.com/api/v1/9999/fulfillment' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
     --data-raw '{}'

API ENDPOINTS

Production

https://sparkystudio.com/api/v1/


Sandbox

https://sparkystudio.com/apitest/v1/

Use this URL to test your api submissions. Fulfillment data is saved, and retrievable but nothing will be shipped. However, your submissions to this URL will not be viewable on the frontend of your customer web portal.

POST

/ fulfillment

POST /fulfillment with the required parameters (see example) to create a new fulfillment request in our system.

When you have a delivery that needs to be made, you can use this endpoint to submit the address and item information to us.

Example JSON Request
{
    "delivery_service_option": "FEDEX_OVER",
    "fedex_collect_account": "XXXXXX",
    "sales_order_num": "XXXXXX",
    "purchase_order_num": "XXXXXXXX",
    "to_address": {
        "name":         "John Smith",
        "company":      "Company X",
        "phone":        "111-111-1111",
        "email":        "john.smith@company.com",
        "address_1":    "120 Evansbrooke Landing NW",
        "address_2":    "Unit 12",
        "city":         "Calgary",
        "postal_zip":   "T3P 1G5",
        "state_iso2":   "AB",
        "country_iso2": "CA"		
    },
    "items": [
        {
            "name":     "My Product",
            "quantity": 1
        }
    ]
}

Parameter Requirements:

Review the table below to ensure you are submitting data correctly.

DATA TYPE PARAMETER REQUIREMENT NOTES
STRING delivery_service_option Required Must be one of the following:
CANPOST_EXPEDITED FEDEX_ECON FEDEX_OVER FEDEX_GROUND FEDEX_INTLECON CHITCHAT_CP UPS_STANDARD UPS_EXPEDITED UPS_EXPRESSEARLY UPS_EXPRESS UPS_EXPRESSSAVER FEDEX_2DAY PICKUP
STRING | NULL fedex_collect_account Optional
STRING | NULL sales_order_num Optional
STRING | NULL purchase_order_num Optional
OBJECT to_address Required
STRING name Conditional NAME or COMPANY must be provided.
STRING company Conditional NAME or COMPANY must be provided.
STRING | NULL phone Optional
STRING | NULL email Optional
STRING address_1 Required
STRING | NULL address_2 Optional
STRING city Required
STRING postal_zip Required
STRING | NULL state_iso2 Optional

If country is United States or Canada, you must provide this value in the 2 digit code format.

See ISO2 format for more information.
STRING country_iso Required

Must be in 2 digit code format.

See ISO2 format for more information.
ARRAY items Required
STRING name Required
STRING | INT quantity Required

GET

/ fulfillment/(ORDER_ID)

GET /fulfillment(ORDER_ID) will retrieve a specfic fulfillment order's details.

You will need to pass the specific order id with this endpoint. Order ID is originally returned when creating a fulfillment order, but it is also returned when calling /Fulfillment.

GET

/ fulfillments/(DATE?)

GET /fulfillments will retrieve an array of all your api fulfillments currently in our system.

You have the option of include a date in the URL in order to retrieve fulfillments from that day. Otherwise, with not date passed it will return fulfillments of the current day.


Notes:

  • Your date should be passed in the following format: YYYY-MM-DD

GET

/ fulfillments/returns/(DATE)

GET /fulfillments/returns will retrieve an array of all your fulfillment returns for a time period.

You must pass in a date value, the api will pass back all returns for that specific month.


Notes:

  • This passed date should follow the following notation: YYYY-MM-DD
Shopping Basket