Version: Next

Tire Protection API

Revision 09-FEB-2023

Tire Protection API

Overview

This API allows partners to create, view, and cancel registrations. Your application must authenticate all requests with a signed JWT.

info

For more information about how to generate a signed JWT see Getting Started. For help, reach out to engineering@abswarranty.net.

Environments

Name	Base URL	Purpose
Sandbox	`https://sandbox.absintegrations.com/api/v3`	Testing
Production	`https://absintegrations.com/api/v3`	Production

note

Your Partner ID and Program ID(s) are unique per environment.

We recommend using a different asymmetric key pair per environment.

Authentication

Your application must authenticate all API requests with a signed JWT passed as a Bearer token in the HTTP Authorization header.

The JWT must contain alg and typ headers, where alg is the algorithm used to sign the token and typ is JWT.

{
  "alg": "ES256",
  "typ": "JWT"
}

::: note

The token must be signed with the Elliptic Curve Digital Signature Algorithm (ECDSA) [FIPS PUB 186-5]. We support the following curves:

:::

Algorithm	Name	Curve
`ES256`	secp256r1	ECSDA P-256
`ES384`	secp384r1	ECDSA P-384
`ES512`	secp521r1	ECDSA P-521

See getting started for further details on how to generate your private and public key.

Send your public key to engineering@abswarranty.net

caution

Keep your private key secure - do not send it over an insecure channel or share it with anyone, including ABS

note

Your key pair never expires - if you decide to change your key pair, send your updated public key to engineering@abswarranty.net

The JWT must contain the following claims:

Claim	Name	Description
`iat`	issued at	Unix timestamp when the token was created.
`iss`	issuer	Your Partner ID.
`aud`	audience	The environment Base URL.
`exp`	expiration time	Unix timestamp not greater than 2 hours in the future.

For example:

{
  "iat": 1627618568,
  "iss": "6102b521f403f42ddcde7ae5",
  "aud": "https://sandbox.absintegrations.com/api/v3",
  "exp": 1627625768
}

To be valid, the JWT must:

Contain iat, iss, aud, and exp claims
iat must be within the last 2 hours
iss must be your Partner ID
exp must not be greater than 2 hours in the future
aud must be an environment Base URL

If a claim is missing, does not pass validation, contains incorrect values, or if the token cannot be verified, the API will return 401: Unauthorized.

{
  "error": "unauthorized",
  "statusCode": 401
}

note

We recommend generating a new signed JWT for every request made to our API.

Creating a registration

POST /registrations

To create a registration, send a POST request to the /registrations endpoint with a JSON payload containing consumer, tire, and vehicle information.

tip

This endpoint only accepts JSON - set the HTTP header 'Content-Type: application/json on every POST request

Parameters

Headers	Description
`Authorization`	Bearer token in form of a JWT see getting started for more information.

Send a registration object as the request body as JSON

Errors

This endpoint may respond with any of the status codes enumerated below; however, the most common errors are 401: Unauthorized and 400: Bad Request.

Status	Name	Description	Resolution
`400`	Bad Request	The server could not understand the request	Check all parameters and ensure the request is valid
`401`	Unauthorized	The request is unauthenticated	Ensure your JWT is valid

Examples

Registration object

{
  "product_id": "YOUR-PRODUCT-ID",
  "invoiceNumber": "001-20345",
  "enrollDate": "2021-08-01T13:08:00.000Z",
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "vehicle": {
    "year": 2021,
    "make": "Tesla",
    "model": "Model 3"
  },
  "tires": [
    {
      "make": "BRIDGESTONE",
      "model": "TURANZA ER33",
      "size": "235/45R18",
      "retailPrice": 334.31
    },
    {
      "make": "BRIDGESTONE",
      "model": "TURANZA ER33",
      "size": "235/45R18",
      "retailPrice": 334.31
    },
    {
      "make": "BRIDGESTONE",
      "model": "TURANZA ER33",
      "size": "235/45R18",
      "retailPrice": 334.31
    },
    {
      "make": "BRIDGESTONE",
      "model": "TURANZA ER33",
      "size": "235/45R18",
      "retailPrice": 334.31
    }
  ]
}

Request

