Intelligence - Submit a fraud event to TeleBureau
NOTE:
To enable TeleBureau for your account, contact our Customer Support Team.
TeleBureau is a service based on Telesign's watchlist, a proprietary database containing verified phone numbers of users known to have committed online fraud. Telesign crowdsources this information from its customers. Participation is voluntary, but you have to contribute in order to benefit.
The TeleBureau API provides an automatic early-warning threat detection solution that allows you to avoid potentially risky online transactions. You can use the TeleBureau web service to submit fraud events, check the status of a submitted fraud event, cancel a submitted fraud event, or view a previously submitted fraud event.
Overview
Submitting a fraud event
Each time your system detects a fraud-related transaction, you can use it as a trigger to automatically send a POST request to the /v1/telebureau/event subresource.
https://rest-ww.telesign.com/v1/telebureau/event
NOTE:
If you are using
rest.telesign.comendpoints, Telesign recommends that you upgrade to the new hostname (rest-ww.telesign.comas soon as possible). It is faster.
Viewing or canceling a previously submitted fraud event
When you submit a phone number to TeleBureau, the web service returns a response message that contains a reference ID. This is a 32-digit hex value that uniquely identifies your submission. You can view or cancel your submission by sending a request message to the /v1/telebureau/event resource specifying this value as the subresource identifier.
https://rest-ww.telesign.com/v1/telebureau/event/[reference_id]
- To view your submission, use the GET method.
- To cancel your submission, use the DELETE method.
URI
To interact with TeleBureau, send requests to the following URI.
https://rest-ww.telesign.com/v1/telebureau/event
Supported HTTP methods
POST
Each time your system detects a fraud-related transaction, send a POST request to the event subresource, and include a parameter string in the message body that contains:
- The user's phone number
- The type of fraud committed
- The time when the fraud was committed
The TeleBureau web service immediately returns a response message that contains details about your request.
The URI for the POST request is /v1/telebureau/event.
GET
After you’ve submitted a fraud event, you can check to see whether Telesign accepted it (and therefore added it to TeleBureau) by sending a GET request to the resource created by appending the reference ID returned in response to your submission request, to the /v1/telebureau/event resource.
Telesign returns a response message that contains the submission status details in a status JSON object in the entity body.
The URI for the GET request is /v1/telebureau/event/[reference_id].
DELETE
After you’ve made your submission request, you can cancel it by sending a DELETE request to the resource indicated by appending the Reference ID returned in response to your submission request, to the /v1/telebureau/event resource.
Telesign returns a response message that contains status details of the cancellation request.
The URI for the DELETE request is /v1/telebureau/event/[reference_id].
Requests
Request parameters
POST
To submit a fraud event, send a request message to the /v1/telebureau/event URI, specifying the POST method be performed, and adding the following parameters to the message body.
| Parameter | Type | Description | Example | Required? |
|---|---|---|---|---|
| phone_number | string | The phone number you want to submit, composed of a string of digits without spaces or punctuation, beginning with the country dialing code (for example, “1” for North America). You would specify the phone number (310) 555-1212 as 13105551212 | 13105551212 | y |
| fraud_type | string | The type of fraud committed. This is a string enumeration value, chosen from the following list. Enumerated Values chargeback : The user got their credit card company to stop payment after receiving merchandise purchased online. coupon : The user took advantage of a sales promotion multiple times by opening several accounts. harass :The user harassed another user or your employee(s), wasted your time, or was difficult to deal with. identity_theft :The user attempted to open an account using someone else’s identity (name, address, Social Security Number, etc.). property_damage :The user caused physical damage to your property. spam :The user sent mass email, posted spam ads or comments, or otherwise attempted to distribute an ad in bulk to other users. takeover :The fraudster took over a legitimate user's account. telco :The user sent mass traffic to a phone number for the purpose of collecting premium rate phone fees or making money off of call-rate arbitrage. Also known as international revenue-share fraud (IRSF). other : Any other type of online fraud. | chargeback | y |
Updated 4 months ago