API Documentation
An in-depth guide to the BAYiQ Rewards Platform

*Version*:	2.38
*Protocol*:	HTTPS
*Type*:	application/json
*Release Date*:	Nov. 15th, 2018

Overview

We developed an easy-to-use API that allows you to add our rewards platform into your software. The API is web-based and is available to any software that has access to the internet. It contains only the core functionality you'll need to get up and running.

All development is done using our sandbox servers and you can even use it to log into our platform with your API keys to view the data you're creating. When you're ready to go live simply update the URL and you're ready to start rewarding your customers.

As an added bonus, we provide real-time support for developers. To get started, Request A Sandbox Key now.

Introduction

All production POST requests are sent over a secure HTTPS endpoint

Data

The data sent to the API is in JSON format. A high-level example is shown below.

{
    "username": "sandbox-credentials@example.com",
    "password": "1k42k3lB49011Kn303",
    "action": VARCHAR (32),
    "data": {Object}
}

POST

Send a POST request to the endpoint with a field named input in the header.

input must be BASE64 encoded

Name	Type	Description
input	TEXT	BASE64 encoded JSON string

API Endpoints

Sandbox

http://www.mccrdev.com/api/v2

Production

https://www.mycarcarerewards.com/api/v2

Search Customers

action

"search"

data

{ "search" : VARCHAR }

Search (required)

Option	Type	Description	Example
Last name	VARCHAR (128)	The last name of the rewards customer	Smith
Phone number	Integer (10)	Customer phone number	4801234321
Email address	VARCHAR (128)	Customer email address	john.doe@fancywebsite.com
Card number	VARCHAR (15)	The rewards card belonging to the customer	814367019681564

Request

{
    "username": "api_sandbox@bayiq.com",
    "password": "password",
    "action": "search",
    "data": {
                "search": "smith"
            }
}

Response

Success

The decoded JSON string displays three existing rewards customers with their personal information, available rewards and their vehicles.

Note: The log is included into the response only in a sandbox environment and is disabled in production to reduce overhead. To demonstrate, the log is included in this example but will not be part of more successful response examples continuing forward.

Response

Success

A rewards card can either belong to an existing rewards customer or a new customer. If the rewards card belongs to an existing rewards customer then the results will resemble what is shown above.

Cards that do not belong to an existing rewards customer are typically mailed to the customer in the form of gift card. When performing a search on this type of card the response is different from that of an existing customer. An example response is shown below.

The decoded JSON string displays the non-rewards customer information.

The mailer_id value will be needed later when registering the customer in the rewards program.

The promotions and promotions_value arrays are populated by data keyed by their BayIQ internal primary key and only include those promotions which are configured to display inside of the point of sale system.

Array
(
    [mailer] => Array
        (
            [first_name] => John
            [last_name] => Doe
            [address] => 123 S. Western Ave.
            [city] => Phoenix
            [state] => AZ
            [zip] => 85001
            [card] => 199570616244236
            [mailer_id] => 9648
        )

    [code] => 3
    [message] => Mailer Card Found
    [status] => success
)

No results

Below is the response when searching for a customer that does not exist.

Array
(
    [log] => Array
        (
            [0] => initializing
            [1] => start authentication
            [2] => already authenticated
            [3] => filtering action
            [4] => calling action:search
            [5] => start search
            [6] => searching last name
            [7] => NO RESULTS
            [8] => close
            [9] => (0.07250 sec)
        )

    [code] => 2
    [message] => NO RESULTS
    [status] => success
)

Search Customers

action

"retrieveUser"

data

{ "search" : VARCHAR }

Retrieve User (required)

Option	Type	Description	Example
Last name	VARCHAR (128)	The last name of the rewards customer	Smith
Home phone number	VARCHAR (128)	Customer home phone number	4801234321
Mobile phone number	VARCHAR (128)	Customer mobile phone number	5551234321
BayIQ Store ID	INT (11)	Customer email address	john.doe@fancywebsite.com

Request

{
    "username": "api_sandbox@bayiq.com",
    "password": "password",
    "action": "retrieveUser",
    "data": {
                "search": {
                    "store_id": 5555,
                    "last_name": "smith",
                    "home_phone": 5555555555,
                    "mobile_phone": 7777777777
                }
            }
}

Response

Success

The decoded JSON string displays three existing rewards customers with their personal information, available rewards and their vehicles.

Array
(
    [log] => Array
        (
            [0] => initializing
            [1] => start authentication
            [2] => already authenticated
            [3] => filtering action
            [4] => calling action:retrieveUser
            [5] => Begin getting user
            [6] => close
            [7] => (0.19532 sec)
        )

    [users] => Array
        (
            [0] => Array
                (
                    [BayIQUserId] => 12345,
                    [BayIQCircleId] => 67895,
                    [BayIQMarketId] => 150
                )
        ),

    [count] => 1,
    [status] => success

)

Response

Success

This method will most often return a single result, but can possibly return multiple results.

No results

Below is the response when searching for a customer that does not exist.

Array
(
    [log] => Array
        (
            [0] => initializing
            [1] => start authentication
            [2] => already authenticated
            [3] => filtering action
            [4] => calling action:retrieveUser
            [5] => Begin getting user
            [6] => close
            [7] => (0.19532 sec)
        )

    [code] => 2
    [message] => NO RESULTS
    [status] => success
)

Register Customers

action

"register"

data

{ "customer" : Object, "card" : Integer (15) | null }

To register a rewards customer construct an object that contains these customer fields shown below.

Customer Object

