Merchants > API Reference > Endpoints > Connect

Connect

Field Status Definitions

Required Required fields must be sent. If the data is not sent Ravelin will return an error.

Important Important fields are crucial for performance where that data is relevant for your business.

Optional Optional fields are additional data points that can be shared with Ravelin.
These fields are unlikely to impact performance but may be visible in the Ravelin dashboard.

Jump to Response

POST api.ravelin.com/v2/connect

Show all

timestamp integer required

The time at which this data payload was valid. When sending events in realtime, this will usually be 'now'. This is used to merge data that arrives out-of-order.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

eventType string optional

An eventType describes from where an API call is being made.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]*$

customerId string optional

The ID of the customer you want to link to in the graph. Mutually exclusive with customer.

customer object optional

The customer you want to link to in the graph. Mutually exclusive with customerId.

Show definition

customerId string required

This is a unique identifier for the customer. Typically this will be your internal ID for the customer. In some cases where internal IDs are never minted then this could be an email address or phone number.

registrationTime integer optional

The time the customer registered

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

familyName string optional

The customer's family name.

givenName string optional

The customer's given name.

name string optional

The customer's full name.

username string optional

The customer's username.

email string optional

The email of the customer.

emailVerifiedTime integer optional

The time the customers email was verified.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

telephone string optional

The telephone number for the customer.

telephoneVerifiedTime integer optional

The time the customers telephone number was verified.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

telephoneCountry string optional

The country that the telephone comes from.

tags object optional

The tags to set on the customer. Use the tag ID followed by true or false, depending on whether you want to set or unset the tag.

country string optional

The home country for this customer. Doesn't change when the customer is briefly abroad.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture

paymentMethods array optional

Payment methods you want to associate the customer with.

Show definition

paymentMethodId string optional

The ID of an existing payment method.

card object optional

The credit or debit card this payment method represents.

Show definition

instrumentId string required

Unique identifier for this card, consistent across users (e.g. Stripe's fingerprint, or Braintree's unique_number_identifier).

pan string pci, optional

The full Primary Account Number of the card.

This should be 14-19 digits. For example 1234123412341234. This should not contain hyphens or spaces.

Used by Ravelin to generate the instrumentId for this card.

If specified, you do not need to provide instrumentId, cardBin or cardLastFour.

Only PCI DSS SAQ-D certified merchants should submit the PAN to Ravelin. You must not send requests containing this field to api.ravelin.com, and must instead use pci.ravelin.com.

Please see our PCI DSS documentation for more information.

paymentMethodId string optional

Unique identifier for this payment method, different for each customer.

nickName string optional

The nickname for the payment method that the customers gives, if applicable.

lastVerified integer optional

The time when the method was last verified

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

banned boolean optional

If the payment method has been banned.

active boolean optional

Whether the payment method is active for use by this account.

registrationTime integer optional

When the payment method was added to the customer's account (Unix time). Note: this is not the card start date.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture

cardBin string optional

The BIN (leading six or eight digits) of the card. Not always available, but strongly recommended when it is.

cardLastFour string optional

The last four digits of the card. Please note this will be truncated to the last two digits when an eight digit BIN is provided.

cardType string optional

the type of card this is.

expiryMonth integer optional

The expiry month of the method.

expiryYear integer optional

The expiry year of the method.

nameOnCard string optional

The name as it appears on the card.

successfulRegistration boolean optional

Whether the card was successfully registered with the PSP.

issuer string optional

The issuer of the payment method.

countryIssued string optional

An ISO 3166-1 Alpha 3 or Alpha 2 country code.

prepaidCard boolean optional

Is this a prepaid card or not.

billingAddress object optional

Show definition

latitude number optional

The latitude of the location.

longitude number optional

The longitude of the location.

geohash string optional

The geohash of the location.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town.

region string optional

The state/county.

country string optional

An ISO 3166-1 Alpha 3 or Alpha 2 country code.

poBoxNumber string optional

The PO box number related to the location.

postalCode string optional

The postal or zip code, if applicable.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture

billingFamilyName string optional

The family name of the customer - often the first name of a customer - associated with their billing address.

billingGivenName string optional

The given name of the customer - often the first name of a customer - associated with their billing address.

corporateCard boolean optional

Whether this payment method is a corporate card.

virtualCard boolean optional

Whether this payment method is a virtual card.

bankaccount object optional

