Skip to main content

Overview

Introduction​

  • The Warranty Life API is a simple REST modeled API.
  • You will require Warranty Life API credentials for access. If you do not already have API credentials, please sign up as a partner, or, if you have already signed up and are missing API credentials, please contact api@warrantylife.com.
  • Any returned field that is not defined in this document should be ignored in order to ensure forward compatibility with updates to this version of the API.
  • All URLs shown should be prefixed with /api/201308 where the last portion is the version identifier (it represents the last month that a backward-compatibility-breaking change occurred rather than the current release date).
  • The protocol and host name to use is

General Usage Information​

Character Set​

UTF-8 is used exclusively.

Authentication​

Authentication is done using HTTP Basic Authentication using your API key and API secret as the username and password values. Other forms of authentication may be introduced in future versions of the API.

Sub-Accounts​

If you are using sub-accounts then you would append /sub-account-id to your API key when acting on behalf of the sub-account when authenticating. Billing of warranties is based on the authenticated account, so you must use sub-accounts if you want to have separate billing for different stores (such as for franchises) and you are not using separate API keys and secrets for each store. Sub-accounts can be created via the partner store add page where "Remote Id" is the sub-account-id.

Example: If the API key for your primary account was MqUax1IGBQdL and you were sending a request on behalf of the sub-account 43 then you would use MqUax1IGBQdL/43 as the API key (used as the username) for authentication.

Reference IDs, "refIds"​

There are a number of fields called or ending in refId. The purpose of these fields is to give you the option to register your own unique identifiers with those objects, allowing you to reference them later using your own identifiers rather than needing to store Warranty Life's identifiers.

Representation Formats​

The API currently supports JSON responses, served as application/json, encoded as UTF-8. That media type should always be specified in the request's Accept header.

Responses and Errors​

Standard HTTP response codes are returned appropriately in the HTTP Status response header. Possible status codes include:

  • 200: Success (upon a successful GET, or PUT request)
  • 201: Created (upon a successful POST request)
  • 202: Accepted (request was accepted for processing, but the processing has not been completed)
  • 204: No Content (upon a successful DELETE request)
  • 400: Resource Invalid (improperly-formatted request)
  • 401: Unauthorized (incorrect or missing authentication credentials)
  • 403: Rejected/Forbidden (request understood but server is refusing the request)
  • 404: Resource Not Found (requesting a non-existent resource)
  • 405: Method Not Allowed (e.g., trying to POST to a URL that responds only to GET)
  • 406: Not Acceptable (server can't satisfy the Accept header specified by the client)
  • 500: Application Error

Errors​

In most cases, requests that return an "error" status code (4XX or 5XX) will contain a short JSON response body explaining the nature of the error (provided the API call asked for a JSON response).

{
    "error_code": 0,
    "status_text": "Bad Request",
    "message": "The ID specified does not exist."
}

Other HTTP verbs​

Successful POST requests (e.g., to create a new record) will return a status code of 200, 201 or 202. If the status is 201 then the response will include a Location header with the URI of the newly created resource, and include a JSON representation of the resource in the body of the response. If the status code is 202 then the response will contain an id that will be the identifier for the object once it exists and can be used in future requests.

Successful PUT requests (e.g., to update an existing record) will return a status code of 200 or 202, and include a JSON representation of the resource in the body of the response.

Successful DELETE requests (e.g., to delete an existing record) will return a status code of 204 and no body.

Wildcards​

Certain parameters in some of the API calls allow the use of wildcards in parameters used to perform searches. These parameters are marked below like this. In these fields, you may use the asterisk character (*) to represent "zero or more characters at this point." For example, Apple* would match Apple, Appleton, Applewood, etc. Without the wildcard character used in this example, only Apple would match.

Paging​

For some API calls, the results are paged, meaning only a subset of all possible results are returned. For these calls, the parameters startAt and limit are used to specify which page of the results should be returned. If these terms are not included, the default of returning the first page of results (startAt=0) will be used with the default number of results.

  • startAt - Specifies the offset to start results
  • limit - Specifies the maximum number of results to return

Example​

If you wanted pages of 50 results each, you might make the following calls to get the first three pages of results:

  1. startAt=0&limit=50 - Returns the first page of 50 results
  2. startAt=50&limit=50 - Returns the second page of 50 results
  3. startAt=100&limit=50 - Returns the third page of 50 results