Option	Type	Description	Example
first_name	VARCHAR (128)	The first name of the rewards customer	John
last_name	VARCHAR (128)	The last name of the rewards customer	Doe
email	VARCHAR (128)	The email address belonging to the rewards customer. If a customer does not have an email address or chooses to opt-out then use the term "optout" in place of an actual email address. This will auto-generate an address for the customer and will be provided in the response for reference.	john.doe@example.com
type	VARCHAR (16)	The type of customer account. Options are retail \| commercial \| military	retail
phone	VARCHAR (10)	The phone number belonging to the rewards customer	4801234321
address	VARCHAR (128)	Customer address	123 S. Western St.
unit_number	VARCHAR (32)	Customer unit address	#212 \| null
city	VARCHAR (128)	City	Phoenix
state	VARCHAR (2)	State	AZ
zip	VARCHAR (5)	Customer zip code	85001
birth_month	VARCHAR (2)	The month the customer was born. This is needed to send the customer a birthday bonus.	06 \| null
birth_day	VARCHAR (2)	The day of month the customer was born	24 \| null
virtual_card	VARCHAR (1)	Issue a virtual card instead of a physical card	1 \| null
sms	VARCHAR (1)	Allow the customer to receive text messages	1 \| null
store_number	VARCHAR (32)	The store number the customer is registering at. If no store number is provided or does not match our store number on record, then the first store belonging to the dealer will be used.	CTP-1a \| null
employee_id	VARCHAR (32)	A unique code given to each employee within your system. This code can be alpha-numeric that will be mapped to the same employee found in the rewards system. Use this parameter if your system uses one login credentials for multiple employees or if you want to assign the registration to someone other than the user sending the request.	17641 \| ABC123 \| MLS \| null
mailer_id	VARCHAR (12)	This is the mailer_id provided in a search response for a gift card.	9648 \| null
aaa_member_number	VARCHAR (255)	This is the AAA Member number of the registrant in question.	ABC123456789 \| null

Request

{
  "username": "api-user@bayiq.com",
  "password": "e54ea19864031557f646",
  "action": "register",
  "data": {
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "4801234321",
      "birth_month": "06",
      "birth_day": "24",
      "address": "123 S. Western St.",
      "unit_number": "420",
      "city": "Phoenix",
      "state": "AZ",
      "virtual_card": null,
      "sms": 1,
      "type": "retail",
      "zip": "85281",
      "mailer_id": "10013",
      "aaa_member_number": "ABC123456789",
      "store_number": "A411",
      "employee_id": "MLS1",
    },
    "card": "501315718394541"
  }
}

Response

Success

When a successful response is returned a user_id will be created. You can store this variable in your software as a reference to our rewards platform.

Array
(
    [status] => success
    [code] => 1
    [message] => USER CREATED
    [user_id] => 10681
    [card] => 0192837465203847
)

Card Not Found

Below is an example of the error response and code returned when attempting to register a customer using a card that is not found in our rewards platform.

Array
(
    [log] => Array
        (
            [0] => initializing
            [1] => start authentication
            [2] => not authenticated
            [3] => attempt key or password authentication
            [4] => authentication passed
            [5] => filtering action
            [6] => calling action:register
            [7] => start register
            [8] => cleansing fields
            [9] => searching required fields
            [10] => validating email address
            [11] => lookup email address
            [12] => start creating new user
            [13] => searching for card-639284601087749
            [14] => card error
            [15] => close
            [16] => (0.79659 sec)
        )

    [status] => failed
    [error] => The card number you entered does not exist.
    [code] => 450
)

Add Vehicles

action

"addVehicle"

data

{ "vehicle" : Object, "user_id" : Integer (12) }

Vehicle Object

Parameter	Type	Description	Example
vehicle_id	Integer (12)	The id of an existing vehicle This is used to include a vehicle in a transaction	454 null
name	VARCHAR (64)	An easy to remember name of the customer's vehicle If a name is not available create one by joining year-make-model	John's Corvette Chevy Truck Bills F250
year	Integer (4)	Year built	1997 2005 2016
make	VARCHAR (64)	Vehicle make	Toyota Ford Cadillac
model	VARCHAR (64)	Vehicle model	Camry Mustang Fleetwood
mileage	Integer (12)	Vehicle mileage	80500 102459 null
plate_number	VARCHAR (12)	Vehicle plate number	BHR5034 SL33P3R AZN0112 null
vin	VARCHAR (32)	Vehicle VIN	1FMCU9G94FUA13888 null

User ID required

Parameter

Name	Type	Description	Example
user_id	Integer (12)	The user id belonging to the customer.	784321

Request

{
    "username": "api-quincy-1@bayiq.com",
    "password": "password",
    "action": "addVehicle",
    "data": {
        "vehicle": {
            "name": "John's Vette",
            "year": 2010,
            "make": "Corvette",
            "model": "Z06",
            "mileage": 19357,
            "plate_number": "ABC123",
            "vin": "1FMCU9G94FUA13888"
        },
        "user_id": "784321"
    }
}

Response

Success

When a successful response is returned a vehicle_id will be created.

Array
(
    [status] => success
    [code] => 1
    [message] => VEHICLE CREATED:454
    [vehicle_id] => 454
)

Missing Parameter

Array
(
    [log] => Array
        (
            [0] => initializing
            [1] => start authentication
            [2] => already authenticated
            [3] => filtering action
            [4] => calling action:addVehicle
            [5] => start add vehicle
            [6] => cleansing fields
            [7] => searching required fields
            [8] => close
            [9] => (0.06566 sec)
        )

    [code] => 502
    [status] => failed
    [error] => make argument is missing
)

Process Transaction

action

"processTransaction"

data

{ "transaction" : Object, "user_id" : Integer (12) }

To process a transaction for a customer construct the base transaction object.

Transaction Object

Parameters