curl --location --request POST 'https://sandbox.absintegrations.com/api/v3/registrations' \
--header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2Mjc2NTU5NzAsImV4cCI6MTYyNzY2MzE3MCwiYXVkIjoiaHR0cHM6Ly9zYW5kYm94LmFic2ludGVncmF0aW9ucy5jb20vYXBpL3YzIiwiaXNzIjoiNjEwMmI1MjFmNDAzZjQyZGRjZGU3YWU1In0.y5-vxJHlBtVf2Jr9sPO4I97L5hImkhyn1EtHeCoeIzqZwObpcVy9ZEMJoCGbXwnGdeZ6GpaiO8KD9xLqgUZcTg' \
--header 'Content-Type: application/json' \
--data-raw '{
  "product_id": "YOUR-PRODUCT-ID",
  "invoiceNumber": "001-20345",
  "enrollDate": "2021-08-01T13:08:00.000Z",
  "customer": {
      "name": "John Doe",
      "email": "john.doe@example.com"
  },
  "vehicle": {
      "year": 2021,
      "make": "Tesla",
      "model": "Model 3"
  },
  "tires": [
    {
      "make": "BRIDGESTONE",
      "model": "TURANZA ER33",
      "size": "235/45R18",
      "retailPrice": 334.31
    },
    {
      "make": "BRIDGESTONE",
      "model": "TURANZA ER33",
      "size": "235/45R18",
      "retailPrice": 334.31
    },
    {
      "make": "BRIDGESTONE",
      "model": "TURANZA ER33",
      "size": "235/45R18",
      "retailPrice": 334.31
    },
    {
      "make": "BRIDGESTONE",
      "model": "TURANZA ER33",
      "size": "235/45R18",
      "retailPrice": 334.31
    }
  ]
}'

Response

{ "id": "6109bf5e5494a80b344f5daf" }

Get a registration

GET /registrations/{id}

This endpoint retreives the registration of the id passed into the endpoint.

note

Replace {id} with the registration id of the registation to retreive.

Parameters

Headers	Description
`Authorization`	Bearer token in form of a JWT see getting started for more information.

Sent in the URL

Name	Description
`id`	The registration ID.

Errors

This endpoint may respond with any of the status codes enumerated below; however, the most common errors are 401: Unauthorized and 404: Not Found.

Status	Name	Description	Resolution
`401`	Unauthorized	The request is unauthenticated.	Ensure your JWT is valid.
`404`	Not Found	The resource was not found.	Ensure the Registration ID is correct.

Example

Request

curl --location --request GET 'https://sandbox.absintegrations.com/api/v3/registrations/63e68996f4307525f7778e8e' \
--header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2Mjc2NTU5NzAsImV4cCI6MTYyNzY2MzE3MCwiYXVkIjoiaHR0cHM6Ly9zYW5kYm94LmFic2ludGVncmF0aW9ucy5jb20vYXBpL3YzIiwiaXNzIjoiNjEwMmI1MjFmNDAzZjQyZGRjZGU3YWU1In0.y5-vxJHlBtVf2Jr9sPO4I97L5hImkhyn1EtHeCoeIzqZwObpcVy9ZEMJoCGbXwnGdeZ6GpaiO8KD9xLqgUZcTg' \
--header 'Content-Type: application/json'

Response

{
  "_id": "63e68996f4307525f7778e8e",
  "invoiceNumber": "001-20345",
  "program_id": "63e68996f4307525f7777c7e",
  "enrollDate": "2023-02-10T18:14:45.959Z",
  "customer": { "name": "John Doe", "email": "john.doe@example.com" },
  "vehicle": { "year": 2021, "make": "Tesla", "model": "Model 3" },
  "tires": [
    {
      "make": "BRIDGESTONE",
      "model": "TURANZA ER33",
      "size": "235/45R18",
      "retailPrice": 334.31
    },
    {
      "make": "BRIDGESTONE",
      "model": "TURANZA ER33",
      "size": "235/45R18",
      "retailPrice": 334.31
    },{
      "make": "BRIDGESTONE",
      "model": "TURANZA ER33",
      "size": "235/45R18",
      "retailPrice": 334.31
    },{
      "make": "BRIDGESTONE",
      "model": "TURANZA ER33",
      "size": "235/45R18",
      "retailPrice": 334.31
    }
  ]
}

Listing all registrations

GET /registrations

To list all registrations, send a GET request to the /registrations endpoint. Returned results are paginated. The request can use optional query string parameters to retrieve different pages.

note

This endpoint only returns JSON

Parameters

Sent in the URL as a query string

Headers	Description
`Authorization`	Bearer token in form of a JWT see getting started for more information.