Details of payment via bank account.

Show definition

transferType string required

The type of transfer: whether the customer is initiating the payment, or you are withdrawing funds from the customer's bank account based on an agreement to initiate payments on their behalf. Use "push" for a customer-initiated payment (e.g. a bank transfer) and "pull" for a merchant-initiated payment (e.g. Direct Debit).

One of: push, or pull.

methodType string optional

Bank account indicator.

Only: bankaccount.

scheme string important

The name of the payment scheme or instrument used for the transfer of funds.

paymentMethodId string optional

Unique identifier for this payment method, different for each customer.

iban string optional

IBAN (International Bank Account Number) Following the ISO 13616:2007 standard.

countryIssued string optional

An ISO 3166-1 Alpha 3 or Alpha 2 country code.

accountAddress object optional

Show definition

latitude number optional

The latitude of the location.

longitude number optional

The longitude of the location.

geohash string optional

The geohash of the location.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town.

region string optional

The state/county.

country string optional

An ISO 3166-1 Alpha 3 or Alpha 2 country code.

poBoxNumber string optional

The PO box number related to the location.

postalCode string optional

The postal or zip code, if applicable.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture

accountOwnerName string optional

The name of the account owner.

bankCode string optional

Code assigned by central bank to identify bank that account is associated with. Multiple bank code formats are supported.

bankName string optional

Name of bank which account belongs to.

bic string optional

BIC - business identifier code for banks and other institutions. Following the ISO9362 standard.

accountNumber string optional

The account number issued by the bank.

nickName string optional

The nickname for the payment method that the customers gives, if applicable.

registrationTime integer important

The time that the card was saved to the customer's account (not the card start date).

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture

paypal object optional

The PayPal account this payment method represents.

Show definition

email string required

PayPal account ID.

paymentMethodId string optional

Unique identifier for this payment method, different for each customer.

payerId string optional

PayPal payer ID.

nickName string optional

The nickname for the payment method that the customers gives, if applicable.

lastVerified integer optional

The time when the method was last verified.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

banned boolean optional

If the payment method has been banned.

active boolean optional

Whether the payment method is active for use by this account.

registrationTime integer optional

When the payment method was added to the customer's account.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture

billingAddress object optional

The address of the account holder. It is common to have fewer location details for this address, but provide what you have.

Show definition

latitude number optional

The latitude of the location.

longitude number optional

The longitude of the location.

geohash string optional

The geohash of the location.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town.

region string optional

The state/county.

country string optional

An ISO 3166-1 Alpha 3 or Alpha 2 country code.

poBoxNumber string optional

The PO box number related to the location.

postalCode string optional

The postal or zip code, if applicable.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture

voucher object optional

The voucher this payment method represents.

Show definition

paymentMethodId string required

A unique identifier for the paymentMethod.

voucherCode string required

The string customers actually see in their app.

value integer required

The value of the voucher.

redemptionTime integer required

The timestamp of the redemption attempt.

success boolean required

Bool indicating the success or failure of the redemption attempt.

referrerId string optional

The customerId of the customer who created this voucher.

expiry integer optional

The timestamp after which the voucher can no longer be redeemed.

currency string optional

The ISO 4217 currency code.

Pattern: ^[a-zA-Z]{3}$

voucherType string optional

The type of voucher.

One of: REFERRAL, REACTIVATION, or GENERAL.

failureReason string optional

Optional reason why the attempt was not successful

One of: EXPIRED, NOT_NEW_CUSTOMER, ALREADY_USED, ABUSER, SYSTEM_FAILURE, or MAX_ALLOWED_TIMES.

failureSource string optional

the source of why the voucher failed.

One of: RAVELIN, or CLIENT.

referralValue integer optional

The amount the owner of the voucher gets when the voucher is used.

custom object optional

paymentMethodCipher object optional

The encrypted ciphertext of the credit or debit card this payment method represents. (See Submission of encrypted card details.)

Show definition

paymentMethodId string optional

Unique identifier for this payment method, different for each customer.

cardCiphertext string pci, optional

The card ciphertext produced by the Ravelin SDK card encryption. This field constitutes cardholder data, and submission of this field therefore requires PCI DSS SAQ-A or SAQ-AEP certification. You must not send requests containing this field to <code>api.ravelin.com</code>, and must instead use <code>pci.ravelin.com</code>. Please see our PCI DSS documentation for more information.