Option	Type	Description	Example
invoice_number	VARCHAR (32)	The invoice number belonging to the transaction	9T85134
original_invoice_number	VARCHAR (32)	Use this parameter to void a transaction if the new transaction has a different invoice number than the original transaction	9T85134
amount	VARCHAR (12)	The total amount of the transaction	149.65
department	VARCHAR (128)	The department which the work order belonged to.	Service\|Tires\|null
store_number	VARCHAR (32)	The store number the customer is registering at. If no store number is provided or does not match our store number on record, then the first store belonging to the dealer will be used.	CTP-1a \| null
payment_type	VARCHAR (128)	The type of payment used.	Cash\|Visa\|MasterCard\|CFNA\|Synchrony\|null
employee_id	VARCHAR (32)	A unique code given to each employee within your system. This code can be alpha-numeric that will be mapped to the same employee found in the rewards system. Use this parameter if your system uses one login credentials for multiple employees or if you want to assign the transaction to someone other than the user sending the request.	17641 \| ABC123 \| MLS \| null
secondary_employee_id	VARCHAR (32)	A unique code given to each employee within your system. If present, this will take precedence over the employee_id parameter above.	17641 \| ABC123 \| MLS \| null
notes	TEXT	Any notes about the transaction	The customer bought new tires and will return for an oil change next month
vehicle	Object	A vehicle object containing either a single vehicle_id field for an existing vehicle or information fields to create a new vehicle association for the customer.	See Vehicle Object
rewards	Object	A rewards object containing bonuses, promotions and points to use on the transaction.	See Rewards Object
line_items	Object	The line item object that represents an itemized summary of the transaction.	See Line Item Object

User ID required

Parameter

Name	Type	Description	Example
user_id	Integer (12)	The user id belonging to the customer.	784321

Vehicle Object optional see above

If 'vehicle_id' is present and valid then it will be included into the transaction.
If 'vehicle_id' is not present then a new vehicle will be created and included into the transaction.
If a vehicle is not present on the invoice then the Vehicle Object can be completely omitted.

Rewards Object optional

Paramaters

Option	Type	Description	Example
bonuses	ARRAY	An array containing a list of bonus ids	[19,82] null
promotions	ARRAY	An array containing a list of promotion ids	[5] null
point_dollar	Decimal	The amount of money, in dollars, to use as rewards.	4.54 0.75 null

Examples

Bonuses, Promotions and Money


{
    "bonuses" : [19,82],
    "promotions": [5],
    "point_dollar":"4.54"
}

Only 1 Bonus


{
    "bonuses" : [24]
}

Use $4.20 in rewards


{
    "point_dollar" : "4.20"
}

Line Item Object required

This object is a nested array of line items.

Paramaters

Option	Type	Description	Example
technician	VARCHAR (64)	Name of the technician who performaned the line item	James Brown null
type	VARCHAR (32)	Type of line item	Labor Service New Parts null
code	VARCHAR (32)	A code reference or part number	K&N-F-1b bosch2ply Fram82 null
vendor	VARCHAR (128)	Vendor or distributor for parts	FAST Distributors null
manufacturer	VARCHAR (128)	Manufacturer name for parts	Holley AED Bosch null
quantity	VARCHAR (12)	The number of items used in the line item	4 8 -1 null
description	VARCHAR(128)	A description about the line item	4-Barrel Carb Wiper Fluid Synthetic 10W-30 null
cost	Decimal	The cost to the dealer* for the line item*	11.75 0.99 84.00 null
price	Decimal	The price the dealer* charges the customer for the line item*	15.00 129.99 -25.00 null
subtotal	Decimal	The total excluding* any fees and taxes*	15.00 129.99 -25.00 null
total	Decimal	The total charge for the line item including* fees and taxes.*	15.00 129.99 -25.00 null
declined_service	Boolean	A service the customer declined	1 null

Example

An object containing 3 line items;


 [{
    "technician": "Larry Guy",
    "type": "New Parts",
    "code": "454SS",
    "vendor": "Racetech distributors",
    "manufacturer": "Holley",
    "quantity": "1",
    "description": "4 barrel carb",
    "cost": 214.19,
    "price": 277.99,
    "total": 305,
    "declined_service": null
}, {
    "technician": "Larry Guy",
    "type": "Extra",
    "code": "ABC123",
    "vendor": "Fastcar supplies",
    "manufacturer": "GoodStuff N More",
    "quantity": "3",
    "description": "Cool decals",
    "cost": 4.99,
    "price": 7.29,
    "total": 8.85,
    "declined_service": 1
}, {
    "technician": "Larry Guy",
    "type": "Misc",
    "code": "WOW711",
    "vendor": "Blades warehouse",
    "manufacturer": "Rainex",
    "quantity": "2",
    "description": "Best wiper-blades in town",
    "cost": 14.99,
    "price": 17.29,
    "total": 18.85,
    "declined_service": null
}]

Putting It All Together

Request

{
    "username": "api-2@bayiq.com",
    "password": "6f83d37a03ce3dc5935b",
    "action": "processTransaction",
    "data": {
        "transaction": {
            "invoice_number": 123456,
            "amount": 11.11,
            "department": "other",
            "payment_type": "Visa",
            "employee_id": "MLS1",
            "notes": "This is a test transaction from the API",
            "vehicle": {
                "vehicle_id": 16
            },
            "rewards": {
                "bonuses": [82],
                "promotions": [19],
                "point_dollar": 6.24
            },
            "line_items": [{
                "technician": "Larry Guy",
                "type": "New Parts",
                "code": "454SS",
                "vendor": "Racetech distributors",
                "manufacturer": "Holley",
                "quantity": "1",
                "description": "4 barrel carb",
                "cost": 214.19,
                "price": 277.99,
                "total": 305,
                "declined_service": null
            }, {
                "technician": "Larry Guy",
                "type": "Extra",
                "code": "ABC123",
                "vendor": "Fastcar supplies",
                "manufacturer": "GoodStuff N More",
                "quantity": "3",
                "description": "Cool decals",
                "cost": 4.99,
                "price": 7.29,
                "total": 8.85,
                "declined_service": 1
            }, {
                "technician": "Larry Guy",
                "type": "Misc",
                "code": "WOW711",
                "vendor": "Blades warehouse",
                "manufacturer": "Rainex",
                "quantity": "2",
                "description": "Best wiper-blades in town",
                "cost": 14.99,
                "price": 17.29,
                "total": 18.85,
                "declined_service": null
            }]
        },
        "user_id": 10681
    }
}

