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",
});

This vocabulary covers the signal data available for decisioning — customer, session, device, and transaction context. If you're looking for the full set of fields a specific payment step needs (Authorization, Capture, Purchase, etc.), pull that from Copy Schema as JSON on the checkpoint's Trigger node instead — see Building a transaction processing checkpoint. The two are related but not identical: this page is the general vocabulary, that one is the exact input list for the steps you've actually wired into a given checkpoint.

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.
`isMfaVerified`	`boolean`	Whether this customer has been MFA-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.
`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).

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.
`token`	`string (unique)`	The Spreedly token of the payment method to use.

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.
`industry`	`string`	Industry.
`phone`	`string`	Company phone.
`merchantCategoryCode`	`string`	Merchant category code (MCC).
`address`	`object`	Nested address (see Address) — e.g. `company.address.city`, `company.address.state`, `company.address.country`, `company.address.postalCode`.