aesKeyCiphertext string optional

The AES Key ciphertext produced by the Ravelin SDK card encryption.

algorithm string optional

The algorithm used to generate the ciphertexts.

ravelinSDKVersion string optional

The version of the ravelin SDK that performed this encryption.

keyIndex integer optional

The index of the public RSA key used to encrypt the card.

keySignature string optional

An identifier for the public key used during encryption.

billingAddress object optional

Show definition

latitude number optional

The latitude of the location.

longitude number optional

The longitude of the location.

geohash string optional

The geohash of the location.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town.

region string optional

The state/county.

country string optional

An ISO 3166-1 Alpha 3 or Alpha 2 country code.

poBoxNumber string optional

The PO box number related to the location.

postalCode string optional

The postal or zip code, if applicable.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture

registrationTime integer optional

When the payment method was added to the customer's account. Note: this is not the card start date.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

methodType string optional

Only: paymentMethodCipher.

other object optional

Another payment instrument this payment method represents.

Show definition

paymentMethodId string required

Unique identifier for this payment method, different for each customer.

nickName string optional

The nickname for the payment method that the customers gives, if applicable.

lastVerified integer optional

The time when the method was last verified.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

banned boolean optional

If the payment method has been banned.

active boolean optional

Whether the payment method is active for use by this account.

registrationTime integer optional

When the payment method was added to the customer's account (Unix time).

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture

methodType string optional

The type of method used.

One of: voucher, bitcoin, transfer, paysafe, cheque, or credit.

nationalIdentifications array optional

Identifications are used by online customers to verify their real-world identity. These forms of identification can be authenticated with government authorities or authorised third-parties to confirm the credentials are legitimate. Extra steps should be taken to confirm the customer is the legitimate holder of these credentials.

Show definition

driversLicense object optional

A driving license permitting the holder to operate one or more types of motorized vehicle.

Show definition

idNumber string required

The number unique to this piece of identification within the jurisdiction country/state.

For privacy reasons, Ravelin recommends obfuscating the real number by peppering and hashing it, using consistent one-way hashing function such as SHA256.

jurisdictionCountry string required

The controlling country for this form of identification. An ISO 3166-1 Alpha 3 or Alpha 2 country code.

jurisdictionState string optional

The controlling state within the controlling country for this form of identification. Not just the licence holder's home state. Omit where the identification is controlled by a country-level authority.

name string optional

The name of the identification holder.

passport object optional

A passport certifying the identity and nationality of its holder primarily for the purpose of international travel.

Show definition

idNumber string required

The number unique to this piece of identification within the jurisdiction country/state.

For privacy reasons, Ravelin recommends obfuscating the real number by peppering and hashing it, using consistent one-way hashing function such as SHA256.

jurisdictionCountry string required

The controlling country for this form of identification. An ISO 3166-1 Alpha 3 or Alpha 2 country code.

jurisdictionState string optional

name string optional

The name of the identification holder.

nationalId object optional

National identification cards and numbers, such as the US Social Security Number, Brazilian cédula de identidade, or UK's Insurance Number.

Show definition

idNumber string required

The number unique to this piece of identification within the jurisdiction country/state.

For privacy reasons, Ravelin recommends obfuscating the real number by peppering and hashing it, using consistent one-way hashing function such as SHA256.

jurisdictionCountry string required

The controlling country for this form of identification. An ISO 3166-1 Alpha 3 or Alpha 2 country code.

jurisdictionState string optional

name string optional

The name of the identification holder.

vehicles array optional

Vehicles the customer owns or has taken out insurance policies with, for example.

Show definition

plate string required

The vehicle registration or licence plate number.

jurisdictionCountry string required

The country in which this vehicle is registered. An ISO 3166-1 Alpha 3 or Alpha 2 country code.

jurisdictionState string optional

The state in which this vehicle is registered. Not just the licence holder's home state.

make string optional

The vehicle brand.

model string optional

The vehicle product range.

year integer optional

The year that the vehicle was produced.

vin string optional

The vehicle identification number as defined in ISO 3779.

deviceId string optional

The ID of the device to which you want to link the customer. Mutually exclusive with device.

device object optional

The device to which you want to link the customer. Mutually exclusive with deviceId.

Show definition

deviceId string required

This is a unique identifier for the device.

type string optional

The type of device.

One of: computer, phone, or tablet.

manufacturer string optional

