Available Vocabulary

Understanding the Spreedly Vocabulary

Different systems describe the same entities in different ways. To resolve this, Spreedly provides a common vocabulary for describing entities across the payments and fraud stack. Internally, Spreedly handles mapping these values to and from the formats each integration expects. Below is a full listing of all data elements in the Spreedly vocabulary.

How to Use the Vocabulary

When submitting data to Spreedly (via a checkpoint call or tracking event), pass in any data you want. Data submitted using the Spreedly vocabulary has special meaning and is automatically forwarded to integrations when appropriate.

spreedly.checkpoint({
  checkpointName: "MY_CHECKPOINT",
  event: {
    ip: "127.0.0.1",
    data: {
      myData: {
        anything: "you'd like to send...",
      },
      customer: {
        firstName: "Chester",
        lastName: "Tester",
        primaryEmail: "[email protected]",
      }
    }
  },
  sourceToken: "abc123...",
  sessionId: "session_def456",
  userId: "user_12345",
  useVerificationId: "def456",
});

Entities

Customer

Represents a real-world user. Top-level key: customer.

Users can be anonymous (not yet registered) or authenticated. Spreedly combines sessions and devices across a user's journey into a single Customer entity.

Data Key	Format	Description
`externalId`	`string (unique)`	Primary identifier for the customer in your system (typically a UUID).
`primaryEmail`	`email`	Primary email address.
`email`	`email`	Comma-separated list of additional email addresses.
`primaryPhone`	E.164	Primary phone number.
`phone`	E.164	Comma-separated list of additional phone numbers.
`firstName`	`string`	First name.
`lastName`	`string`	Last name.
`middleName`	`string`	Middle name.
`username`	`string`	Username within your application.
`gender`	ISO/IEC 5218	Gender.
`dateOfBirth`	`YYYY-MM-DD`	Date of birth.
`yearOfBirth`	`YYYY`	Year of birth (if full date unavailable).
`riskScore`	`number`	Risk score (computed by Spreedly or passed in manually).
`isMfaVerified`	`boolean`	Whether this customer has been MFA-verified.
`isIdvVerified`	`boolean`	Whether this customer has been IDV-verified.

Session

Represents a time-bounded series of interactions. Top-level key: session.

Data Key	Format	Description
`externalId`	`string (unique)`	Unique session identifier from your application.
`userAgent`	`string`	Latest user agent for this session.
`accountAbuseScore`	`number`	Account abuse risk score.
`contentAbuseScore`	`number`	Content abuse risk score.
`promotionAbuseScore`	`number`	Promotion abuse risk score.
`accountTakeoverScore`	`number`	Account takeover risk score.
`isMfaVerified`	`boolean`	Whether this session has been MFA-verified.
`isIdvVerified`	`boolean`	Whether this session has been IDV-verified.

Device

Represents a device making a request. Top-level key: device. The Client SDK automatically collects device information and issues sourceToken values — you typically won't need to set these manually.

Data Key	Format	Description
`fingerprintHash`	`string`	Unique device fingerprint hash (auto-populated if `sourceToken` is provided).
`isMfaVerified`	`boolean`	Whether this device has been MFA-verified.
`isIdvVerified`	`boolean`	Whether this device has been IDV-verified.
`ip`	IPv4 or IPv6	Relevant for server-side events only.
`browser.userAgent`	`string`	Browser user agent string.
`browser.name`	`string`	Browser name (e.g., `"Chrome"`).
`browser.version`	`string`	Full browser version.
`os.name`	`string`	Operating system name.
`os.version`	`string`	Operating system version.
`isMobile`	`boolean`	Whether the device is mobile.

(Additional device fields available — see full SDK reference.)

MFA

Represents Multi-Factor Authentication context. Top-level key: mfa.

Data Key	Format	Description
`phoneNumbers`	E.164	Comma-separated phone numbers to present during MFA.
`emailAddresses`	`email`	Comma-separated email addresses to present during MFA.

Transaction

Represents a transfer of value. Top-level key: transaction.

Data Key	Format	Description
`externalId`	`string (unique)`	Unique transaction identifier.
`currency`	ISO 4217	Currency code (defaults to USD).
`amount`	`integer`	Amount in smallest denomination (e.g., `150` for $1.50 USD).
`fromAccount`	`string`	Account value is being transferred out of.
`toAccount`	`string`	Account value is being transferred into.
`riskScore`	`number`	Transaction risk score.

Payment Method

Represents a method of transferring value. Top-level key: paymentMethod.

Data Key	Format	Description
`externalId`	`string (unique)`	Unique identifier for this payment method.

Address

Represents a physical location. Top-level key: address.

Data Key	Format	Description
`externalId`	`string (unique)`	Unique address identifier.
`type`	`string`	Address type: `SHIPPING`, `BILLING`, `HOME`, `WORK`, or `OTHER` (case-insensitive).
`line1`	`string`	Address line 1.
`line2`	`string`	Address line 2.
`city`	`string`	City.
`state`	ISO 3166-2	State/region.
`country`	ISO 3166-1 alpha-2	Country code.
`postalCode`	`string`	Postal code.
`latitude`	`number`	Latitude (typically auto-populated by integration).
`longitude`	`number`	Longitude (typically auto-populated by integration).

Company

Represents a business entity. Top-level key: company.

Data Key	Format	Description
`externalId`	`string (unique)`	Unique company identifier.
`name`	`string`	Company name.
`website`	`string`	Company website.
`employeeCount`	`number`	Number of employees.
`industry`	`string`	Industry.
`type`	`string`	Company type.
`description`	`string`	Company description.
`city`	`string`	City.
`state`	`string`	State/region.
`country`	`string`	Country.
`postalCode`	`string`	Postal code.