All Thirdwatch APIs are authenticated using your API key. Your API key is sent to your registered email id after you activate your account. You can also find this on the Thirdwatch Dashboard, under the Settings → General tab.
Watch this video for more information.
Every API request should contain the API Key X-THIRDWATCH-API-KEY in the header.
Every API request should include your user_id. If this is not available, you can alternatively provide a session_id value.
You can collect customer information by creating a device fingerprint.
A fingerprint is a unique hashed string identifier generated by combining the hashed values of device parameters, such as the user agent, plugins installed, webGL rendering information, device OS, and fonts installed. Thirdwatch’s Fingerprint SDK generates this identifier for the user and passes it to Thirdwatch. This helps identify customers better as the device parameters remain unchanged irrespective of the browsing platform used, cookies, and other application-level identifiers.
To add device fingerprinting to your website, paste the below script on your webpage, just after the opening tag. Add this script to the page that is accessed by your customer. For example, if you want to track three different web pages, paste the below script on each webpage, just after the opening tag.
Do not want to pass device details to Thirdwatch using the front-end?
If you do not want to pass device details to Thirdwatch using the front-end, you can instead use the Thirdwatch Orders API.
Data type string. The unique user id at your end. This can be an email id or primary key in the database. For a guest user, use the session ID.
data-app-secretmandatory
Data type string. The unique App secret generated for you by Thirdwatch.
data-is-track-pageviewoptional
Data type boolean. Possible values:
true (default) - The URL on which this script is running is sent to Thirdwatch.
false - The URL is not captured.
data-session-cookie-nameoptional
Data type string. The cookie name where you are saving the unique session id. Our system picks the session id by our reading its value from the cookie name.
data-session-id-valueoptional
Data type string. If you are not passing data-session-cookie-name, pass the session id using this parameter. If no data-session-cookie-name or data-session-id-value values are available, our system generates a session id.
To use Thirdwatch on your custom-build website, you will have to integrate with the Thirdwatch Orders API. This API contains all the required customer and order information.
Thirdwatch API collects information associated with the life cycle of an order to help you make decisions. You can use the below endpoint to pass data of the events related to the customer and the orders placed during the transaction.
The details of the device used to place the order.
Note: If the device details are passed using the front-end, all the parameters in this array can be passed as empty strings.
ipmandatory
Data type string. The IP address from where the order is placed. For example, 192.178.0.1.
session_idmandatory
Data type string. The unique identifier for the session.
user-agentmandatory
Data type string. The details of the browser used to place the order. For example, Mozilla/5.0.
user
The details of the customer placing the order. This information is vital to understand the fraudulent behaviour of delinquent customers.
idmandatory
Data type string. Your customer’s account id according to your system. This field is case-sensitive. For example, AsXcYnkERrjb.
created_atmandatory
Data type string. The Unix timestamp in milliseconds when the customer account was created in your system. For example, 1578487238129.
emailmandatory
Data type string. The customer's email id. For example, gaurav.kumar@example.com.
Note: If the customer’s email id is also the account id in your system, set both the user_id and email fields to their email id.
first_namemandatory
Data type string. The customer's first name. For example, Gaurav.
last_namemandatory
Data type string. The customer's last name. For example, Kumar.
contactmandatory
Data type string. The customer's phone number. For example, 9123456789.
first_purchasemandatory
Data type boolean. Set to true if the customer is a first-time buyer.
email_verificationmandatory
Data type string. The status of email verification. Possible values:
unverified (default)
pending
verified
contact_verificationmandatory
Data type string. The status of phone number verification. Possible values:
unverified (default)
pending
verified
order
The details of the order.
idmandatory
Data type string. A unique identifier for the order created in your system. For example, Axn167SnweX.
created_atmandatory
Data type string. The Unix timestamp in milliseconds when the order was created in your system. For example, 1578487238129.
amountmandatory
Data type string. The order amount in the currency subunit. For example, if the order amount is ₹15,600 pass 1560000.
currencymandatory
Data type string. The 3-letter ISO currency code for the order amount. For example, INR.
prepaidmandatory
Data type boolean. Pass true if the order is prepaid.
item
This contains an array of items with item details, such as amount, currency, brand, category and quantity.
idmandatory
Data type string. A unique identifier for an item created in your system. Use the same id that you will use to look up items on your website's database. For example, XQF1576BGY.
titlemandatory
Data type string. The item's name. For example, Awesome bag to impress your friends.
amountmandatory
Data type string. The item amount in the currency subunit. For example, if the item amount is ₹15,600 pass 1560000.
currencymandatory
Data type string. The 3-letter currency code for the item amount. For example, INR.
brandmandatory
Data type string. The brand name of the item. For example, Office bags.
categorymandatory
Data type string. The category on your website under which the item is listed. For example, "Office bags", "man > bags".
quantitymandatory
Data type integer. The number or quantity of the item. For example, 4.
is_onsalemandatory
Data type boolean. Set to true if the item is on sale.
skuoptional
Data type string. The stock-keeping unit ID (SKU) for the item, if available. For example, 167380XBGEB.
shipping_address
The address details where the order is to be shipped.
namemandatory
Data type string. The full name associated with the address. For example, Gaurav Kumar. Concatenate first name and last name together if you collect them separately in your system.
phonemandatory
Data type string. The phone number associated with this address. Provide the phone number as a string starting with the country code. For example, +919123456789.
line1mandatory
Data type string. The first line of the shipping address. For example, 221B Bakery Street.
line2mandatory
Data type string. The second line of the address. For example, 14th Main Road, 3rd Cross.
citymandatory
Data type string. The city or town name. For example, Bengaluru.
statemandatory
Data type string. The state where the address is to be shipped. For example, Karnataka.
countrymandatory
Data type string. The 2-letter ISO country code where the order is to be shipped. For example, IN for India.
postal_codemandatory
Data type string. The postal code where the order is to be shipped. For example, 560666.
typemandatory
Data type string. The type of address. Possible values:
home
office
other
promotions
The promotion details applied to the order.
idoptional
Data type string. The unique identifier for the coupon code in your system. For example, ADbb.
statusoptional
Data type string. Use this to pass both successful and failed attempts to Thirdwatch when using a promotion. This may be useful in spotting potential abuse. Possible Values:
applied
failed
typeoptional
Data type string. The type of promotion. Possible values:
discount
cashback
store_credit
voucher
amountoptional
Data type string. The amount of credits the promotion is worth in the currency subunits. For example, if the promotion is worth ₹50, pass 5000.
currencyoptional
Data type string. The 3-letter ISO currency code for the amount. For example, INR.
payment
The payment details for the order.
idmandatory
Data type string. The unique identifier for the payment. This helps to track transactions and to link different parts of the same transaction, such as a refund, together.
statusmandatory
Data type string. The status of the payment. Possible values:
pending
success
failure
gatewaymandatory
Data type string. The gateway used for the payment. For example, razorpay.
amountmandatory
Data type string. The amount for the payment in the currency subunits. For example, if the payment is worth ₹7,500 pass 750000.
currencymandatory
Data type string. The 3-letter ISO currency code for the payment amount. For example, INR.
methodmandatory
Data type string. The method used to make the payment. Possible values:
card
wallet
upi
netbanking
cod
fund_transfer
bankoptional
Data type string. The name of the bank used by the customer to make the payment. For example, State Bank of India.
walletoptional
Data type string. The name of the wallet used by the customer to make the payment. For example, amazonpay.
card
The details of the card used to make the payment.
last4optional
Data type string. The last 4 digits of the card used. For example, 0305
typeoptional
Data type string. The type of card used. Possible values:
debit
credit
gift
prepaid
issueroptional
Data type string. The name of the bank issuing the card. For example, State Bank of India.
internationaloptional
Data type boolean. Pass true if the card has been issued outside India. Default is false.
iinoptional
Data type string. The first 6 digits of the card number. For example, 305619.
expiry_monthoptional
Data type string. The expiry month of the card in MM format. For example, if the card expires in October, pass 10.
expiry_yearoptional
Data type string. The expiry year of the card in YY format. For example, if the expiry year is 2022, pass 22.
nameoptional
Data type string. The name of the cardholder. For example, Gaurav Kumar.
The Thirdwatch Orders API also supports the Seller use case. The Seller entity stores details of the Seller registered on the merchant's website. These details need to be passed with every order request.
The details of the device used to place the order.
Note: If the device details are passed using the front-end, all the parameters in this array can be passed as empty strings.
ipmandatory
Data type string. The IP address from where the order is placed. For example, 192.178.0.1.
session_idmandatory
Data type string. The unique identifier for the session.
user-agentmandatory
Data type string. The details of the browser used to place the order. For example, Mozilla/5.0.
user
The details of the customer making the payment. This information is vital to understand the fraudulent behaviour of delinquent customers.
idmandatory
Data type string. Your customer’s account id according to your system. This field is case-sensitive. For example, AsXcYnkERrjb.
created_atmandatory
Data type string. The Unix timestamp in milliseconds of when the customer account was created in your system. For example, 1578487238129.
emailmandatory
Data type string. The customer's email id. For example, gaurav.kumar@example.com.
Note: If the customer’s email id is also the account id in your system, set both the user_id and email fields to their email id.
first_namemandatory
Data type string. The customer's first name. For example, Gaurav.
last_namemandatory
Data type string. The customer's last name. For example, Kumar.
contactmandatory
Data type string. The customer's phone number. For example, 9123456789.
first_purchasemandatory
Data type boolean. Set to true if the customer is a first-time buyer.
email_verificationmandatory
Data type string. The status of email verification. Possible values:
unverified (default)
pending
verified
contact_verificationmandatory
Data type string. The status of phone number verification. Possible values:
unverified (default)
pending
verified
order
The details of the order that is created.
idmandatory
Data type string. A unique identifier for the order created in your system. For example, Axn167SnweX.
created_atmandatory
Data type string. The Unix timestamp in milliseconds of when the order was created in your system. For example, 1578487238129.
amountmandatory
Data type string. The order amount in the currency subunit. For example, if the order amount is ₹15,600 pass 1560000.
currencymandatory
Data type string. The 3-letter ISO currency code for the order amount. For example, INR.
prepaidmandatory
Data type boolean. Pass true if the order is prepaid.
item
This contains an array of items, consisting of item details, such as amount, currency, brand, category and quantity.
idmandatory
Data type string. A unique identifier for an item created in your system. Use the same id that you will use to look up items on your website's database. For example, XQF1576BGY.
titlemandatory
Data type string. The item's name. For example, Awesome bag to impress your friends.
amountmandatory
Data type string. The item amount in the currency subunit. For example, if the order amount is ₹15,600 pass 1560000.
currencymandatory
Data type string. The 3-letter currency code for the item amount. For example, INR.
brandmandatory
Data type string. The brand name of the item. For example, Office bags.
categorymandatory
Data type string. The category under which the item is listed in your business. For example, "Office bags", "man > bags".
quantitymandatory
Data type integer. The number or quantity of the item. For example, 4.
is_onsalemandatory
Data type boolean. Indicates if the item is on sale. Set to true if the item is on sale.
skuoptional
Data type string. The stock-keeping unit ID (SKU) for the item, if available. For example, 167380XBGEB.
shipping_address
Address where the order is to be shipped.
namemandatory
Data type string. Provide the full name associated with the address. Concatenate first name and last name together if you collect them separately in your system. For example, Gaurav Kumar.
phonemandatory
Data type string. The phone number associated with this address. Provide the phone number as a string starting with the country code. For example, +919123456789.
line1mandatory
Data type string. The first line of the shipping address. For example, 221B Bakery Street.
line2mandatory
Data type string. The second line of the address. For example, 14th Main Road, 3rd Cross.
citymandatory
Data type string. The city or town name. For example, Bengaluru.
statemandatory
Data type string. The state where the address is to be shipped. For example, Karnataka.
countrymandatory
Data type string. The 2-letter ISO country code where the order is to be shipped. For example, IN for India.
postal_codemandatory
Data type string. The postal code to which the order is to be shipped. For example, 560069.
typemandatory
Data type string. The type of address. Possible values:
home
office
other
promotions
An array of promotions applied to the order.
idoptional
Data type string. The unique identifier for the coupon code in your system. For example, ADbb.
statusoptional
Data type string. The status of the addition of promotion to an order. This way, you can pass both successful and failed attempts to Thirdwatch when using a promotion. This may be useful in spotting potential abuse. Possible values:
applied
failed
typeoptional
Data type string. Possible values:
discount
cashback
store_credit
voucher
amountoptional
Data type string. The amount or credits the promotion is worth in the currency subunits. For example, if the promotion is worth ₹50, pass 5000.
currencyoptional
Data type string. The 3-letter ISO currency code for the amount. For example, INR.
payment
The details of the payment made for the order.
idmandatory
Data type string. The unique identifier for the payment. It helps to track transactions and to link different parts of the same transaction, such as a refund, together.
statusmandatory
Data type string. The status of the payment. Possible values:
pending
success
failure
gatewaymandatory
Data type string. The gateway used to make the payment. For example, razorpay.
amountmandatory
Data type string. The amount for the payment in the currency subunits. For example, if the payment is worth ₹7,500 pass 750000.
currencymandatory
Data type string. The 3-letter ISO currency code for the payment. For example, INR.
methodmandatory
Data type string. The method used to make the payment. Possible values:
card
wallet
upi
netbanking
cod
fund_transfer
bankoptional
Data type string. The name of the bank using which the payment was made. For example, State Bank of India.
walletoptional
Data type string. The name of the wallet using which the payment was made. For example, amazonpay.
card
The details of the card used to make the payment.
last4optional
Data type string. Last 4 digits of the card. For example, 0305
typeoptional
Data type string. The type of card. Possible values:
debit
credit
gift
prepaid
issueroptional
Data type string. The name of the bank issuing the card. For example, State Bank of India.
internationaloptional
Data type boolean. Pass true if the card is issued outside India. Default is false.
iinoptional
Data type string. The first 6 digits of the card number. For example, 305619.
expiry_monthoptional
Data type string. The expiry month of the card in MM format. For example, if the card expires in October, pass 10.
expiry_yearoptional
Data type string. The expiry year of the card in YY format. For example, is the expiry year is 2022, pass 22.
nameoptional
Data type string. The name of the cardholder. For example, Gaurav Kumar.
seller
The details of the seller registered on the merchant's website. The seller details need to be passed with every order.
idoptional
Data type string. The unique identifier for the seller's internal account. For example, Ax17Ybc.
nameoptional
Data type string. The name associated with the seller's account. For example, Asa Fox.
emailoptional
Data type string. The email id associated with the seller's account. For example, asa.fox@examplecompany.com.
contactoptional
Data type string. The contact number associated with the seller's account. For example, +919988770099.
created_atoptional
Data type string. The Unix timestamp in milliseconds when the seller completed the registration process. For example, 1578924272676.
updated_atoptional
Data type string. The Unix timestamp in milliseconds when the seller's profile was last updated. For example, 1578924272676.
device
The details of the device used by the seller to place the order.
ipoptional
Data type string. The IP address used by the seller while placing the order. For example, 192.178.0.1.
session_idoptional
Data type string. The unique identifier for the session.
user-agentoptional
Data type string. The details of the browser used by the seller to place the order. For example, Mozilla/5.0.
After you create an order, Thirdwatch analyses the data. This is an asynchronous process on Thirdwatch’s end and lasts for less than 200 ms. You can retrieve the outcome of the analysis using the:
Data type string. This should be same as the order_id used in the Thirdwatch Orders API. For example, Axn167SnweX.
user_id
Data type string. The id of the user who placed the order. This should be same as the user_id used in the Thirdwatch Orders API. For example, AsXcYnkERrjb.
order_timestamp
Data type integer. The Unix timestamp in milliseconds when the order was created. For example, 1601388449000.
score
Data type integer. The probability score calculated by Thirdwatch systems on the overall confidence of the prediction. A higher probability score indicates that the order is more likely to be a fraud order.
flag
Data type string. Possible values:
Red - Indicates the potential of fraud. This needs to be further investigated by you.
Green - Indicates that the order can be shipped to the customer.
reasons
Data type array. List of reasons why Thirdwatch has flagged an order as red. This also takes into account any custom rule that you set up on the Thirwdwatch Dashboard.
name
Data type string. The rule name set on the Thirdwatch Dashboard.
display_name
Data type string. The display rule name set on the Thirdwatch Dashboard.
flag
Data type string. The nature of flagging by the rule.
value
Data type string. The level of impact your custom rule has on the flagged order.
api_key
Data type string. This is your API key.
tags
Data type array. Possible values of tags: Address, Email, ZipCode, Phone, MultipleSameItemsInADay, MultipleSameItemInAnOrder, HighValueCOD, DynamicRule, NetworkFlag, HighRto, HighRtoZipcode, Merchant Notes, multipleSameItemInAWeek, CustomerName, AddressTest
Data type string. This should be same as the order_id used in the Thirdwatch Orders API. For example, Axn167SnweX.
user_id
Data type string. This should be same as the user_id used in the Thirdwatch Orders API. For example, AsXcYnkERrjb.
order_timestamp
Data type string. For example, "2020-10-05T11:39:32Z"
score
Data type integer. The probability score calculated by Thirdwatch on the overall confidence of the prediction. A higher probability score indicates that the order is likely to be fraudulent.
flag
Data type string. Possible values:
Red - Indicates the potential of fraud. This needs to be further investigated by you.
Green - Indicates that the order can be shipped to the customer.
reasons
Data type array. List of reasons why Thirdwatch has flagged an order as red. This also takes into account any custom rule that you set up on the dashboard.
name
Data type string. The rule name set on the Thirdwatch Dashboard.
display_name
Data type string. The rule display name set on the Thirdwatch Dashboard.
flag
Data type string. The nature of flagging by the rule.
value
Data type string. The impact of the rule on the flagged order.
tags
Data type array. Possible values of tags: Address, Email, ZipCode, Phone, MultipleSameItemsInADay, MultipleSameItemInAnOrder, HighValueCOD, DynamicRule, NetworkFlag, HighRto, HighRtoZipcode, Merchant Notes, multipleSameItemInAWeek, CustomerName, AddressTest
You can synchronize actions taken on your server with the decisions taken using Thirdwatch. For example, you can have separate Fraud Prevention and Shipping Teams. The Fraud Prevention Team can work on the Thirdwatch Dashboard, while the Shipping Team works on your server.
There are three APIs for this.
Action API
Using this API, you can pass the actions taken on your server to Thirdwatch. For example, if you update an order on your server, you can use this API to update the order on Thirdwatch.
Action Postback API
Using this API, you can sync actions (such as cancelling an order or updating an order) taken on the Thirdwatch Dashboard with your server. For example, cancelling an order on the Thirdwatch Dashboard will cancel the order on your server.
Address Update API
Using this API, you can sync changes to the shipping address made on the Thirdwatch Dashboard with your server.
To use this feature, you have to add an action postback URL on the Thirdwatch Dashboard. The action postback URL should be configured on your server. Thirdwatch sends the action postback to this URL for your consumption. Every time an action is taken on an order on the Thirdwatch Dashboard, the information is sent to the action postback URL.
To use this feature, you have to add a shipping address postback URL on the Thirdwatch Dashboard. This postback URL should be configured on your server. Every time the shipping address is updated on the Thirdwatch Dashboard, the information is sent to the shipping address postback URL.
After you have processed and shipped the order, you need to capture its final status. This information is consumed by Thirdwatch AI to learn patterns and behaviour and prevent fraud in the future.
The real-time status of the update of an order can be captured using this API. The status can be updated at an overall order level as well as at an individual item level.
Data type string. The id of the user who placed the order. This should be same as the user_id used in the Thirdwatch Order API. For example, AsXcYnkERrjb.
order_idmandatory
Data type string. This should be same as the order_id used in the Thirdwatch Orders API. For example, Axn167SnweX.
order_statusmandatory
Data type string. The status of the order. You can assign values as per your business case. We recommend using the following values:
approved - The order is approved for shipping.
fulfilled - The order is successfully delivered to the customer.
cancelled - The order was cancelled by you and was not considered for delivery.
rto - The order was dispatched, but was returned to origin.
returned - The order was successfully delivered, but the customer returned the product.
held - The delivery for this order is put on hold.
reasonoptional
Data type string. The reason for cancellation. For example, Wrong pincode.
session_idoptional
Data type string. This can be alternately passed with the user id provided the same session id was passed in the orders request.
shipping_costoptional
Data type string. The shipping cost in the currency subunit. For example, if the shipping cost is ₹75, pass 7500.
tracking_numberoptional
Data type string. The tracking number for the order. For example, 374t873284768746.
tracking_methodoptional
Data typestring. The URL to track the shipment. For example, http://fedex.com/track?q=abc123.
sourceoptional
Data type string. The source from where the update was received. For example, Updated in delivery bay.
analystoptional
Data type string. The id of the person in your team who updated the order. For example, saurav.kumar@exampleenterprises.com.
descriptionoptional
Data type string. A user-entered comment while updating the order. For example, Approved for shipping.