Introduction

The PowerTool Safe API use REST. Our API has predictable URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Your developer account includes a two keys: sandbox and production. These keys serve as both authentication and to which system your request will be routed. The sandbox does not affect your live data or interact with other networks.

API Keys

The API uses keys to authenticate requests. You can view and manage your API keys in the Dashboard.

Test keys have the prefix test_ and live keys have the prefix live_. Keep your keys secure! They would allow someone to create accounts on your behalf and make updates to your customer's tools. For instance, not make javascript calls to the API from your client browser code as this would make them visible to any user with the ability to look at the page source code. You definitely don't want to share them on GitHub!

Authentication is performed with every request via your key as a parameter. All requests must be via https and http calls will fail. Calls without authentication will also fail.

Error Handling

The API uses standard HTTP response codes for error handling. Responses may also include attributes that further explain the error.

200 - OK
No errors
400 - Bad Request
The request was not acceptable. In the case of a missing field, check the returned JSON for more info.
401 - Unauthorized
A valid API key was not provided.
402 - Request Failed
A valid request, but failed. Check the response attributes.
403 - Forbidden
Access denied for this request.
404 - Not Found
Requested item doesn't exist. Check the response attributes.
409 - Conflict
The request conflicts with another request.
429 - Too Many Requests
Too many requests hit the API too quickly. The API is throttled to 6 calls/minute. Contact us if you need more.
500, 502, 503, 504 - Server Errors
Something went wrong on the server. Don't worry, we monitor the error logs and we'll get it resolved.

Verbs and Parameters

Verbs such as GET/POST/DELETE are used to determine the action to take on the endpoints.

Parameters are passed via a json payload named "payload". Images are passed as Base64 strings within the payload. An exception to data that is stored in the payload is the api key. This will always be a parameter named "key".

When the attributes of the documented payloads have been indented, that indicates a nested array of attributes within the attribute above.

For GET requests the payload can be sent as a parameter on the URL as in /some_call?payload={...}&key=test_mykey, where for POST use the data in the request body of payload={...} and key=mykey

Endpoints

Preface all endpoint requests with https://powertoolsafe.com/api/v1. As we move to future versions of the API the version number will change, but calls to a previous version will be supported.

Customer

A customer is an end user in the PowerTool Safe system. They are identified by an email address.

To process a transaction for a customer, a typical flow would be:

  • 1 - Check to see if the customer exists with GET /customer/{email}
  • 2 - If it doesn't exist (a 404 status is returned), add it with POST /customer
  • 3 - Add the tools and receipts for that customer with POST /transaction

Payload Attributes

  • email - The email address of the user.
  • type - The type of the user (construction, homeowner).
  • name - The full name of the user.
  • company - The company name for users of type construction.
  • phone - The phone number
  • billing
    • address1 - billing street address
    • address2 - billing address additional line
    • city - billing address city
    • state - billing address state
    • postal_code - billing address postal code
    • country - billing address country 2 letter code
  • shipping
    • address1 - shipping street address
    • address2 - shipping address additional line
    • city - shipping address city
    • state - shipping address state
    • postal_code - shipping address postal code
    • country - shipping address country 2 letter code

Endpoints

GET /customer/{email} 
{
    "email": "thecustomer@powertoolsafe.com",
    "types: {"construction"},
    "yours": true,
}
Returns 404 if the customer is not found, you can POST and create a new one. "Yours" indicates that this is a customer you created.
POST /customer Payload 
{
    "email":"thecustomer@powertoolsafe.com",
    "type":"construction",
    "name":"Power Tool",
    "company="Big Construction Inc",
    "phone":"406-555-1212",
    "billing":{
        "address1":"123 Any Lane",
        "address2":"Apt 2",
        "city":"Bozeman",
        "state":"MT",
        "postal_code":"59718"
    },
    "shipping":{
        "address1":"123 Any Lane",
        "address2":"Apt 2",
        "city":"Bozeman",
        "state":"MT",
        "postal_code":"59718"
    }
}
Returns 
{
    "email": "thecustomer@powertoolsafe.com",
}
Returns 403 if the customer already exists since you cannot update a customer's attributes. Returns 400 if a required field is missing -- all fields required except address2.

Examples

$ curl https://powertoolsafe.com/api/v1/customer?email=thecustomer@powertoolsafe.com&key=test_asdsdf89sdm2tsdfg
    -X GET