The manufacturer of the device.

model string optional

The model/identifier name of the device. See here: https://www.theiphonewiki.com/wiki/Models and Here: https://docs.google.com/spreadsheets/d/16gXm7mGsXY_wQjTsRJYQVKkIjR8c3v-MAliAiRs0E3c/pub?gid=0&single=true&output=pdf

os string optional

The operating system that the device is running.

browser string optional

The name of the web browser being used, if applicable.

userAgent string optional

Browser user-agent string, if applicable.

chargeback object optional

The chargeback to which you want to link the customer.

Show definition

chargebackId string required

A unique identifier for the chargeback.

gateway string optional

The gateway of the chargeback.

gatewayReference string optional

A reference to the transaction being disputed. Should match the gateway and reference fields supplied on the transaction object. Not required if you supply a customer Id or an order Id.

reason string optional

The reason code from the chargeback.

status string optional

The status of the dispute.

amount integer optional

The amount that is being disputed, in the lowest denomination of the currency.

currency string optional

The ISO 4217 currency code.

Pattern: ^[a-zA-Z]{3}$

disputeTime integer optional

The time the dispute was opened.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

liabilityShifted boolean optional

Whether liability for this chargeback has been shifted to a third-party.

nonFraud boolean optional

Whether this chargeback was claimed for reasons other than fraud.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture

dispute object optional

The dispute to which you want to link the customer.

Show definition

disputeId string required

Unique identifier for the dispute.

stage string required

Stage of the dispute. A dispute with the stage EARLY_FRAUD_WARNING or REQUEST_FOR_INFORMATION is not considered a chargeback for reporting purposes. See our Sending Disputes guide to learn more.

One of: EARLY_FRAUD_WARNING, REQUEST_FOR_INFORMATION, NOTIFICATION_OF_CHARGEBACK, CHARGEBACK, SECOND_CHARGEBACK, CHARGEBACK_REVERSED, PREARBITRATION, or ARBITRATION.

gateway string important

Name of the payment gateway that processed the disputed transaction.

gatewayReference string important

Payment gateway's identifier for the disputed transaction. Must match the gateway reference of the original transaction. Not required if you provide transactionId.

transactionId string important

Identifier for the disputed transaction. Must match the transaction identifier of the original transaction. Not required if you provide gatewayReference.

amount integer important

Disputed amount, in the currency's basic units, including any additional dispute fees or penalties.

currency string important

Currency of the dispute amount, as an ISO 4217 currency code.

Pattern: ^[a-zA-Z]{3}$

disputeTime integer important

Time at which the dispute was created, used for reporting. A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

reason string optional

Reason given by the cardholder for disputing the transaction.

outcome string optional

Outcome of the dispute. Use ACCEPTED for disputes you have accepted and decided not to defend, WON for disputes you have successfully defended, EXPIRED for disputes that have timed out and LOST for disputes ruled in favour of the cardholder. Omit outcome if the dispute is still open.

One of: ACCEPTED, WON, LOST, or EXPIRED.

liabilityShifted boolean optional

Whether liability for this dispute was shifted to the issuer. See Liability Shift.

nonFraud boolean optional

Whether the cardholder disputed the payment for reasons other than fraud. Make sure to set a reason if this is the case - see our disputes guide to learn more.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture

review object optional

The manual review you would like to apply to the customer, stating whether your analyst believes them to be fraudulent or genuine.

Show definition

label string required

The label applied in this review. The conclusion reached.

One of: UNREVIEWED, GENUINE, or FRAUDSTER.

comment string optional

Comment for the review.

reviewer object optional

The person who is performing the review.

Show definition

name string optional

Name of reviewer.

email string optional

Email address of the reviewer.

customNode object optional

A custom entity you would like to use as a node to link customers in the graph.

Show definition

nodeType string required

The type of custom node - please contact us to configure custom nodes for your organisation.

nodeId string required

The unique identifier of the custom node.

nodeName string optional

A human readable label for this node. We will show this in the Connect network UI in the Ravelin Dashboard.

customNodes array optional

Custom entities you would like to use as nodes to link customers in the graph.

Show definition

nodeType string required

The type of custom node - please contact us to configure custom nodes for your organisation.

nodeId string required

The unique identifier of the custom node.

nodeName string optional

A human readable label for this node. We will show this in the Connect network UI in the Ravelin Dashboard.

