API Documentation for BayEngage (1.0.0)

Download OpenAPI specification:Download

This is a documentation that covers all of BayEngage's Custom APIs

Contacts

Receive customer data from a custom app into BayEngage. (Note - This a Protected API and requires Private API key to access it. Don't expose this keys in the browser)

Create an Email contact in BayEngage

Contact details can be included along with the Email contact. A new contact will be created for the provided email. If contact already exists, contact details will be updated.

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can generate it under the name 'Client Secret (private key)'.

x-public-id
required
string
Example: 7b74ec988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can find it under the name 'Client ID'.

Request Body schema: application/json
id
integer

This is the customer ID that your maintain in your platform.

email
required
string

This is the email address of the customer. Either email or phone is mandatory.

phone
string

This is the phone number of the customer.

source
required
string
Default: "api"

This is an identification for source of contact creation. The source is mandatory to create the contact.

email_subscription
required
string

The subscription status of the customer. Possible values are active or unsub. The contact is added as subscribed or unsubscribed based on this value.

phone_optin_trigger
boolean
Enum: true false

Indicates whether to trigger an SMS opt-in message to the provided phone number. Set to "true" to send opt-in message; "false" to skip.

phone_optin_trigger will not work by default, reach support@targetbay.com for activation.

phone_subscription
string

Possible values are "unverified", "unsub"

phone_subscription will not work by default, reach support@targetbay.com for activation.

phone_existing_subscription
string

Possible values is "retain". By using this key user account phone status will not override.

Learn more. https://help.targetbay.com/s/article/Understanding-the-phone-existing-subscription-Field-in-the-Create-Contact-API

tags
object

This is for the purpose of grouping. The values are added as shopify tags.

custom_fields
object
first_name
string

This is the customer's first name

last_name
string

This is the customer's last name

address1
string
address2
string
city
string
province
string
zip
string
country
string
list_id
string

This is the list UUID where your contact have been added to in BayEngage. You can find the List UUID is the list settings page. If this UUID misspelled or not provided your contact will be added into website contact default list.

Responses

Request samples

Content type
application/json
{
  • "id": 984112,
  • "email": "johndoe@targetbay.com",
  • "phone": "+1xxxxxxxxxx",
  • "source": "api",
  • "email_subscription": "active",
  • "phone_optin_trigger": false,
  • "phone_subscription": "unverified",
  • "phone_existing_subscription": "retain",
  • "tags": [
    ],
  • "custom_fields": [
    ],
  • "first_name": "John",
  • "last_name": "Doe",
  • "address1": "Melrose Avenue",
  • "address2": 102,
  • "city": "Los Angeles",
  • "province": "Michigan",
  • "zip": 30303,
  • "country": "United States",
  • "list_id": "58133f44864d"
}

Update an Email contact in BayEngage

Update an Email contact in BayEngage

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can generate it under the name 'Client Secret (private key)'.

x-public-id
required
string
Example: 7b74ec988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can find it under the name 'Client ID'.

Request Body schema: application/json
id
string

This is the customer ID that your maintain in your platform.

email
required
string

This is the email address of the customer.

phone
string

This is the phone number of the customer.

source
required
string
Default: "api"

This is an identification for source of contact creation. The source is mandatory to create the contact.

email_subscription
required
string

The subscription status of the customer. Possible values are active or unsub. The contact is added as subscribed or unsubscribed based on this value.

phone_optin_trigger
boolean
Enum: true false

Indicates whether to trigger an SMS opt-in message to the provided phone number. Set to "true" to send opt-in message; "false" to skip.

phone_optin_trigger will not work by default, reach support@targetbay.com for activation.

phone_subscription
string

Possible values are "unverified", "unsub"

phone_subscription will not work by default, reach support@targetbay.com for activation.

phone_existing_subscription
string

Possible values is "retain". By using this key user account phone status will not override.

Learn more. https://help.targetbay.com/s/article/Understanding-the-phone-existing-subscription-Field-in-the-Create-Contact-API

tags
object

This is for the purpose of grouping. The values are added as shopify tags.

custom_fields
object
first_name
string

This is the customer's first name

last_name
string

This is the customer's last name

address1
string
address2
string
city
string
province
string
zip
string
country
string

Responses

Request samples

Content type
application/json
{
  • "id": 984112,
  • "email": "johndoe@targetbay.com",
  • "phone": "+1xxxxxxxxxx",
  • "source": "api",
  • "email_subscription": "active",
  • "phone_optin_trigger": false,
  • "phone_subscription": "unverified",
  • "phone_existing_subscription": "retain",
  • "tags": [
    ],
  • "custom_fields": [
    ],
  • "first_name": "John",
  • "last_name": "Doe",
  • "address1": "Melrose Avenue",
  • "address2": 102,
  • "city": "Los Angeles",
  • "province": "Michigan",
  • "zip": 30303,
  • "country": "United States"
}

Fetch all email contacts in BayEngage

The API that should be used to fetch all contacts in BayEngage.

query Parameters
page
integer >= 1
Default: 1

The page number for pagination.

limit
integer <= 100
Default: 25

The number of items to return per page. The default value is 25 items and the maximum is 100 per page.

fields
string
Enum: "tags" "custom_fields"

Getting extra details for the customers.

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can generate it under the name 'Client Secret (private key)'.

x-public-id
required
string
Example: 7b74ec988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can find it under the name 'Client ID'.

Responses

Create multiple Email contacts at once in BayEngage

Contact details can be included along with the Email contacts. A new contact will be created for the provided email if it does not already exist. The contact details will be updated if eamil contact already exists.

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can generate it under the name 'Client Secret (private key)'.

x-public-id
required
string
Example: 7b74ec988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can find it under the name 'Client ID'.

Request Body schema: application/json
Array of objects

The array that contains the list of subscribers

Responses

Request samples

Content type
application/json
{
  • "subscribers": [
    ]
}

Delete an Email contact in BayEngage

Delete an Email contact in BayEngage

path Parameters
id
required
integer

The customer ID that you wish to delete

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can generate it under the name 'Client Secret (private key)'.

x-public-id
required
string
Example: 7b74ec988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can find it under the name 'Client ID'.

Responses

Search an Email or Phone contact in BayEngage

Search for an email or phone contact from BayEngage.

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can generate it under the name 'Client Secret (private key)'.

x-public-id
required
string
Example: 7b74ec988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can find it under the name 'Client ID'.

Request Body schema: application/json
email
string

The email address that you want to search. Either phone or email is mandatory.

phone
string

The phone number that you want to search. Either phone or email is mandatory.

Responses

Request samples

Content type
application/json
{
  • "email": "johndoe@targetbay.com",
  • "phone": 8967540319
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": 200,
  • "message": "OK",
  • "data": {
    }
}

Category

Receive category data from a custom app into BayEngage. (Note - This a Protected API and requires Private API key to access it. Don't expose this keys in the browser)

Create category in BayEngage

Create category in BayEngage

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

A unique key provided for each client.

x-public-id
required
string
Example: 7b74ec988ffa

The ID provided for each BayEngage account.

Request Body schema: application/json
category_id
required
string

Category ID

parent_id
string

Parent ID

name
required
string

Category Name

code
required
string

Category code

Responses

Request samples

Content type
application/json
{
  • "category_id": 10,
  • "parent_id": 1,
  • "name": "shirts-men",
  • "code": "shirts-men"
}

Update category in BayEngage

Update category in BayEngage

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

A unique key provided for each client.

x-public-id
required
string
Example: 7b74ec988ffa

The ID provided for each BayEngage account.

Request Body schema: application/json
category_id
required
string

Category ID

parent_id
string

Parent ID

name
required
string

Category Name

code
required
string

Category code

Responses

Request samples

Content type
application/json
{
  • "category_id": 10,
  • "parent_id": 1,
  • "name": "shirts-men",
  • "code": "shirts-men"
}

Delete category in BayEngage

Delete category in BayEngage

path Parameters
id
required
integer

The category ID

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

A unique key provided for each client.

x-public-id
required
string
Example: 7b74ec988ffa

The ID provided for each BayEngage account.

Responses

Products

Receive product data from a custom app into BayEngage. (Note - This a Protected API and requires Private API key to access it. Don't expose this keys in the browser)

Create product in BayEngage

Create product in BayEngage

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can generate it under the name 'Client Secret (private key)'.

x-public-id
required
string
Example: 7b74ec988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can find it under the name 'Client ID'.

Request Body schema: application/json
product_id
required
integer

This is the unique ID of the product.

product_title
required
string

This is the name of the product.

description
string

A detailed description about the product.

vendor
string

The vendor of the product.

product_type
required
string

The type of the product. It must either be simple or variant. If your product has multipe variants, use the type 'variant'.

product_url
string

The URL of the product.

product_status
integer

The status of the product. If the status is 1, then the product is 'Active'. If 0, then the product is 'Inactive/Draft'. Default is 1.

Array of objects

The category information of the product.

tags
string

Tags can be used for filtering.

required
Array of objects

This is the detailed variant information.

Array of objects

The image information of the product.

object

custom fields store personalized data.

Responses

Request samples

Content type
application/json
{
  • "product_id": 10,
  • "product_title": "pink shirt",
  • "description": "New Collection pink- t-shirt",
  • "vendor": "Puma",
  • "product_type": "simple or variant",
  • "product_status": "<1 or 0>",
  • "product_category": [
    ],
  • "tags": "t-shirt,mens,pink",
  • "variants": [
    ],
  • "images": [],
  • "custom": {
    }
}

Update product in BayEngage

Update product in BayEngage

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can generate it under the name 'Client Secret (private key)'.

x-public-id
required
string
Example: 7b74ec988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can find it under the name 'Client ID'.

Request Body schema: application/json
product_id
required
integer

This is the unique ID of the product.

product_title
required
string

This is the name of the product.

description
string

A detailed description about the product.

vendor
string

The vendor of the product.

product_type
required
string

The type of the product. It must either be simple or variant. If your product has multipe variants, use the type 'variant'.

product_url
string

The URL of the product.

product_status
integer

The status of the product. If the status is 1, then the product is 'Active'. If 0, then the product is 'Inactive/Draft'. Default is 1.

Array of objects

The category information of the product.

tags
string

Tags can be used for filtering.

required
Array of objects

This is the detailed variant information.

Array of objects

The image information of the product.

object

custom fields store personalized data.

Responses

Request samples

Content type
application/json
{
  • "product_id": 10,
  • "product_title": "pink shirt",
  • "description": "New Collection pink- t-shirt",
  • "vendor": "Puma",
  • "product_type": "simple or variant",
  • "product_status": "<1 or 0>",
  • "product_category": [
    ],
  • "tags": "t-shirt,mens,pink",
  • "variants": [
    ],
  • "images": [],
  • "custom": {
    }
}

Delete product in BayEngage

Delete product in BayEngage

path Parameters
id
required
integer

This is the product ID.

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can generate it under the name 'Client Secret (private key)'.

x-public-id
required
string
Example: 7b74ec988ffa

This can be found in the settings page of 'Custom integration' under 'Apps'. You can find it under the name 'Client ID'.

Responses

Orders

Receive order data from a custom app into BayEngage. (Note - This a Protected API and requires Private API key to access it. Don't expose this keys in the browser)

Create order in BayEngage

Create order in BayEngage

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

A unique key provided for each client.

x-public-id
required
string
Example: 7b74ec988ffa

The ID provided for each BayEngage account.

Request Body schema: application/json
id
required
string

Order ID

customer_id
string

Customer ID

email
required
string

Customer email

cart_token
required
string

Customer cart token

phone
string

Customer phone number

created_at
required
string

Order created at

completed_at
string

Order updated at

currency
string

Currency

current_subtotal_price
required
string

Current subtotal price

current_total_discounts
string

Current total discounts

current_total_price
required
string

Current total price

current_total_tax
string

Currency

Array of objects
refunds
string
status
required
string

Order status

financial_status
string

Order payment status

fulfillment_status
string

Order fulfillment status

order_number
required
string

Order Number

required
Array of objects
required
Array of objects
required
Array of objects
object

Responses

Request samples

Content type
application/json
{
  • "id": 4112002,
  • "customer_id": 643456,
  • "email": "allutest2@gmail.com",
  • "cart_token": "83d188b46c3396d880c20c187f56e679",
  • "phone": 8990998999,
  • "created_at": "2021-08-04T15:13:40.000Z",
  • "completed_at": "2022-02-02T13:25:20.000Z",
  • "currency": "USD",
  • "current_subtotal_price": 500,
  • "current_total_discounts": 0,
  • "current_total_price": 500,
  • "current_total_tax": 0,
  • "discount_codes": [
    ],
  • "refunds": null,
  • "status": "open",
  • "financial_status": "paid",
  • "fulfillment_status": "pending",
  • "order_number": 5674898,
  • "billing_address": [
    ],
  • "line_items": [
    ],
  • "shipping_address": [
    ],
  • "custom": {
    }
}

Update order in BayEngage

Update order in BayEngage

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

A unique key provided for each client.

x-public-id
required
string
Example: 7b74ec988ffa

The ID provided for each BayEngage account.

Request Body schema: application/json
id
required
string

Order ID

customer_id
string

Customer ID

email
required
string

Customer email

cart_token
required
string

Customer cart token

phone
string

Customer phone number

created_at
required
string

Order created at

completed_at
string

Order updated at

currency
string

Currency

current_subtotal_price
required
number

Current subtotal price

current_total_discounts
number

Current total discounts

current_total_price
required
number

Current total price

current_total_tax
number

Currency

Array of objects
refunds
string
status
required
string

Order status

financial_status
string

Order payment status

fulfillment_status
string

Order fulfillment status

order_number
required
string

Order Number

required
Array of objects
Array of objects
required
Array of objects
required
Array of objects
object

Responses

Request samples

Content type
application/json
{
  • "id": 4112002,
  • "customer_id": 643456,
  • "email": "allutest2@gmail.com",
  • "cart_token": "83d188b46c3396d880c20c187f56e679",
  • "phone": 8990998999,
  • "created_at": "2021-08-04T15:13:40.000Z",
  • "completed_at": "2022-02-02T13:25:20.000Z",
  • "currency": "USD",
  • "current_subtotal_price": 500,
  • "current_total_discounts": 0,
  • "current_total_price": 500,
  • "current_total_tax": 0,
  • "discount_codes": [
    ],
  • "refunds": null,
  • "status": "open",
  • "financial_status": "paid",
  • "fulfillment_status": "pending",
  • "order_number": 5674898,
  • "billing_address": [
    ],
  • "customer": [
    ],
  • "line_items": [
    ],
  • "shipping_address": [
    ],
  • "custom": {
    }
}

Delete order in BayEngage

Delete order in BayEngage

path Parameters
id
required
integer

The order ID

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

A unique key provided for each client.

x-public-id
required
string
Example: 7b74ec988ffa

The ID provided for each BayEngage account.

Responses

Carts

Receives cart data from a custom app into BayEngage. (Note - This a Protected API and requires Private API key to access it. Don't expose this keys in the browser)

Create cart in BayEngage

Create cart in BayEngage

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

A unique key provided for each client.

x-public-id
required
string
Example: 7b74ec988ffa

The ID provided for each BayEngage account.

Request Body schema: application/json
token
required
string

Cart token

email
string

User Email ID

Array of objects
created_at
string

Responses

Request samples

Content type
application/json
{
  • "token": "83d188b46c3396d880c20c187f56e6752898",
  • "email": "primeallu@test.com",
  • "line_items": [
    ],
  • "created_at": "2023-02-02T13:28:28.939Z"
}

Update cart in BayEngage

Update cart in BayEngage

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

A unique key provided for each client.

x-public-id
required
string
Example: 7b74ec988ffa

The ID provided for each BayEngage account.

Request Body schema: application/json
token
required
string

Cart token

email
string

User Email ID

Array of objects

Responses

Request samples

Content type
application/json
{
  • "token": "83d188b46c3396d880c20c187f56e6752898",
  • "email": "primeallu@test.com",
  • "line_items": [
    ]
}

Checkouts

Receives checkout data from a custom app into BayEngage. (Note - This a Protected API and requires Private API key to access it. Don't expose this keys in the browser)

Create checkout in BayEngage

Create checkout in BayEngage

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

A unique key provided for each client.

x-public-id
required
string
Example: 7b74ec988ffa

The ID provided for each BayEngage account.

Request Body schema: application/json
checkout_id
required
integer
token
required
string
email
required
string
buyer_accepts_email_marketing
required
boolean
currency
required
string
required
Array of objects
abandoned_checkout_url
required
string
buyer_accepts_sms_marketing
required
boolean
sms_marketing_phone
required
string
total_price
required
string
total_tax
required
string
subtotal_price
required
string
required
object
required
object

Responses

Request samples

Content type
application/json
{
  • "checkout_id": 0,
  • "token": "string",
  • "email": "string",
  • "buyer_accepts_email_marketing": true,
  • "currency": "string",
  • "line_items": [
    ],
  • "abandoned_checkout_url": "string",
  • "buyer_accepts_sms_marketing": true,
  • "sms_marketing_phone": "string",
  • "total_price": "string",
  • "total_tax": "string",
  • "subtotal_price": "string",
  • "shipping_address": {
    },
  • "customer": {
    }
}

Update checkout in BayEngage

Update checkout in BayEngage

header Parameters
x-client-secret
required
string
Example: uVY6nwVOOc26xB7e7a74bb988ffa

A unique key provided for each client.

x-public-id
required
string
Example: 7b74ec988ffa

The ID provided for each BayEngage account.

Request Body schema: application/json
checkout_id
required
integer
token
required
string
email
required
string
buyer_accepts_email_marketing
required
boolean
currency
required
string
required
Array of objects
abandoned_checkout_url
required
string
buyer_accepts_sms_marketing
required
boolean
sms_marketing_phone
required
string
total_price
required
string
total_tax
required
string
subtotal_price
required
string
required
object
required
object

Responses

Request samples

Content type
application/json
{
  • "checkout_id": 0,
  • "token": "string",
  • "email": "string",
  • "buyer_accepts_email_marketing": true,
  • "currency": "string",
  • "line_items": [
    ],
  • "abandoned_checkout_url": "string",
  • "buyer_accepts_sms_marketing": true,
  • "sms_marketing_phone": "string",
  • "total_price": "string",
  • "total_tax": "string",
  • "subtotal_price": "string",
  • "shipping_address": {
    },
  • "customer": {
    }
}

Activity

Receives an Activity event into BayEngage (Note - This a Public API and only requires the Public API key to access it.)

Create an Activity in BayEngage.

An Activity can be created using the API. A new Activity will be created if it does not already exists. If the Activity already exists, an event for that acitivity will be recorded.

header Parameters
x-public-id
required
string
Example: INSERT_YOUR_CLIENT_ID

The BayEngage tenant's client UUID (You can find it in the admin settings page).

Request Body schema: application/json
key
required
string

The ID provided for each BayEngage account.

activity_name
required
string

The name of the activity that you wish to create.

object

User properties can contain both System fields and Custom fields. System fields are readily available within BayEngage and the data types of such fields are predefined. Custom fields are customizable and can be used for the purpose of storing additional information about the user. The data type of such custom properties can be defined by the sender using the field_type object.

object

Any additional data related to the activity can be included in the activity_properties object. This data can be made use in the email templates. The fields provided are part of the sample data related to the sample acitivty. The sender has to replaced the sample fields with the actual fields as per the requirement.

Responses

Request samples

Content type
application/json
{
  • "key": "INSERT_YOUR_PUBLIC_KEY",
  • "activity_name": "Book rental",
  • "user_properties": {
    },
  • "activity_properties": {
    }
}