$ curl https://powertoolsafe.com/api/v1/customer
    -d key=test_asdsdf89sdm2tsdfg:
    -d payload={"email":"thecustomer@powertoolsafe.com","type":"construction","name":"Power Tool","company": "Big Construction Inc","phone":"406-555-1212","billing":{"address1":"123 Any Lane","address2":"Apt 2","city":"Bozeman","state":"MT","postal_code":"59718"},"shipping":{"address1":"123 Any Lane","address2":"Apt 2","city":"Bozeman","state":"MT","postal_code":"59718"}}:
    -x POST

Transaction

A transaction provides tha capability of adding/querying receipts and tools for a customer.

The transaction consists of a receipt and then a list of tools from that receipt.

Payload Attributes

  • email - The email address of the user.
  • receipt - A single receipt for this transaction
    • date - the date on the receipt
    • total - the total amount on the receipt
    • description - any text to describe the receipt (not required)
    • invoice - the invoice number of the receipt
    • sold_by - text to indicate the sales person (not required)
    • images - array of any number of pages
      • page - integer of page number
      • encoded_image - base64 encoding of image
  • tools - array of any number of tools
    • brand - Brand/Manufacturer of the tool
    • model - Model of the tool
    • serial_number - Serial number on the tool (not required)
    • purchase_price - Price of the tool according to the receipt
    • is_new - 1 if new purchase, 0 if used

Endpoints

POST /transactionPayload 
{
    "email": "thecustomer@powertoolsafe.com",
    "type": "construction",
    "receipt": {
        "date" : "2021-01-15",
        "total" : "933.23",
        "description" : "online sale",
        "invoice" : "100221",
        "sold_by" : "PB",
        "images" : {
            { "page": 1, "type":"jpg", "encoded_image":"aWpqWtSW0OXLkSEHRqSAIrFmzhm9/+9s0NzdP73vLKZwPTPD3H3cRSoOczaDL" }
            { "page": 2, "type":"jpg", "encoded_image":"Dz30ECtXrdXHq1ClOnz49657y8nJWtbTwyCOP4Pf778ifitx2MqYQjUb5/PPP" }
        },
    },
    "tools" : {
        { "brand":"DeWalt","model":"DW2400","serial_number":"2220022","purchase_price":"344.22","is_new":1},
        { "brand":"DeWalt","model":"DW2402","purchase_price":"344.22","is_new":0},
    }
}
Returns 
  {
    "email": "thecustomer@powertoolsafe.com",
    "type": "construction",
    "receipt_id" : "62b19b0c-8469-43cc-aaf0-612bf5b6af8e",
    "tools" : {
        {"brand": "DeWalt","model":"DW2400", "tool_uuid":"cacedc28-e7a9-4f90-96b3-5b570fa5bdd7"},
        {"brand": "DeWalt","model":"DW2402", "tool_uuid":"d86cc17a-5112-42f2-9881-5d911566a020"},
    }
  }