POST https://api.ravelin.com/v2/connect?features=true&depth=10 HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "customer": {
    "customerId": "abc-123-ZYZ",
    "registrationTime": 1479302798,
    "familyName": "Smith",
    "givenName": "John",
    "name": "John Smith",
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 1479302798,
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1479302798,
    "telephoneCountry": "GBR",
    "tags": {
      "foo": true,
      "bar": false
    },
    "country": "GBR"
  },
  "paymentMethods": [
    {
      "card": {
        "paymentMethodId": "123-abc-XYZ",
        "nickName": "joescard",
        "lastVerified": 1480340580,
        "banned": false,
        "active": true,
        "registrationTime": 1480340580,
        "instrumentId": "123-abc-XYZ",
        "cardBin": "123456",
        "cardLastFour": "1234",
        "cardType": "visa",
        "expiryMonth": 4,
        "expiryYear": 2020,
        "nameOnCard": "John Smith",
        "successfulRegistration": true,
        "issuer": "barclaycard",
        "countryIssued": "GBR",
        "prepaidCard": false,
        "billingAddress": {
          "latitude": 51.503252,
          "longitude": -0.127899,
          "geohash": "gcpuvp",
          "street1": "123 fake st.",
          "street2": "floor 4, flat 48",
          "neighbourhood": "Hackney",
          "zone": "1",
          "city": "London",
          "region": "California",
          "country": "GBR",
          "poBoxNumber": "1234",
          "postalCode": "E1 1AA"
        },
        "billingFamilyName": "Smith",
        "billingGivenName": "John",
        "corporateCard": true,
        "virtualCard": true
      }
    }
  ],
  "nationalIdentifications": [
    {
      "driversLicense": {
        "idNumber": "10261985",
        "jurisdictionCountry": "USA",
        "jurisdictionState": "CA",
        "name": "Marty McFly"
      }
    }
  ],
  "vehicles": [
    {
      "plate": "OUTATIME",
      "jurisdictionCountry": "USA",
      "jurisdictionState": "CA",
      "make": "DeLorean Motor Company",
      "model": "DeLorean",
      "year": 1983,
      "vin": "2GTEK13M081122443"
    }
  ],
  "device": {
    "deviceId": "abc-123-ZYZ",
    "type": "phone",
    "manufacturer": "google",
    "model": "Pixel XL",
    "os": "android",
    "browser": "Chrome 42",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36"
  },
  "chargeback": {
    "chargebackId": "abc-123-XYZ",
    "gateway": "Stripe",
    "gatewayReference": "abc-123-XYZ",
    "reason": "FRAUD",
    "status": "LOST",
    "amount": 15212,
    "currency": "GBP",
    "disputeTime": 1479302798,
    "liabilityShifted": true,
    "nonFraud": false
  },
  "review": {
    "label": "FRAUDSTER",
    "comment": "Definitely a fraudster.",
    "reviewer": {
      "name": "tom@mycompany.com",
      "email": "Tom"
    }
  },
  "customNodes": [
    {
      "nodeType": "group",
      "nodeId": "group-abc-123-ZYZ",
      "nodeName": "Group abc-123-ZYZ"
    }
  ]
}

Response

Note: If the maximum node visit limit is reached while searching the graph, the maxNodesHit field will be set to true and all the *Count fields (customerCount, cardCount, etc.) will be set to 5000.

Show all

status integer

The HTTP response status code.

(Only present if features were not requested with the features query parameter.)

success string

Indicates whether the request was successful (HTTP 200 OK).

(Only present if features were not requested with the features query parameter.)

timestamp integer

A Unix timestamp indicating when we finished handling the request.

clientID string

The unique identifier for your Ravelin client account.

customerID string

Unique identifier for the customer.

count integer

The total number of nodes visited while searching the graph. Equal to the sum of all count fields.

customerCount integer

Number of customer nodes visited while searching the graph.

cardCount integer

Number card payment method nodes visited while searching the graph.

chargebackCount integer

Number of dispute nodes visited while searching the graph.

reviewedFraudsterCount integer

Number of nodes for customers reviewed as 'fraudster' visited while searching the graph.

reviewedGenuineCount integer

Number of nodes for customers reviewed as 'genuine' visited while searching the graph.

emailCount integer

Number of email address nodes visited while searching the graph.

phoneCount integer

Number of phone number nodes visited while searching the graph.

deviceCount integer