Response

Success

Array
(
    [status] => success
    [code] => 1
    [message] => TRANSACTION CREATED
    [transaction_id] => 44
    [vehicle_id] => 16
    [user_id] => 17
    [point_dollar_balance] => 9.34
    [point_balance] => 467
)

Error

Processing a transaction for an invalid user; i.e. store employee.

Array
(
    [log] => Array
        (
            [0] => initializing
            [1] => start authentication
            [2] => not authenticated
            [3] => attempt key or password authentication
            [4] => authentication passed
            [5] => filtering action
            [6] => calling action:register
            [7] => start register
            [8] => cleansing fields
            [9] => searching required fields
            [10] => validating email address
            [11] => lookup email address
            [12] => start creating new user
            [13] => searching for card-639284601087749
            [14] => card error
            [15] => close
            [16] => (0.70419 sec)
        )

    [status] => failed
    [error] => The card number you entered does not exist.
    [code] => 450
)

Error

Rewards Balance Error

Array
(
    [log] => Array
        (
            [0] => initializing
            [1] => start authentication
            [2] => already authenticated
            [3] => filtering action
            [4] => calling action:processTransaction
            [5] => start transaction
            [6] => checking user
            [7] => user_id=17
            [8] => circle_id=8
            [9] => cleansing fields
            [10] => searching required fields
            [11] => validating vehicle fields
            [12] => cleansing fields
            [13] => existing vehicle; clearing additional fields
            [14] => searching required fields
            [15] => searching existing vehicle
            [16] => found vehicle id=16
            [17] => validating rewards fields
            [18] => cleansing fields
            [19] => searching required fields
            [20] => process promotions
            [21] => available promotions=3
            [22] => process bonuses
            [23] => available bonuses=1
            [24] => process points
            [25] => close
            [26] => (0.15852 sec)
        )

    [message] => point_dollar exceeds rewards balance
    [status] => failed
    [error] => user has $9.56 dollar(s) in rewards to use;
    [code] => 760
)

Redeem Gift Card

action

"redeemGiftCard"

data

{ "card" : VARCHAR (15), "user_id" : Integer (12) }

Use this function when redeeming a gift card for an existing customer.

Parameters

Option	Type	Description	Example
card	VARCHAR (15)	The number of the gift card	159674498565330
user_id	Integer (12)	The user id belonging to the customer.	10676

Request

{
	"username": "api_sandbox@bayiq.com",
        "password": "password",
	"action": "redeemGiftCard",
	"data": {
                    "card": "159674498565330",
                    "user_id": 10676
                }
}

Response

Success

Array
(
    [status]    => success
    [code]      => 1
    [message]   => Card Redeemed! Added 834 points.
)

Card Not Found / Already Redeemed

Array
(
    [status]    => failed
    [error]     => This gift card does not exist or it has already been redeemed.
    [code]      => 1405
)

Import

action

"import"

data

{ "data" : Object }

This function will import data into a dealers Prospect Database.

Customer Object required

Option	Type	Description	Example
customer_id	Integer (12)	The customer ID	25386333
name_first	VARCHAR (128)	The first name of the rewards customer	John
name_last	VARCHAR (128)	The last name of the rewards customer	Doe
store_id	VARCHAR (32)	The store ID this customer belongs to.	342\|CT-1\|Downtown
type	VARCHAR (16)	The type of customer account.	Retail
company	VARCHAR (128)	The name of the company if this is a commercial account	ABC Company Inc.\|null
address	VARCHAR (128)	Customer address	123 S. Western St.
address2	VARCHAR (32)	Customer unit address	#212 \| null
city	VARCHAR (128)	City	Phoenix
state	VARCHAR (2)	State	AZ
zip	VARCHAR (5)	Customer zip code	85001
email	VARCHAR (128)	The email address belonging to the rewards customer. If a customer does not have an email address or chooses to opt-out then use the term "optout" in place of an actual email address. This will auto-generate an address for the customer and will be provided in the response for reference.	john.doe@example.com
phone_mobile	VARCHAR (10)	The mobile phone number belonging to the customer	4801234321
phone_home	VARCHAR (10)	The home phone number belonging to the customer	4801234321
phone_work	VARCHAR (10)	The work number belonging to the customer	4801234321

Vehicle Object required

Parameter	Type	Description	Example
vehicle_id	Integer (12)	Vehicle ID	45698712345
year	Integer (4)	Year built	1997 2005 2016
make	VARCHAR (64)	Vehicle make	Toyota Ford Cadillac
model	VARCHAR (64)	Vehicle model	Camry Mustang Fleetwood
mileage	Integer (12)	Vehicle mileage	80500 102459 null
plate	VARCHAR (12)	Vehicle plate number	BHR5034 SL33P3R AZN0112 null
vin	VARCHAR (32)	Vehicle VIN	1FMCU9G94FUA13888 null

Transaction Object required

Parameters

