Skip to main content
Version: v3

ABS Tire Protection API

Revision 06-JUN-2022

Table of Contents

Overview

This API allows partners to create, view, and cancel registrations. Your application must authenticate all requests with a signed JWT. For help, reach out to engineering@abswarranty.net.

Environments

NameBase URLPurpose
Sandboxhttps://sandbox.absintegrations.com/api/v3Testing
Productionhttps://absintegrations.com/api/v3Production

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

Note: 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"
}

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

algNameCurve
ES256secp256k1ECSDA P-256
ES384secp384r1ECDSA P-384
ES512secp521r1ECDSA P-521

Send your public key to engineering@abswarranty.net

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

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:

ClaimNameDescription
iatissued atUnix timestamp when the token was created.
ississuerYour Partner ID.
audaudienceThe environment Base URL.
expexpiration timeUnix 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
}

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

Creating a registration

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

POST /registrations

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

Parameters

Sent in the request body as JSON

Registration Object

NameTypeRequired
product_idstringyes
invoiceNumberstringyes
enrollDateISO 8601 date stringyes
customercustomer objectyes
tiresarray of tire objectsyes
vehiclevehicle objectno
commentsstringno

Customer Object

NameTypeRequired
namestringyes
phonephone stringno
emailemail stringyes
addressobjectno

Address Object

NameTypeRequired
line1stringyes
line2stringno
citystringyes
statestringyes
zipstringyes

Tire Object

NameTypeRequired
makestringyes
modelstringyes
sizestringyes
retailPricenumberyes
dotstringno
partNumberstringno

Vehicle Object

NameTypeRequired
year4-digit numberyes
makestringyes
modelstringyes
vinstringno
plateNumberstringno
plateStatestringno
mileagenumberno

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.

StatusNameDescriptionResolution
400Bad RequestThe server could not understand the requestCheck all parameters and ensure the request is valid
401UnauthorizedThe request is unauthenticatedEnsure 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" }

Listing all 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.

This endpoint only returns JSON

GET /registrations

Parameters

Sent in the URL as a query string

NameDefault ValueDescription
pageSize100Number of records per page.
page1The 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.

StatusNameDescriptionResolution
401UnauthorizedThe request is unauthenticated.Ensure your JWT is valid.
400Bad RequestThe 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
}

Viewing a registration

To view a single registration, send a GET request to the /registrations/:id endpoint.

This endpoint only returns JSON

GET /registrations/:id

Parameters

Sent in the URL

NameDescription
idThe 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.

StatusNameDescriptionResolution
401UnauthorizedThe request is unauthenticated.Ensure your JWT is valid.
404Not FoundThe resource was not found.Ensure the Registration ID is correct.

Example

Request

curl --location --request GET 'https://sandbox.absintegrations.com/api/v3/registrations/6109bf5e5494a80b344f5daf' \
--header 'Authorization: Bearer eyJpYXQiOjE2Mjc2NTU5NzAsImV4cCI6MTYyNzY2MzE3MCwiYXVkIjoiaHR0cHM6Ly9zYW5kYm94LmFic2ludGVncmF0aW9ucy5jb20vYXBpL3YzIiwiaXNzIjoiNjEwMmI1MjFmNDAzZjQyZGRjZGU3YWU1In0.y5-vxJHlBtVf2Jr9sPO4I97L5hImkhyn1EtHeCoeIzqZwObpcVy9ZEMJoCGbXwnGdeZ6GpaiO8KD9xLqgUZcTg'

Response

{
"_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"
}

Cancelling a registration

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

PATCH /registrations/:id
PATCH /registrations?invoiceNumber=:invoiceNumber

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

NameTypeRequired
cancelledOnISO 8601 Date extended format String.yes

Sent in the URL as a query string

NameDescriptionRequired
invoiceNumberThe invoice number.Required if not using registration id.

Sent in the URL

NameDescriptionRequired
idThe 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.

StatusNameDescriptionResolution
401UnauthorizedThe request is unauthenticated.Ensure your JWT is valid.
409ConflictThe 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

Status Codes

Success

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

StatusNameDescription
200OKThe request succeeded and content is returned.
201CreatedThe request succeeded and a resource has been created.
204No ContentThe 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.

StatusNameDescription
301Moved PermanentlyThis endpoint has changed permanently - please use the new URL given for all future requests.
302FoundThis 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.

StatusNameDescriptionResolution
400Bad RequestThe server could not understand the request.Check all parameters and ensure the request is valid.
401UnauthorizedThe request is unauthenticated.Ensure your JWT is valid.
403ForbiddenThe client does not have access rights to this content.Ensure your Partner ID, endpoint, and method are correct.
404Not FoundThe resource was not found.Ensure your Partner ID, endpoint, and method are correct.
405Not AllowedThe request method is not allowed.Ensure your method is correct.
409ConflictThe request conflicts with the current state of the server.Ensure your Partner ID, endpoint, and method are correct. Some resources cannot be modified.
429Too Many RequestsThe users has sent too many requests in the given amount of time (rate limiting).Wait and retry your request.
500Internal Server ErrorThe server has encountered an unexpected error.Wait and retry your request. Contact engineering@abswarranty.net if the issue persists.
502Bad GatewayThe server was unable to communicate with another service.Wait and retry your request. Contact engineering@abswarranty.net if the issue persists.
503Service UnavailableThe server is not ready to handle the request.Wait and retry your request. Contact engineering@abswarranty.net if the issue persists.
504Gateway TimeoutThe server was not able to complete your request in time.Wait and retry your request. Contact engineering@abswarranty.net if the issue persists.