Number of device nodes visited while searching the graph.

vehicleCount integer

Number of vehicle nodes visited while searching the graph.

identificationCount integer

Number of national identification document nodes visited while searching the graph.

customNode1Count integer

Number of custom node 1 nodes visited while searching the graph.

We will inform you which custom node type this represents when we configue custom nodes for your account.

customNode2Count integer

Number of custom node 2 nodes visited while searching the graph.

We will inform you which custom node type this represents when we configue custom nodes for your account.

customNode3Count integer

Number of custom node 3 nodes visited while searching the graph.

We will inform you which custom node type this represents when we configue custom nodes for your account.

customNode4Count integer

Number of custom node 4 nodes visited while searching the graph.

We will inform you which custom node type this represents when we configue custom nodes for your account.

customNode5Count integer

Number of custom node 5 nodes visited while searching the graph.

We will inform you which custom node type this represents when we configue custom nodes for your account.

supplierCount integer

Number of supplier nodes visited while searching the graph.

hopsToFraud integer

Minimum number of connections (edges) between the parent node and nearest known fraudster.

Fraudsters are identified as either customers who have been reviewed as fraudsters, or customers who have an unforgiven dispute.

A value of -1 indicates that no fraudster was found in the graph.

customerDegreeMin number

Minimum number of connections for any customer node found while searching the graph.

customerDegreeMean number

Average number of connections across all customer nodes found while searching the graph.

customerDegreeMax number

Maximum number of connections for any customer node found while searching the graph.

cardDegreeMin number

Minimum number of connections for any card node found while searching the graph.

cardDegreeMean number

Average number of connections across all card nodes found while searching the graph.

cardDegreeMax number

Maximum number of connections for any card node found while searching the graph.

emailDegreeMin number

Minimum number of connections for any email address node found while searching the graph.

emailDegreeMean number

Average number of connections across all email address nodes found while searching the graph.

emailDegreeMax number

Maximum number of connections for any email address node found while searching the graph.

phoneDegreeMin number

Minimum number of connections for any phone number node found while searching the graph.

phoneDegreeMean number

Average number of connections across all phone number nodes found while searching the graph.

phoneDegreeMax number

Maximum number of connections for any phone number node found while searching the graph.

deviceDegreeMin number

Minimum number of connections for any device node found while searching the graph.

deviceDegreeMean number

Average number of connections across all device nodes found while searching the graph.

deviceDegreeMax number

Maximum number of connections for any device node found while searching the graph.

identificationDegreeMin number

Minimum number of connections for any national identification document node found while searching the graph.

identificationDegreeMean number

Average number of connections across all national identification document nodes found while searching the graph.

identificationDegreeMax number

Maximum number of connections for any identification document node found while searching the graph.

vehicleDegreeMin number

Minimum number of connections for any vehicle node found while searching the graph.

vehicleDegreeMean number

Average number of connections across all vehicle nodes found while searching the graph.

vehicleDegreeMax number

Maximum number of connections for any vehicle node found while searching the graph.

vinDegreeMin number

Minimum number of connections for any vehicle identification number (VIN) node found while searching the graph.

vinDegreeMean number

Average number of connections across all vehicle identification number (VIN) nodes found while searching the graph.

vinDegreeMax number

Maximum number of connections for any vehicle identification number (VIN) node found while searching the graph.

customNode1DegreeMin number

Minimum number of connections for any custom node type 1 found while searching the graph.

customNode1DegreeMean number

Average number of connections across all custom nodes type 1 found while searching the graph.

customNode1DegreeMax number

Maximum number of connections for any custom node type 1 found while searching the graph.

customNode2DegreeMin number

Minimum number of connections for any custom node type 2 found while searching the graph.

customNode2DegreeMean number

Average number of connections across all custom nodes type 2 found while searching the graph.

customNode2DegreeMax number

Maximum number of connections for any custom node type 2 found while searching the graph.

customNode3DegreeMin number

Minimum number of connections for any custom node type 3 found while searching the graph.

customNode3DegreeMean number

Average number of connections across all custom nodes type 3 found while searching the graph.

customNode3DegreeMax number

Maximum number of connections for any custom node type 3 found while searching the graph.

customNode4DegreeMin number

Minimum number of connections for any custom node type 4 found while searching the graph.

customNode4DegreeMean number

Average number of connections across all custom nodes type 4 found while searching the graph.