Option	Type	Description	Example
tech_writer	VARCHAR (64)	The name of the tech writer	John Doe
employee_id	VARCHAR (64)	The ID of the employee/tech writer	JD001
invoice_number	VARCHAR (64)	The invoice number	1-61102\|94485210
mileage_in	VARCHAR (12)	Mileage of the serviced vehicle	132589
labor_total	VARCHAR (12)	The total cost of labor.	123.99
parts_total	VARCHAR (12)	The total cost of parts.	75.99
tax1	VARCHAR (12)	The total cost of taxes.	14.28
tax2	VARCHAR (12)	Additional tax field.	8.18\|null
tax3	VARCHAR (12)	Additional tax field.	8.18\|null
total	VARCHAR (12)	The total charge of the invoice.	1336.88
payment_type	VARCHAR (255)	The type of payment(s) used.	Visa\|Cash,Debit\|Mastercard
invoice_date	VARCHAR (32)	The date of the invoice.	2016-04-15 12:00:00
description	TEXT	A description for the work performed on the invoice.	Front and rear break pads \| null

Line Item Object required

This object is a nested array of line items.

Paramaters

Option	Type	Description	Example
technician	VARCHAR (64)	Name of the technician who performaned the line item	James Brown null
line_type	VARCHAR (32)	Type of line item	Labor Service New Parts null
code	VARCHAR (32)	A code reference or part number	K&N-F-1b bosch2ply Fram82 null
vendor	VARCHAR (128)	Vendor or distributor for parts	FAST Distributors null
manufacturer	VARCHAR (128)	Manufacturer name for parts	Holley AED Bosch null
quantity	VARCHAR (12)	The number of items used in the line item	4 8 -1 null
description	VARCHAR(128)	A description about the line item	4-Barrel Carb Wiper Fluid Synthetic 10W-30 null
cost	Decimal	The cost to the dealer* for the line item*	11.75 0.99 84.00 null
price	Decimal	The price the dealer* charges the customer for the line item*	15.00 129.99 -25.00 null
total	Decimal	The total charge for the line item including* fees and taxes.*	15.00 129.99 -25.00 null
declined_service	Boolean	A service the customer declined	1 null
details	VARCHAR(255)	Details about the line item	TIRE DISPOSAL REPAIR LABOR OIL-BULK 10W-30 null
pkg_id	VARCHAR(64)	If the line item is part of a package then include the package ID here	130256852 null
labor_code	VARCHAR(64)	A labor code if one exists	SW1 34215 ABC123 null
size	VARCHAR(64)	A size associated to the line item, i.e. tires	LT235/85R16/10 235/60R16 null
taxable	Boolean	Identifies if the line item taxable	1 0
tax	Decimal	The tax applied to the line item	15.23 9.69 null
use_qty	Decimal	The quantity used for the line item, i.e. oil	4.25 3.00 0.00 null
max_qty	Decimal	The maximum quantity allowed for the line item, i.e. quarts of oil	6.00 5.00 null
item_type	VARCHAR(255)	The item type	Maintenance Warranty Lubrication Parts null
atd_mfg	VARCHAR(255)	The ATD manufacturer	Continental BFG null
atd_id	VARCHAR(255)	The ATD id	CT53a B051HrT null
part_number	VARCHAR(255)	A part number associated to the line item	402289477 EN000001 null

Example

An object containing 3 line items;


 [{
    "technician": "Larry Guy",
    "line_type": "New Parts",
    "code": "454SS",
    "vendor": "Racetech distributors",
    "manufacturer": "Holley",
    "quantity": "1",
    "description": "4 barrel carb",
    "cost": 214.19,
    "price": 277.99,
    "total": 305,
    "declined_service": null
}, {
    "technician": "Larry Guy",
    "line_type": "Extra",
    "code": "ABC123",
    "vendor": "Fastcar supplies",
    "manufacturer": "GoodStuff N More",
    "quantity": "3",
    "description": "Cool decals",
    "cost": 4.99,
    "price": 7.29,
    "total": 8.85,
    "declined_service": 1
}, {
    "technician": "Larry Guy",
    "line_type": "Misc",
    "code": "WOW711",
    "vendor": "Blades warehouse",
    "manufacturer": "Rainex",
    "quantity": "2",
    "description": "Best wiper-blades in town",
    "cost": 14.99,
    "price": 17.29,
    "total": 18.85,
    "declined_service": null
}]

Putting It All Together

Request

{
	"username": "api-2@bayiq.com",
	"password": "6f83d37a03ce3dc5935b",
	"action": "import",
	"data": {
		"Customer": {
			"customer_id": 701760,
			"name_first": "James",
			"name_last": "Brown",
			"store_id": "194",
			"type": "Retail",
			"company": null,
			"address": "1475 N 150TH AVE",
			"address2": "",
			"city": "Tempe",
			"state": "Arizona",
			"zip": 85281,
			"email": "",
			"phone_mobile": "123-234-3456",
			"phone_home": "",
			"phone_work": ""
		},
		"LineItems": [{
    "technician": "Larry Guy",
    "line_type": "New Parts",
    "code": "454SS",
    "vendor": "Racetech distributors",
    "manufacturer": "Holley",
    "quantity": "1",
    "description": "4 barrel carb",
    "cost": 214.19,
    "price": 277.99,
    "total": 305,
    "declined_service": null
}, {
    "technician": "Larry Guy",
    "line_type": "Extra",
    "code": "ABC123",
    "vendor": "Fastcar supplies",
    "manufacturer": "GoodStuff N More",
    "quantity": "3",
    "description": "Cool decals",
    "cost": 4.99,
    "price": 7.29,
    "total": 8.85,
    "declined_service": 1
}, {
    "technician": "Larry Guy",
    "line_type": "Misc",
    "code": "WOW711",
    "vendor": "Blades warehouse",
    "manufacturer": "Rainex",
    "quantity": "2",
    "description": "Best wiper-blades in town",
    "cost": 14.99,
    "price": 17.29,
    "total": 18.85,
    "declined_service": null
}],
		"Vehicle": {
			"vehicle_id": 3113166,
			"year": 2007,
			"make": "Corvette",
			"model": "Z06",
			"engine": "454 SS",
			"vin": "1FTHF25HXLKA05274",
			"plate": "ABC4321",
			"color": "White",
			"mileage": 10568,
			"lastin_date": "2015-04-30 12:00:00"
		},
		"WorkOrder": {
			"tech_writer": "Larry J.",
			"employee_id": "LJ001",
			"mileage_in": 31874,
			"labor_total": 65.5,
			"parts_total": 34,
			"estimate": "",
			"tax1": 3.5,
			"tax2": 11.25,
			"tax3": 0.13,
			"total": 123.25,
			"payment_type": "Visa",
			"other_charges": 1,
			"discount": null,
			"invoice_date": "2015-12-15 12:00:00",
			"description": "Front and rear break pads; tire rotation."
		}
	}
}

