Available Vocabulary

Understanding the Dodgeball Vocabulary

Every company understands the world in different ways. You say tomato, I say Solanum lycopersicum. At the end of the day, we're all talking about the same things, just in different ways. Unfortunately, this leads to a lot of work translating data points across systems. To fix this issue, we've compiled a common vocabulary used for describing entities within Dodgeball. Internally, Dodgeball handles mapping those values into ones that each of our integrations understand, and handle mapping their responses into our common vocabulary. Here you can find a listing of all the data elements within the Dodgeball vocabulary, along with their meaning and formatting.

How to Use the Vocabulary

When submitting data to Dodgeball (either when calling a checkpoint or sending in a tracking event), pass in any data you want. Data passed in our vocabulary has special meaning within Dodgeball and is automatically sent to integrations when appropriate. Here's an example illustrating how to send customer information:

dodgeball.checkpoint({
  checkpointName: "MY_CHECKPOINT",
  event: {
    ip: "127.0.0.1", // The IP address of the device where the request originated
    data: {
      // Arbitrary data to send in to the checkpoint...
      myData: {
        anything: "you'd like to send...",
      },
      // Dodgeball vocabulary
      customer: {
        firstName: "Chester",
        lastName: "Tester",
        primaryEmail: "chester.tester@testing.com",
        // ...
      }
    }
  },
  sourceToken: "abc123...", // (Optional) Obtained from the Dodgeball Client SDK, represents the device making the request
  sessionId: "session_def456", // The current session ID of the request
  userId: "user_12345", // When you know the ID representing the user making the request in your database (ie after registration), pass it in here. Otherwise leave it blank.
  useVerificationId: "def456", // (Optional), if you have a verification ID, you can pass it in here
});

Entities

Customer

The Customer entity represents a real-world user within your application. The top-level key is customer.

There are two kinds of users that are represented by the Customer entity: anonymous and authenticated.

• Anonymous users are ones who have yet to register or login to your application (ie. your application may not have a unique identifier representing them in your database).
• Authenticated users are ones who have created an account with your system and have logged-in to that account.

Most users will start as anonymous and transition to authenticated as they use your application. Dodgeball combines these anonymous and authenticated sessions and devices associated with a user's journey into a single Customer entity to help identify suspicious behavior.

Data Key Name	Expected Format	Description
externalId	string (unique)	This is the primary identifier representing the customer within your application. Typically, this is a UUID.
primaryEmail	email	This is the primary email address associated with this customer.
email	email	A comma-separated list of any other email addresses associated with this customer.
primaryPhone	E.164	The primary phone number for this customer in E.164 format.
phone	E.164	A comma-separated list of any other phone numbers associated with this customer.
firstName	string	The first name of this customer.
lastName	string	The last name of this customer.
middleName	string	The middle name of this customer.
username	string	If applicable, the username for this customer within your application.
gender	ISO/IEC 5218	The gender of this customer in ISO/IEC 5218 format.
dateOfBirth	YYYY-MM-DD	The date of birth of this customer in the format YYYY-MM-DD.
yearOfBirth	YYYY	If you only have the year of birth of this customer, pass it in here.
riskScore	number	The risk score for this customer. Typically this value is computed by a fraud engine integrated with Dodgeball. However, if you would like to pass in your own risk score, use this data key.
isMfaVerified	boolean	Whether this customer has ever been verified by MFA. Typically this value is calculated by Dodgeball when using a MFA step in a checkpoint. However, if you handle MFA within your application, use this data key.
isIdvVerified	boolean	Whether this customer has ever been verified by IDV. Typically this value is calculated by Dodgeball when using a IDV step in a checkpoint. However, if you handle IDV within your application, use this data key.

Session

The Session entity represents a time-bounded series of interactions with your application. The top-level key is session.