customNode4DegreeMax number

Maximum number of connections for any custom node type 4 found while searching the graph.

customNode5DegreeMin number

Minimum number of connections for any custom node type 5 found while searching the graph.

customNode5DegreeMean number

Average number of connections across all custom nodes type 5 found while searching the graph.

customNode5DegreeMax number

Maximum number of connections for any custom node type 5 found while searching the graph.

supplierDegreeMin number

Minimum number of connections for any supplier node found while searching the graph.

supplierDegreeMean number

Average number of connections across supplier nodes found while searching the graph.

supplierDegreeMax number

Maximum number of connections for any supplier node found while searching the graph.

maxNodesHit boolean

Indicates if the maximum node visit limit of 5000 visited nodes was reached during graph traversal. When true, all *Count fields (customerCount, cardCount, etc.) will be set to 5000 and the count field will be a multiple of 5000.

maxDepthReached boolean

Indicates if the maximum graph traversal depth was reached before fraud was found. The maximum depth is specified by the depth query parameter in the request. The default maximum depth is 20.

maxDegreeHit boolean

Indicates if the maximum allowed node degree was encountered. The maximum allowed node degree is 5000, we will not search through nodes connected to over 5000 other nodes. The search will continue, but will ignore nodes connected to more than 5000 other nodes.

autoExcludeHit boolean

Indicates if any automatic exclusion rules were triggered.

The following rules are applied:

Searching will not proceed through phone number nodes with more than 500 connections.

edgeGeneralMeanAge number

Average age of edges found up to depth 6 (6 hops from the parent node), in seconds.

edgeGeneralGrowthRate number

Rate of new edge creation calculated on edges up to depth 6 (6 hops from the parent node), in edges per hour.

edgeGeneralCount integer

The number of edges found up to depth 6 (6 hops from the parent node).

edgeLocalMeanAge number

Average age of edges found up to depth 2 (2 hops from the parent node), in seconds.

edgeLocalGrowthRate number

Rate of new edge creation around the parent node, calculated on edges up to depth 2 (2 hops from the parent node), in edges per hour.

edgeLocalCount integer

Number of edges found up to depth 2 (2 hops from the parent node).

meanDegree number

Average number of connections across all nodes visited while searching the graph.

tags array

List of tags with their respective depths in the graph.

Show definition

tagName string

Name of the tag.

depth integer

Distance from the parent node to the tagged node.

{
  "timestamp": 1512828988826,
  "clientID": "client123",
  "customerID": "abc-123-ZYZ",
  "count": 20,
  "chargebackCount": 0,
  "reviewedFraudsterCount": 0,
  "reviewedGenuineCount": 0,
  "customerCount": 14,
  "cardCount": 0,
  "emailCount": 3,
  "phoneCount": 1,
  "deviceCount": 0,
  "vehicleCount": 2,
  "identificationCount": 1,
  "customNode1Count": 1,
  "supplierCount": 1,
  "hopsToFraud": -1,
  "customerDegreeMin": 2,
  "customerDegreeMean": 2.2142857142857144,
  "customerDegreeMax": 3,
  "cardDegreeMin": 0,
  "cardDegreeMean": 0,
  "cardDegreeMax": 0,
  "emailDegreeMin": 12,
  "emailDegreeMean": 53.666666666666664,
  "emailDegreeMax": 115,
  "phoneDegreeMin": 4,
  "phoneDegreeMean": 4,
  "phoneDegreeMax": 4,
  "deviceDegreeMin": 0,
  "deviceDegreeMean": 0,
  "deviceDegreeMax": 0,
  "vehicleDegreeMin": 12,
  "vehicleDegreeMean": 50,
  "vehicleDegreeMax": 88,
  "customNode1DegreeMin": 1,
  "customNode1DegreeMean": 1,
  "customNode1DegreeMax": 1,
  "maxDepthReached": true,
  "edgeGeneralMeanAge": 58649687.38709678,
  "edgeGeneralGrowthRate": 0.0011340132677723277,
  "edgeGeneralCount": 31,
  "edgeLocalMeanAge": 54742302.71428572,
  "edgeLocalGrowthRate": 0.0010242700483104894,
  "edgeLocalCount": 28,
  "meanDegree": 14.8,
  "tags": [
    {
      "tagName": "high_risk",
      "depth": 2
    }
  ]
}

Feedback

Was this page helpful?