Appointment Scheduler

BAYiQ has developed a robust appointment scheduler that can integrate directly into your system and operates independently per shop location. Our appointment scheduler uses Google Calendar which means your appointments can be accessed from anywhere.

Since our appointment scheduler is specific per location, a store number is required for each API request.

Get Services

action

"getAvailableServices"

data

{ "store_number" : VARCHAR (64) }

This function will return all of the services available for a given store. The service IDs originate from your system.

Parameters

Option	Type	Description	Example
store_number	VARCHAR (64)	The shop location number.	6 \| 24 \| 82

Request

{
	"username": "api_sandbox@bayiq.com",
        "password": "password",
	"action": "getAvailableServices",
	"data": {
                    "store_number": 1
                }
}

Response

Success

{
	"status": "success",
	"code": 1,
	"services": [
                        {
                            "id": "420",
                            "name": "Tire Replacement"
                        },
                        {
                            "id": "228",
                            "name": "Tire Rotation"
                        },
                        {
                            "id": "230",
                            "name": "Wheel Alignment"
                        },
                        {
                            "id": "360",
                            "name": "Flat Repair"
                        },
                        {
                            "id": "3601",
                            "name": "Starting & Charging/Battery"
                        }
                    ]
}

Unknown store number

If this error occurs please contact BAYiQ support

{
    "status": "failed",
    "error": "Unknown store number : 22",
    "code": 506
}

Create Appointment

action

"createAppointment"

data