Name	Default Value	Description
`pageSize`	`100`	Number of records per page.
`page`	`1`	The page to retrieve.

Errors

This endpoint may respond with any of the status codes enumerated below; however, the most common errors are 401: Unauthorized and 400: Bad Request.

Status	Name	Description	Resolution
`401`	Unauthorized	The request is unauthenticated.	Ensure your JWT is valid.
`400`	Bad Request	The server could not understand the request.	Check all parameters and ensure the request is valid.

Example

Request

curl --location --request GET 'https://sandbox.absintegrations.com/api/v3/registrations?page=1&pageSize=100' \
--header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2Mjc2NTU5NzAsImV4cCI6MTYyNzY2MzE3MCwiYXVkIjoiaHR0cHM6Ly9zYW5kYm94LmFic2ludGVncmF0aW9ucy5jb20vYXBpL3YzIiwiaXNzIjoiNjEwMmI1MjFmNDAzZjQyZGRjZGU3YWU1In0.y5-vxJHlBtVf2Jr9sPO4I97L5hImkhyn1EtHeCoeIzqZwObpcVy9ZEMJoCGbXwnGdeZ6GpaiO8KD9xLqgUZcTg'

Response

{
  "results": [
    {
      "_id": "6109bf5e5494a80b344f5daf",
      "product_id": "YOUR-PRODUCT-ID",
      "invoiceNumber": "001-20345",
      "enrollDate": "2021-08-01T13:08:00.000Z",
      "customer": {
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      "vehicle": {
        "year": 2021,
        "make": "Tesla",
        "model": "Model 3"
      },
      "tires": [
        {
          "make": "BRIDGESTONE",
          "model": "TURANZA ER33",
          "size": "235/45R18",
          "retailPrice": 334.31
        },
        {
          "make": "BRIDGESTONE",
          "model": "TURANZA ER33",
          "size": "235/45R18",
          "retailPrice": 334.31
        },
        {
          "make": "BRIDGESTONE",
          "model": "TURANZA ER33",
          "size": "235/45R18",
          "retailPrice": 334.31
        },
        {
          "make": "BRIDGESTONE",
          "model": "TURANZA ER33",
          "size": "235/45R18",
          "retailPrice": 334.31
        }
      ],
      "cancelledOn": "2021-08-03T10:10:00.000Z"
    }
  ],
  "totalRecordCount": 1,
  "page": 1,
  "pageSize": 100,
  "totalPages": 1
}

Cancelling a registration

PATCH /registrations/:id

PATCH /registrations?invoiceNumber=:invoiceNumber

To cancel a registration, send a PATCH request to the /registrations/:id endpoint or to the /registrations?invoiceNumber=:invoiceNumber endpoint with a JSON payload containing the cancellation date.

note

If your invoice numbers are not unique, you must use the /registrations/:id endpoint

tip

This endpoint only accepts JSON - set the HTTP header 'Content-Type: application/json on every PATCH request

Parameters

Sent in the request body as JSON

Name	Type	Required
`cancelledOn`	ISO 8601 Date extended format String.	yes

Sent in the URL as a query string

Name	Description	Required
`invoiceNumber`	The invoice number.	Required if not using registration `id`.

Sent in the URL

Name	Description	Required
`id`	The registration ID.	Required if not using `invoiceNumber`.

Errors

This endpoint may respond with any of the status codes enumerated below; however, the most common errors are 401: Unauthorized and 409: Conflict.

Status	Name	Description	Resolution
`401`	Unauthorized	The request is unauthenticated.	Ensure your JWT is valid.
`409`	Conflict	The request conflicts with the current state of the server.	Ensure the Registration ID or Invoice Number is correct. Some registrations cannot be cancelled. Registrations cannot be cancelled more than once.

note

Not all registrations can be cancelled. If the terms and conditions for your program do not allow for cancellation, attempting to cancel a registration will result in the error 409: Conflict

Examples

Registration object

{
  "cancelledOn": "2021-08-03T10:10:00.000Z"
}

Request

curl --location --request PATCH 'https://sandbox.absintegrations.com/api/v3/registrations?invoiceNumber=001-20345' \
--header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2Mjc2NTU5NzAsImV4cCI6MTYyNzY2MzE3MCwiYXVkIjoiaHR0cHM6Ly9zYW5kYm94LmFic2ludGVncmF0aW9ucy5jb20vYXBpL3YzIiwiaXNzIjoiNjEwMmI1MjFmNDAzZjQyZGRjZGU3YWU1In0.y5-vxJHlBtVf2Jr9sPO4I97L5hImkhyn1EtHeCoeIzqZwObpcVy9ZEMJoCGbXwnGdeZ6GpaiO8KD9xLqgUZcTg' \
--header 'Content-Type: application/json' \
--data-raw '{
  "cancelledOn": "2021-08-03T10:10:00.000Z"
}'

Response

No body is returned in the response, only the HTTP status: 204: No Content

Type Objects

Registration Object

Name	Type	Required
`product_id`	string	yes
`invoiceNumber`	string	yes
`enrollDate`	ISO 8601 date string	yes
`customer`	customer object	yes
`tires`	array of tire objects	yes
`vehicle`	vehicle object	no
`comments`	string	no

Customer Object

Name	Type	Required
`name`	string	yes
`phone`	phone string	no
`email`	email string	yes
`address`	object	no

Address Object

Name	Type	Required
`line1`	string	yes
`line2`	string	no
`city`	string	yes
`state`	string	yes
`zip`	string	yes

Tire Object

Name	Type	Required
`make`	string	yes
`model`	string	yes
`size`	string	yes
`retailPrice`	number	yes
`dot`	string	no
`partNumber`	string	no

Vehicle Object

Name	Type	Required
`year`	4-digit number	yes
`make`	string	yes
`model`	string	yes
`vin`	string	no
`plateNumber`	string	no
`plateState`	string	no
`mileage`	number	no

Status Codes

Success

All API endpoints may return the following codes indicating a successful request.

Status	Name	Description
`200`	OK	The request succeeded and content is returned.
`201`	Created	The request succeeded and a resource has been created.
`204`	No Content	The request succeeded and there is no content to return.

Redirect

All API endpoints may return the following codes indicating a new endpoint is to be used for the request.

Status	Name	Description
`301`	Moved Permanently	This endpoint has changed permanently - please use the new URL given for all future requests.
`302`	Found	This endpoint has changed temporarily - please use the new URL given for this request.

Error

All API endpoints may throw the following errors. It is your responsibility to handle these errors appropriately, including retrying requests when needed until they succeed.

Status	Name	Description	Resolution
`400`	Bad Request	The server could not understand the request.	Check all parameters and ensure the request is valid.
`401`	Unauthorized	The request is unauthenticated.	Ensure your JWT is valid.
`403`	Forbidden	The client does not have access rights to this content.	Ensure your Partner ID, endpoint, and method are correct.
`404`	Not Found	The resource was not found.	Ensure your Partner ID, endpoint, and method are correct.
`405`	Not Allowed	The request method is not allowed.	Ensure your method is correct.
`409`	Conflict	The request conflicts with the current state of the server.	Ensure your Partner ID, endpoint, and method are correct. Some resources cannot be modified.
`429`	Too Many Requests	The users has sent too many requests in the given amount of time (rate limiting).	Wait and retry your request.
`500`	Internal Server Error	The server has encountered an unexpected error.	Wait and retry your request. Contact engineering@abswarranty.net if the issue persists.
`502`	Bad Gateway	The server was unable to communicate with another service.	Wait and retry your request. Contact engineering@abswarranty.net if the issue persists.
`503`	Service Unavailable	The server is not ready to handle the request.	Wait and retry your request. Contact engineering@abswarranty.net if the issue persists.
`504`	Gateway Timeout	The server was not able to complete your request in time.	Wait and retry your request. Contact engineering@abswarranty.net if the issue persists.

Tire Protection API

Table of Contents​

Overview​

Environments​

Authentication​

Creating a registration​

Parameters​

Errors​

Examples​

Get a registration​

Parameters​

Errors​

Example​

Listing all registrations​

Parameters​

Errors​

Example​

Cancelling a registration​

Parameters​

Errors​

Examples​

Type Objects​

Registration Object​

Customer Object​

Address Object​

Tire Object​

Vehicle Object​

Status Codes​

Success​

Redirect​

Error​

Table of Contents

Overview

Environments

Authentication

Creating a registration

Parameters

Errors

Examples

Get a registration

Parameters

Errors

Example

Listing all registrations

Parameters

Errors

Example

Cancelling a registration

Parameters

Errors

Examples

Type Objects

Registration Object

Customer Object

Address Object

Tire Object

Vehicle Object

Status Codes

Success

Redirect

Error