Returns 400 if a required field is missing -- all fields required unless noted.
POST /transaction/toolsPayload 
{
    "tools": {
        {"tool_uuid": "cacedc28-e7a9-4f90-96b3-5b570fa5bdd7", "serial_number":"5738292"},
        {"tool_uuid": "d86cc17a-5112-42f2-9881-5d911566a020", "serial_number":"3223332"},
    }
}
Returns 
{
    "tools_updated": 2
}
Returns 400 if a required field is missing -- all fields required.
GET /transaction/toolsPayload - Email + any combination to search, returns all matching tools 
{
    "email" : "thecustomer@powertoolsafe.com",
    "type" : "construction",
    "brand" : "DeWalt",
    "model" : "DW2400",
    "receipt_id" : "62b19b0c-8469-43cc-aaf0-612bf5b6af8e",
    "tool_uuid" : "cacedc28-e7a9-4f90-96b3-5b570fa5bdd7"
}
Returns 
{
    "search" : {
        "email" : "thecustomer@powertoolsafe.com",
        "type" : "construction",
        "brand" : "DeWalt",
        "model" : "DW2400",
        "receipt_id" : "62b19b0c-8469-43cc-aaf0-612bf5b6af8e",
        "tool_uuid" : "cacedc28-e7a9-4f90-96b3-5b570fa5bdd7"
    },
    "tools" : {
        {
        "brand" : "DeWalt",
        "model" : "DW2400",
        "receipt_id" : "62b19b0c-8469-43cc-aaf0-612bf5b6af8e",
        "tool_uuid" : "tool_uuid":"cacedc28-e7a9-4f90-96b3-5b570fa5bdd7",
        "date_added" : "2021-12-15"
        }
    }
}
Returns 400 if email is missing. Returns 404 if tool not found.
GET /transaction/receiptsPayload - Email + any combination to search, returns all matching receipts 
{
    "email" : "thecustomer@powertoolsafe.com",
    "type" : "construction",
    "receipt_id" : "62b19b0c-8469-43cc-aaf0-612bf5b6af8e",
    "date" : "2021-01-15",
    "total" : "933.23",
    "description" : "online sale",
    "invoice" : "100221",
    "sold_by" : "PB"
}
Returns 
{
    "search": {
        "email" : "thecustomer@powertoolsafe.com",
        "type" : "construction",
        "receipt_id" : "62b19b0c-8469-43cc-aaf0-612bf5b6af8e",
        "date" : "2021-01-15",
        "total" : "933.23",
        "description" : "online sale",
        "invoice" : "100221",
        "sold_by" : "PB"
    },
    "receipts" : {
        {
        "receipt_id" : "62b19b0c-8469-43cc-aaf0-612bf5b6af8e",
        "date_added" : "2021-12-15",
        "total" : "933.23",
        "description" : "online sale",
        "invoice" : "100221",
        "sold_by" : "PB",
        "tools": {
            "brand" : "DeWalt",
            "model" : "DW2400",
            "tool_uuid" : "tool_uuid":"cacedc28-e7a9-4f90-96b3-5b570fa5bdd7",
            }
        }
    }
}
Returns 400 if email is missing. Returns 404 if receipt not found.

Examples

$ curl https://powertoolsafe.com/api/v1/transaction
    -d key=test_asdsdf89sdm2tsdfg:
    -d payload={"email":"thecustomer@powertoolsafe.com","type":"construction", "receipt": {"date" : "2021-01-15","total" : "933.23","description" : "online sale","invoice" : "100221","sold_by" : "PB", "images" : { { "page":"1", "encoded_image":"aWpqWtSW0OXLkSEHRqSAIrFmzhm9/+9s0NzdP73vLKZwPTPD3H3cRSoOczaDL"},{ "page": 2, "encoded_image":"Dz30ECtXrdXHq1ClOnz49657y8nJWtbTwyCOP4Pf778ifitx2MqYQjUb5/PPP" }},},"tools" : { { "brand":"DeWalt","model":"DW2400","serial_number":"2220022","purchase_price":"344.22","is_new":1},{ "brand":"DeWalt","model":"DW2402","purchase_price":"344.22","is_new":0}}}
    -x POST

$ curl https://powertoolsafe.com/api/v1/transaction/tools
    -d key=test_asdsdf89sdm2tsdfg:
    -d payload="tools": { {"tool_uuid": "cacedc28-e7a9-4f90-96b3-5b570fa5bdd7", "serial_number":"5738292"},{"tool_uuid": "d86cc17a-5112-42f2-9881-5d911566a020", "serial_number":"3223332"}}
    -x POST

$ curl https://powertoolsafe.com/api/v1/transaction/tool
    -d key=test_asdsdf89sdm2tsdfg:
    -d payload={"email" : "thecustomer@powertoolsafe.com", "type":"construction", "tools" : { {"brand" : "DeWalt","model" : "DW2400","invoice_id" : "62b19b0c-8469-43cc-aaf0-612bf5b6af8e","tool_uuid" : "tool_uuid":"cacedc28-e7a9-4f90-96b3-5b570fa5bdd7","date_added" : "2021-12-15"}} }
    -x GET

$ curl https://powertoolsafe.com/api/v1/transaction/receipt
    -d key=test_asdsdf89sdm2tsdfg:
    -d payload={"email" : "thecustomer@powertoolsafe.com", "type":"construction", "tools" : { {"brand" : "DeWalt","model" : "DW2400","invoice_id" : "62b19b0c-8469-43cc-aaf0-612bf5b6af8e","tool_uuid" : "tool_uuid":"cacedc28-e7a9-4f90-96b3-5b570fa5bdd7","date_added" : "2021-12-15"}} }
    -x GET