Data Key Name	Expected Format	Description
externalId	string (unique)	A unique identifier representing this session that is generated by your application. Typically, this is a UUID.
userAgent	string	The latest user agent for this session.
accountAbuseScore	number	The account abuse score for this session. Typically this value is computed by a fraud engine integrated with Dodgeball. However, if you would like to pass in your own account abuse score, use this data key.
contentAbuseScore	number	The content abuse score for this session. Typically this value is computed by a fraud engine integrated with Dodgeball. However, if you would like to pass in your own content abuse score, use this data key.
promotionAbuseScore	number	The promotion abuse score for this session. Typically this value is computed by a fraud engine integrated with Dodgeball. However, if you would like to pass in your own promotion abuse score, use this data key.
accountTakeoverScore	number	The account takeover risk score for this session. Typically this value is computed by a fraud engine integrated with Dodgeball. However, if you would like to pass in your own account takeover risk score, use this data key.
isMfaVerified	boolean	Whether this session has ever been verified by MFA. Typically this value is calculated by Dodgeball when using a MFA step in a checkpoint. However, if you handle MFA within your application, use this data key.
isIdvVerified	boolean	Whether this session has ever been verified by IDV. Typically this value is calculated by Dodgeball when using a IDV step in a checkpoint. However, if you handle IDV within your application, use this data key.

Device

The Device entity represents a device making a request to your application. The Dodgeball Client SDK automatically handles collecting device information and issuing tokens representing a device, called sourceToken. Typically, you will not need to specify device information when calling checkpoints. The top-level key is device.

Data Key Name	Expected Format	Description
fingerprintHash	string	A unique hash representing fingerprint of the device making the request. This will automatically be populated by Dodgeball if a sourceToken is provided when calling a checkpoint.
isMfaVerified	boolean	Whether this device has ever been verified by MFA. Typically this value is calculated by Dodgeball when using a MFA step in a checkpoint. However, if you handle MFA within your application, use this data key.
isIdvVerified	boolean	Whether this device has ever been verified by IDV. Typically this value is calculated by Dodgeball when using a IDV step in a checkpoint. However, if you handle IDV within your application, use this data key.
ip	Any IPv4 or IPv6 address	Note: This data key is only relevant when tracking server-side events as all checkpoint calls already require an IP address. This represents latest IP address of the device that initiated a request.
browser.userAgent	string	User Agent detected on the device Browser. Example: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36"
browser.name	string	Name of the browser detected on the device. Example: "Chrome"
browser.version	string	Full version information of the browser. Example: "115.0.0.0"
browser.majorVersion	string	Major version of the browser. Example: "115"
browser.engine	string	Engine used by the browser. Example: "Blink"
browser.engineVersion	string	Version of the browser's engine. Example: "115.0.0.0"
os.name	string	Name of the operating system detected on the device. Example: "Mac OS"
os.version	string	Full version information of the operating system. Example: "10.15.7"
isMobile	boolean	Whether the device is mobile or not. Example: false
colorDepth	number	The color depth of the device display. Example: 24
currentResolution	string	Current resolution of the device display. Example: "1920x1080"
availableResolution	string	Available resolution of the device display. Example: "1920x1055"
browser.plugins	string	List of plugins installed in the browser. Example: "PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF"
browser.isJavaEnabled	boolean	Whether Java is enabled in the browser. Example: false
browser.isFlashEnabled	boolean	Whether Flash is enabled in the browser. Example: false
browser.isSilverlightEnabled	boolean	Whether Silverlight is enabled in the browser. Example: false
browser.silverLightVersion	string	Version of Silverlight installed, if enabled. Example: ""
browser.mimeTypes	string	List of MIME types supported by the browser. Example: "Portable Document Format, Portable Document Format"
browser.fonts	string	List of fonts available in the browser. Example: "Arial Black, Arial, Bauhaus 93, Chalkduster, Comic Sans MS, Courier New, Georgia, Hiragino Sans GB, Impact, Menlo, Microsoft Sans Serif, Papyrus, Plantagenet Cherokee, Rockwell, Symbol, Tahoma, Times New Roman, Trebuchet MS, Verdana, Webdings, Wingdings"
browser.isLocalStorageEnabled	boolean	Whether LocalStorage is enabled in the browser. Example: true
browser.isSessionStorageEnabled	boolean	Whether SessionStorage is enabled in the browser. Example: true
browser.isCookiesEnabled	boolean	Whether cookies are enabled in the browser. Example: true
browser.language	string	Language setting of the browser. Example: "en-US"
systemLanguage	string	System language setting of the device. Example: "en-US"
dodgeballFingerprintService.hash	string	Hash value from the Dodgeball Fingerprint Service. Example: "1111111111"