{ "appointment" : Object, "services" : Array, "store_number : VARCHAR(64) }

Use this function to create a future appointment.

The field called updated is provided in the response. Store this value in your database along with the appointment id. If the updated value differs from the value you have stored, then the appointment has since been updated when you last stored it.

Appointment Object

Parameters

Option	Type	Description	Example
scheduled_date	VARCHAR (16)	The date of the appointment in a 24-hour format	2018-08-15 12:45:00
first_name	VARCHAR (32)	First name of customer; can be empty string	John
last_name	VARCHAR (12)	Last name of customer	Doe
email	VARCHAR (64)	The email address of the customer; can be empty	john@doe.com
phone	Integer (10)	The phone number of the customer	4801234321
email_reminder	Bool (1)	Send customer an email appointment	1 \| 0 \|null
sms_reminder	Bool (1)	Send customer a text appointment	1 \| 2 \| null
year	Integer (4)	The vehicle year	2010
make	VARCHAR (64)	The vehicle make	Dodge \| Toyota
model	VARCHAR (64)	The vehicle model	Ram \| Tundra
vin	VARCHAR (64)	The vehicle VIN	2GNALBEK7C6233930
notes	TEXT	Any notes about the appointment	The customer needs wheelchair access

Services Array

Parameters

Option	Type	Description	Example
service	ARRAY	An array of service IDs	[432,228] \| [228]

Store Number

Parameters

Option	Type	Description	Example
store_number	VARCHAR (64)	The shop location number.	6 \| 24 \| 82

Request

{
	"username": "api_sandbox@bayiq.com",
        "password": "password",
	"action": "createAppointment",
	"data": {
		"appointment": {
			"scheduled_date": "2018-08-17 12:45:00",
			"first_name": "John",
			"last_name": "Doe",
			"phone": "2132344321",
			"email": "john@doe.com",
			"email_reminder": 1,
			"sms_reminder": 0,
                        "year": 2008,
                        "make": "Dodge",
                        "model": "Ram",
                        "vin":" 123234345asn2324"
                        "notes": "Customer wants interior kept clean"
		},
		"services": [432],
		"store_number": 223
	}
}

Response

Success

When an appointment is successfully created the appointment_id is provided for future use.

{
	"status": "success",
	"code": 1,
	"message": "appointment created",
	"appointment_id": "183",
	"google_event_id": "fjad4sf36d85f14hadbvcp1is4",
	"updated":1534610622

}

Invalid Service

This error will occur when an appointment is being created for a service that does not belong to the store

{
	"status": "failed",
	"error": "Invalid service id:228",
	"code": 1805
}

Missing Reminder

If the email reminder or sms reminder is enabled and neither option is provided when creating an appointment then this error will occur.

{
	"status": "failed",
	"error": "Invalid Values for Reminders",
	"code": 1804
}

Invalid Date

Supplying an invalid appointment date will result in the following error

{
	"status": "failed",
	"error": "Appointment Date must be a Future Date",
	"code": 1804
}

Schedule Full

Creating an appointment in a full time slot will result in the following error

{
	"status": "failed",
	"error": "No more appointments available for the selected time",
	"code": 1804
}

Unknown store number

If this error occurs please contact BAYiQ support

{
    "status": "failed",
    "error": "Unknown store number : 22",
    "code": 506
}

Update Appointment

action

"updateAppointment"

data

{ "appointment" : Object, "services" : Array, "store_number : VARCHAR(64) }

This function follows the same payload as creating an appointment, but must include an appointment id

Appointment Object

Parameters

Option	Type	Description	Example
id	Integer (10)	The ID of an existing appointment	183 \| 4210
scheduled_date	VARCHAR (16)	The date of the appointment in a 24-hour format	2018-08-15 12:45:00
first_name	VARCHAR (32)	First name of customer; can be empty string	John
last_name	VARCHAR (12)	Last name of customer	Doe
email	VARCHAR (64)	The email address of the customer; can be empty	john@doe.com
phone	Integer (10)	The phone number of the customer	4801234321
email_reminder	Bool (1)	Send customer an email appointment	1 \| 0 \|null
sms_reminder	Bool (1)	Send customer a text appointment	1 \| 2 \| null
year	Integer (4)	The vehicle year	2010
make	VARCHAR (64)	The vehicle make	Dodge \| Toyota
model	VARCHAR (64)	The vehicle model	Ram \| Tundra
vin	VARCHAR (64)	The vehicle VIN	2GNALBEK7C6233930
notes	TEXT	Any notes about the appointment	The customer needs wheelchair access

Services Array

Parameters

Option	Type	Description	Example
service	ARRAY	An array of service IDs	[432,228] \| [228]

Store Number

Parameters

Option	Type	Description	Example
store_number	VARCHAR (64)	The shop location number.	6 \| 24 \| 82

Request

{
	"username": "api_sandbox@bayiq.com",
        "password": "password",
	"action": "updateAppointment",
	"data": {
		"appointment": {
			"id": 183,
			"scheduled_date": "2018-08-17 12:45:00",
			"first_name": "John",
			"last_name": "Doe",
			"phone": "2132344321",
			"email": "john@doe.com",
			"email_reminder": 1,
			"sms_reminder": 0,
			"year": 2008,
                        "make": "Dodge",
                        "model": "Ram",
                        "vin":" 123234345asn2324"
                        "notes": "Customer wants interior kept clean"
		},
		"services": [432],
		"store_number": 223
	}
}

Response

Success

Successfully updating an existing appointment

{
	"status": "success",
	"code": 1,
	"message":"appointment updated",
        "updated":1534610622,
}

Invalid Appointment ID

Attempting to update an appointment that does not exist

{
	"status": "failed",
	"error": "Invalid appointment id",
	"code": 1801
}

Invalid Service

This error will occur when an appointment is being updated for a service that does not belong to the store

{
	"status": "failed",
	"error": "Invalid service id:228",
	"code": 1805
}

Missing Reminder

If the email reminder or sms reminder is enabled and neither option is provided when updating an appointment then this error will occur.

{
	"status": "failed",
	"error": "Invalid Values for Reminders",
	"code": 1804
}

Invalid Date

Supplying an invalid appointment date will result in the following error

{
	"status": "failed",
	"error": "Appointment Date must be a Future Date",
	"code": 1804
}

Schedule Full

Updating an appointment in a full time slot will result in the following error

{
	"status": "failed",
	"error": "No more appointments available for the selected time",
	"code": 1804
}

Unknown store number

If this error occurs please contact BAYiQ support

{
    "status": "failed",
    "error": "Unknown store number : 22",
    "code": 506
}

Cancel Appointment

action

"cancelAppointment"

data

{ "id" : Integer (10), "store_number" : VARCHAR (64) }

Use this function to cancel an existing appointment

Parameters

Option	Type	Description	Example
id	Integer (10)	The appointment ID.	136 \| 9831
store_number	VARCHAR (64)	The shop location number.	6 \| 24 \| 82

Request

{
	"username": "api_sandbox@bayiq.com",
        "password": "password",
	"action": "cancelAppointment",
	"data": {
                    "id": 182,
                    "store_number": 1
                }
}

Response

Success

{
	"status": "success",
	"code": 1,
	"message":"appointment cancelled"
}

Invalid Appointment ID

Attempting to cancel an appointment that does not exist

{
	"status": "failed",
	"error": "Invalid appointment id",
	"code": 1801
}

Access Denied

Attempting to cancel an appointment that does not belong to the store

{
	"status": "failed",
	"error": "Access denied to appointment id",
	"code": 1802
}

Unknown store number

If this error occurs please contact BAYiQ support

{
    "status": "failed",
    "error": "Unknown store number : 22",
    "code": 506
}

Get Appointments By Date

action

"getAppointmentsByDate"

data

{ "start_date" : Date, "end_date" : Date, "store_number" : VARCHAR (64) }

Get a list of appointment for a given date range

Parameters

Option	Type	Description	Example
start_date	Date	Start date in a 24-hour format	2018-08-01 00:00:00
end_date	Date	End date in a 24-hour format	2018-08-14 12:45:00
store_number	VARCHAR (64)	The shop location number.	6 \| 24 \| 82

Request

{
    "username": "api_sandbox@bayiq.com",
    "password": "password",
    "action": "getAppointmentsByDate",
    "data": {
            "start_date": "2018-08-01",
            "end_date": "2018-08-31",
            "store_number": 1
    }
}

Response

Success

{
	"status": "success",
	"code": 1,
	"message": "5 result(s) found",
	"appointments": [{
			"id": "166",
			"google_event_id": "eeg0334c7u1k6i7o2s6lpq4ems",
			"scheduled_date": "2018-08-10",
			"status": "Scheduled",
			"first_name": "John",
			"last_name": "Doe",
			"email": "john@doe.com",
			"phone": "1232343456",
			"year": 2010,
			"make": "Dodge",
			"model": "Ram",
			"vin": "1FMCU0HX2DUA35653",
			"email_reminder": "1",
			"sms_reminder": "0",
                        "updated":1534610909,
                        "notes":"",
			"services": [{
				"id": "226",
				"name": "Oil & Filter Change",
				"description": "",
				"duration": null
			}]
		},

		{
			"id": "173",
			"google_event_id": "suin8o8ksks84d9ajgge2s7fc8",
			"scheduled_date": "2018-08-05",
			"status": "Scheduled",
			"first_name": "James",
			"last_name": "Brown",
			"email": "james@brown.com",
			"phone": "1232343456",
			"year": 2011,
			"make": "Toyota",
			"model": "Tundra",
			"vin": "5NPEB4AC0CH340367",
			"email_reminder": "1",
			"sms_reminder": "0",
                        "updated":1534610122,
                        "notes":"",
			"services": [{
					"id": "226",
					"name": "Oil & Filter Change",
					"description": "",
					"duration": null
				},
				{
					"id": "420",
					"name": "Tire Replacement",
					"description": "",
					"duration": null
				}
			]
		},


		{
			"id": "176",
			"google_event_id": "4iv8hfqnhrdqe5vj6773s9cmes",
			"scheduled_date": "2018-08-05",
			"status": "Scheduled",
			"first_name": "Jane",
			"last_name": "Roe",
			"email": "jane@roe.com",
			"phone": "1232343456",
			"year": 2019,
			"make": "Chevrolet",
			"model": "Silverado 1500",
			"vin": "5NPEB4AC0CH340367",
			"email_reminder": "1",
			"sms_reminder": "1",
                        "updated":1534610408,
                        "notes":"",
			"services": [{
				"id": "226",
				"name": "Oil & Filter Change",
				"description": "",
				"duration": null
			}, {
				"id": "360",
				"name": "Flat Repair",
				"description": "",
				"duration": null
			}]
		},
		{
			"id": "180",
			"google_event_id": "28u39pvsuuphsj3rbkvck4uh78",
			"scheduled_date": "2018-08-10",
			"status": "Scheduled",
			"first_name": "Ricky",
			"last_name": "Bobby",
			"email": "ricky@bobby.com",
			"phone": "4565676789",
			"year": null,
			"make": "",
			"model": "",
			"email_reminder": "1",
			"sms_reminder": "0",
			"services": [{
				"id": "70",
				"name": "Brakes",
				"description": "",
				"duration": null
			}]
		},
		{
			"id": "183",
			"google_event_id": "7ablibjb5lba0s3h4jp8d96vk8",
			"scheduled_date": "2018-08-15",
			"status": "Scheduled",
			"first_name": "Ivan",
			"last_name": "Drago",
			"email": "ivan@drago.com",
			"phone": "6784562345",
			"year": null,
			"make": "",
			"model": "",
			"email_reminder": "1",
			"sms_reminder": "0",
			"services": [{
					"id": "228",
					"name": "Tire Rotation",
					"description": "",
					"duration": null
				},
				{
					"id": "3601",
					"name": "New Battery",
					"description": "",
					"duration": null
				}
			]
		}
	]
}

Invalid Date Range

{
	"status": "failed",
	"error": "date range is invalid",
	"code": 1501
}

Unknown store number

If this error occurs please contact BAYiQ support

{
    "status": "failed",
    "error": "Unknown store number : 22",
    "code": 506
}

Get Appointment By ID

action

"getAppointmentById"

data

{ "id" : Integer (10), "store_number" : VARCHAR (64) }

Get a specific appointment by ID. This function's response is identical to getAppointmentsByDate except that it only returns 1 result

Parameters

Option	Type	Description	Example
id	Integer (10)	The appointment ID	136 \| 9831
store_number	VARCHAR (64)	The shop location number.	6 \| 24 \| 82

Request

{
	"username": "api_sandbox@bayiq.com",
        "password": "password",
	"action": "getAppointmentById",
	"data": {
                    "id": 166,
                    "store_number": 1
                }
}

Response

Success

{
	"status": "success",
	"code": 1,
	"message": "1 result found",
	"appointments": [{
			"id": "166",
			"google_event_id": "eeg0334c7u1k6i7o2s6lpq4ems",
			"scheduled_date": "2018-08-10",
			"status": "Scheduled",
			"first_name": "John",
			"last_name": "Doe",
			"email": "john@doe.com",
			"phone": "1232343456",
			"year": 2017,
			"make": "Ford",
			"model": "F150",
			"vin": "3MZBM1V78FM164964",
			"email_reminder": "1",
			"sms_reminder": "0",
                        "updated":1534610622,
                        "notes":"",
			"services": [{
				"id": "226",
				"name": "Oil & Filter Change",
				"description": "",
				"duration": null
			}]
		}]
}

Invalid Appointment ID

{
	"status": "failed",
	"error": "Invalid appointment id",
	"code": 1801
}

Access Denied

Attempting to retrieve an appointment that does not belong to the store

{
	"status": "failed",
	"error": "Access denied to appointment id",
	"code": 1802
}

Unknown store number

If this error occurs please contact BAYiQ support

{
    "status": "failed",
    "error": "Unknown store number : 22",
    "code": 506
}

API Documentation An in-depth guide to the BAYiQ Rewards Platform

Overview

Introduction

Data

POST

API Endpoints

Sandbox

Production

Search Customers

action

data

Search (required)

Request

Response

Success

Response

Success

No results

Search Customers

action

data

Retrieve User (required)

Request

Response

Success

Response

Success

No results

Register Customers

action

data

Customer Object

Request

Response

Success

Card Not Found

Add Vehicles

action

data

Vehicle Object

User ID required

Parameter

Request

Response

Success

Missing Parameter

Process Transaction

action

data

Transaction Object

Parameters

User ID required

Parameter

Vehicle Object optional see above

Rewards Object optional

Paramaters

Examples

Bonuses, Promotions and Money

Only 1 Bonus

Use $4.20 in rewards

Line Item Object required

Paramaters

Example

An object containing 3 line items;

Putting It All Together

Request

Response

Success

Error

Error

Redeem Gift Card

action

data

Parameters

Request

Response

Success

Card Not Found / Already Redeemed

Import

action

API Documentation
An in-depth guide to the BAYiQ Rewards Platform