Submit a Fraud Event to TeleBureau

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.

NOTE:

To enroll in the TeleBureau program, contact our Customer Support Team.

TeleBureau

The following sections describe the TeleBureau web service and how to use it.

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.com endpoints, TeleSign recommends that you upgrade to the new hostname (rest-ww.telesign.com as 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.

ParameterDescription
phone_number[Required] 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
[Example] phone_number=13105551212
fraud_type[Required] The type of fraud committed. This is a string enumeration value, chosen from the following list.
[Example] fraud_type=takeover
Enumeration ValueDescription
chargebackThe user got their credit card company to stop payment after receiving merchandise purchased online.
couponThe 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_theftThe user attempted to open an account using someone else’s identity (name, address, Social Security Number, etc.).
otherAny other type of online fraud that is not covered in this enumeration.
property_damageThe user caused physical damage to our property.
spamThe user sent mass mailings to recipients, posing as someone they trust.
takeoverThe user hacked into another user’s account.
telcoThe user runs a scan pumping traffic (artificially inflating call traffic), exploiting the price arbitrages created by policies of the Federal Communications Commission (FCC). International Revenue Share Fraud (IRSF).
occurred_at[Required] A string value specifying when the fraud event occurred. The value must be in RFC 3339 time format (for example, yyyy-mm-ddThh:mm:ssZ).
[Example] occurred_at=2014-01-24T00:43:44Z
impact_type[Optional] A string enumeration value indicating the area of your business that was affected by this fraud event.
[Example] impact_type=revenue_loss
Enumeration ValueDescription
revenue_lossTheft of products or services.
operational_overheadAdded load to our system resources.
customer_experienceDegraded our web site’s response time.
otherAn area not covered in this enumeration.
impact[Optional] A string enumeration value indicating how severely your business was affected by this fraud event.
[Example] impact=medium
Enumeration ValueDescription
low(< $1,000 USD) or (< 1,000 users affected)
medium($1,000 - $10,000 USD) or (1,000 - 10,000 users affected)
high(> $10,000 USD) or (> 10,000 users affected)
verified_by[Optional] A string enumeration value identifying the method used to verify the submitted phone number.
[Example] verified_by=telesign
Enumeration ValueDescription
telesignYou verified the user’s number with one of TeleSign’s verification methods (see the *[GetStatus and Verify Transaction Callback](doc:rest_api-verify-transaction-callback)* page).
otherYou verified the user’s number some other way.
verified_at[Optional] If you verified the user’s phone number, then you use this parameter to specify when. The value must be in RFC 3339 time format (for example, yyyy-mm-ddThh:mm:ssZ).
[Example] verified_at=2014-01-24T00:43:44Z
add_to_blocklist[Optional] This feature must be enabled in your account to be used. Please contact TeleSign Client Services to make changes to your account. A boolean indicating that you want the number listed to be added to your blocklist. These numbers will not be issued Verify requests until the block has passed its expiration date.
blocklist_start_date[Optional] If add_to_blocklist is true, then you use this parameter to specify when to start the block. If this value is not specified and add_to_blocklist is true, the current date and time is used. The value must be in RFC 3339 time format (for example, yyyy-mm-ddThh:mm:ssZ).
[Example] blocklist_start_date=2014-01-24T00:43:44Z
blocklist_end_date[Optional] If add_to_blocklist is true, then you use this parameter to specify when to end the block. If this value is not specified and add_to_blocklist is true, the block will never expire. The value must be in RFC 3339 time format (for example, yyyy-mm-ddThh:mm:ssZ).
[Example] blocklist_end_date=2014-01-24T00:43:44Z

GET

To check whether TeleSign accepted your Fraud Submission candidate (and therefore added it to TeleBureau), send a request message to the /v1/telebureau/event/[reference_id] URI, specifying the GET method be performed.

The GET method takes no query parameters.

NOTE:

The reference_id of your submission request becomes the subresource identifier in the request URI.

ParameterDescription
reference_id[Required] The reference ID that TeleSign generates and returns in its response to your fraud submission request message. This value uniquely identifies your fraud submission.

DELETE

If you change your mind, you can delete your fraud event submission. You do this by sending a request message to the /v1/telebureau/event/[reference_id] URI, specifying the DELETE method be performed.

The DELETE method takes no query parameters.

NOTE:

The reference_id of your submission request becomes the subresource identifier in the request URI.

ParameterDescription
reference_id[Required] The reference ID that TeleSign generates and returns in its response to your fraud submission request message. This value uniquely identifies your fraud submission.

Responses

This section details the response header and the response entity-body returned by the TeleBureau Event web service.

Response Body

When the TeleBureau web service processes a service request, it returns a response message that contains information about the result of that service request. The information is contained in the message body, and it is structured in JavaScript Object Notation (JSON). The web service returns different pieces of information, depending on the HTTP method performed on the resource.

This section contains examples of the JSON object returned for each of the supported methods.

POST

The TeleBureau web service returns the following JSON object after processing a POST request.

JSON Object Returned by TeleBureau in Response to POST Request
{
  "status": {
    "code": 1490,
    "updated_on": "2015-02-25T22:51:02.472839Z",
    "description": "Pending"
  },
  "errors": [],
  "reference_id": "0123456789ABCDEF0123456789ABCDEF"
}

The JSON object contains the following members:

NOTE:

Unless otherwise specified, a missing or unspecified value defaults to null.

ParameterDescription
statusAn object that describes the submission transaction status. The object contains the following parameters:
ParameterDescription
codeOne of the TeleBureau fraud submission status codes below.
updated_onAn ISO 8601 UTC timestamp indicating when the submission transaction status was updated.
descriptionA text description corresponding to the submission transaction status code.
errorsA JSON object that contains information on error conditions that might have resulted from the request, in an array of property-value pairs. If multiple errors occur, a pair is returned for each error.
ValueDescription
codeA 1 to 5-digit error code (possibly negative) that indicates the type of error that occurred.
descriptionA string that describes the type of error that occurred.
If no errors occur, then this array is empty.
"errors":[]
warnings A JSON object that contains information on warning conditions that might have resulted from the request, in an array of property-value pairs. If multiple warnings occur, a pair is returned for each warning.
ValueDescription
codeA 1 to 5-digit warning code (possibly negative) that indicates the type of warning that occurred.
descriptionA string that describes the type of warning that occurred.
If no warnings occur, then this array is empty.
"warnings":[]
reference_id A 32-digit hex value used to identify your web service request (the POST request that you just made, in which you submitted a new phone number). The value is unique to each web service request, is randomly-generated by TeleSign, and is returned in the response to your POST request.

GET

The TeleBureau web service returns the following information after processing a GET request.

Response from TeleBureau to a GET Request
{
  "status": {
    "code": 1400,
    "updated_on": "2015-05-22T23:13:23.472839Z",
    "description": "Success"
  },
  "fraud_event": {
    "phone_number": "15555551234"
  },
  "errors": [],
  "reference_id": "0123456789ABCDEF0123456789ABCDEF"
}

The JSON object contains the following members:

NOTE:

Unless otherwise specified, a missing or unspecified value defaults to null.

ParameterDescription
statusAn object that describes the submission transaction status. The object contains the following parameters:
ParameterDescription
codeOne of the TeleBureau fraud submission status codes below.
updated_onAn ISO 8601 UTC timestamp indicating when the submission transaction status was updated.
descriptionA text description corresponding to the submission transaction status code.
errorsA JSON object that contains information on error conditions that might have resulted from the request, in an array of property-value pairs. If multiple errors occur, a pair is returned for each error.
ValueDescription
codeA 1 to 5-digit error code (possibly negative) that indicates the type of error that occurred.
descriptionA string that describes the type of error that occurred.
If no errors occur, then this array is empty.
"errors":[]
warnings A JSON object that contains information on warning conditions that might have resulted from the request, in an array of property-value pairs. If multiple warnings occur, a pair is returned for each warning.
ValueDescription
codeA 1 to 5-digit warning code (possibly negative) that indicates the type of warning that occurred.
descriptionA string that describes the type of warning that occurred.
If no warnings occur, then this array is empty.
"warnings":[]
reference_idA 32-digit hex value used to identify your web service request (the POST request that you just made, in which you submitted a new phone number). The value is unique to each web service request, is randomly-generated by TeleSign, and is returned in the response to your POST request.

GET

The TeleBureau web service returns the following information after processing a GET request.

Response from TeleBureau to a GET Request
{
  "status": {
    "code": 1400,
    "updated_on": "2015-05-22T23:13:23.472839Z",
    "description": "Success"
  },
  "fraud_event": {
    "phone_number": "15555551234"
  },
  "errors": [],
  "reference_id": "0123456789ABCDEF0123456789ABCDEF"
}

The JSON object contains the following members:

NOTE:

Unless otherwise specified, a missing or unspecified value defaults to null.

ParameterDescription
statusAn object that describes the submission transaction status. The object contains the following parameters:
ParameterDescription
codeOne of the TeleBureau fraud submission status codes below.
updated_onAn ISO 8601 UTC timestamp indicating when the submission transaction status was updated.
descriptionA text description corresponding to the submission transaction status code.
fraud_eventContains details about your fraud submission. This will also include any optional parameters specified in the original POST request.
phone_numberThe end user’s complete phone number, which includes its country code.
errorsA JSON object that contains information on error conditions that might have resulted from the request, in an array of property-value pairs. If multiple errors occur, a pair is returned for each error.
ValueDescription
codeA 1 to 5-digit error code (possibly negative) that indicates the type of error that occurred.
descriptionA string that describes the type of error that occurred.
If no errors occur, then this array is empty. "errors": []
reference_idA 32-digit hex value used to identify your web service request (the GET request that you just made, to check the status of your submission). The value is unique to each web service request, is randomly-generated by TeleSign, and is returned in the response to your GET request.

DELETE

The TeleBureau web service returns the following information after processing a DELETE request.

Response from TeleBureau to a DELETE Request
{
  "status": {
    "code": 1490,
    "updated_on": "2015-05-22T23:13:23.472839Z",
    "description": "Pending"
  },
  "errors": [],
  "reference_id": "0123456789ABCDEF0123456789ABCDEF"
}

The JSON object contains the following members:

NOTE:

Unless otherwise specified, a missing or unspecified value defaults to null.

ParameterDescription
statusAn object that describes the submission transaction status. The object contains the following parameters:
ParameterDescription
codeOne of the TeleBureau fraud submission status codes below.
updated_onAn ISO 8601 UTC timestamp indicating when the submission transaction status was updated.
descriptionA text description corresponding to the submission transaction status code.
errorsA JSON object that contains information on error conditions that might have resulted from the request, in an array of property-value pairs. If multiple errors occur, a pair is returned for each error.
ValueDescription
codeA 1 to 5-digit error code (possibly negative) that indicates the type of error that occurred.
descriptionA string that describes the type of error that occurred.
If no errors occur, then this array is empty. "errors": []
reference_idA 32-digit hex value used to identify your web service request (the GET request that you just made, to check the status of your submission). The value is unique to each web service request, is randomly-generated by TeleSign, and is returned in the response to your GET request.

Examples

Submitting a Fraud Event

Request

You submit a Fraud Event by sending a request message the specifies the POST method, to the /v1/telebureau/event URI.

Submit a Fraud Event Request Message Example
POST https://rest-ww.telesign.com/v1/telebureau/event HTTP/1.1
Authorization: Basic AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: 68
Host: rest-ww.telesign.com

phone_number=15555551234
   &fraud_type=takeover
   &occurred_at=2014-08-09T01:23:39Z
   &impact_type=revenue_loss
   &impact=medium
NOTE:

The request parameters are shown on separate lines for illustration purposes.

Response

TeleSign returns the following message in response to the preceding example request.

Response to Submission of a Fraud Event
HTTP/1.1 200 OK
Date: Sat, 09 Aug 2015 01:23:45 GMT
Server: CERN/3.0 Add 'libwww' to dictionary/2.17
Content-Length: 314
Allow: POST, HEAD
Content-Type: application/json

{
   "status" : {
      "code" : 1490,
      "updated_on": "2015-02-25T22:51:02.472839Z",
      "description" : "Pending"
   },
   "errors": [],
   "reference_id" : "0123456789ABCDEF0123456789ABCDEF"
}

Checking Status of Your Submission

Request

You check the status of your submission by sending a request message that specifies the GET method, to the resource indicated by appending the Reference ID returned in response to your submission request, to the /v1/telebureau/event resource.

Example Check the Status of Your Submission Request Message
GET https://rest-ww.telesign.com/v1/telebureau/event/0123456789ABCDEF0123456789ABCDEF HTTP/1.1
Authorization: Basic AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: rest-ww.telesign.com

Response

TeleSign returns the following message in response to the preceding example request.

Example Response to a Request to Check Status
HTTP/1.1 200 OK
Date: Sat, 09 Aug 2015 01:23:45 GMT
Server: CERN/3.0 Add 'libwww' to dictionary/2.17
Content-Length: 314
Allow: POST, HEAD
Content-Type: application/json

{
    "status": {
        "code": 1400,
        "updated_on": "2015-05-22T23:13:23.472839Z",
        "description": "Success"
    },
    "fraud_event" : {
        "phone_number" : "15555551234"
    },
    "errors": [],
    "reference_id": "0123456789ABCDEF0123456789ABCDEF"
}

Canceling Your Submission

Request

You cancel your submission by sending a request message that specifies the DELETE method, to the resource indicated by appending the reference ID returned in response to your submission request, to the /v1/telebureau/event resource.

Example Cancel Submission Request Message
DELETE https://rest-ww.telesign.com/v1/telebureau/event/0123456789ABCDEF0123456789ABCDEF HTTP/1.1
Authorization: Basic AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: rest-ww.telesign.com

Response

TeleSign returns the following message in response to the preceding example request.

Response to a Request to Cancel a Submission
HTTP/1.1 200 OK
Date: Sat, 09 Aug 2015 01:23:45 GMT
Server: CERN/3.0 Add 'libwww' to dictionary/2.17
Content-Length: 314
Allow: POST, HEAD
Content-Type: application/json

{
    "status": {
        "code": 1490,
        "updated_on": "2015-05-22T23:13:23.472839Z",
        "description": "Pending"
    },
    "errors": [],
    "reference_id": "0123456789ABCDEF0123456789ABCDEF"
}

TeleBureau Fraud Submission Status Codes

Code Description Detail
1400 Success The operation was successful. For POST and GET: TeleSign successfully processed your fraud submission, and added the phone number to TeleBureau. For DELETE: TeleSign successfully cancelled your fraud submission.
1401 Partial Success Returned when a bulk submission includes some entries that succeeded and some that failed.
1403 Failed TeleSign failed to process your fraud submission, and did not add the phone number to TeleBureau. Please check the submission format and try again.
1490 Pending TeleSign is currently processing your fraud submission. Please check the status of your submission again later.

Warning Codes

The following is a list of warning codes that may be generated by the TeleSign API:

Error Code Description
0 No warning
-60003 See the status code for fraud submission status. The blocklist feature is not enabled for this customerID. Contact support for more information.

For a complete list of error codes (this is a shortened list), refer to All Status and Error Codes.