MFA

The MFA entity represents information relevant to displaying Multi-Factor Authentication modals to a user. The top-level key is mfa.

Data Key Name	Expected Format	Description
phoneNumbers	E.164	Comma separated list of phone numbers to present to the user when performing MFA.
emailAddresses	email	Comma separated list of email addresses to present to the user when performing MFA.

Transaction

The Transaction entity represents a transfer of value. The top-level key is transaction.

Data Key Name	Expected Format	Description
externalId	string (unique)	A unique identifier representing this transaction that is generated by your application.
currency	ISO 4217	The ISO 4217 currency code for this transaction. Defaults to USD.
amount	integer	The amount of this transaction in the smallest denomination of the currency specified by the currency field (USD by default). For example, $1.50 USD should be submitted as 150 cents.
fromAccount	string	An identifier representing the account that value is being transferred out of.
toAccount	string	An identifier representing the account that value is being transferred into.
riskScore	number	The risk score for this transaction. Typically this value is computed by a fraud engine integrated with Dodgeball. However, if you would like to pass in your own risk score, use this data key.

Payment Method

The Payment Method entity represents a way in which value can be transferred. The top-level key is paymentMethod.

Data Key Name	Expected Format	Description
externalId	string (unique)	A unique identifier representing this payment method that is generated by your application.

Address

The Address entity represents a physical location. The top-level key is address.

Note: Some data keys below are redundant (eg. line1 and streetName) and are provided for convenience if your application stores the individual components of an address (ie. streetName, streetNumber, unit) instead of a compiled (ie. line1, line2) format.

Data Key Name	Expected Format	Description
externalId	string (unique)	A unique identifier representing this address that is generated by your application.
type	string	The type of this address. Case-insensitive, may be one of: SHIPPING, BILLING, HOME, WORK, or OTHER.
organization	string	The organization for this address (if applicable).
line1	string	The first line of the address.
line2	string	The second line of the address.
streetName	string	The street name for this address.
streetNumber	string	The street number for this address.
unit	string	The unit for this address.
city	string	The city for this address.
district	ISO 3166-2	The region for this address in ISO 3166-2 format.
state	ISO 3166-2	The state for this address in ISO 3166-2 format.
country	ISO 3166-1 alpha-2	The country for this address in ISO 3166-1 alpha-2 format.
postalCode	string	The postal code for this address.
latitude	number	The latitude for this address. This typically is populated by an integration in Dodgeball, however you may pass a latitude here if known.
longitude	number	The longitude for this address. This typically is populated by an integration in Dodgeball, however you may pass a longitude here if known.

Company

The Company entity represents a business. The top-level key is company.

Data Key Name	Expected Format	Description
externalId	string (unique)	A unique identifier representing this company that is generated by your application.
name	string	The name of this company.
website	string	The website for this company.
employeeCount	number	The number of employees at this company.
industry	string	The industry for this company.
type	string	The type of this company.
description	string	The description of this company.
line1	string	The first line of the address for this company.
line2	string	The second line of the address for this company.
city	string	The city of the address for this company.
district	string	The region of the address for this company.
state	string	The state of the address for this company.
country	string	The country of the address for this company.
postalCode	string	The postal code of the address for this company.