Overview

With the Reference Lookup utility, your most frequent, predictable transactions code themselves as they sync into Accounting Seed. You build a lookup table that maps a key derived from each transaction's attributes to a set of default values: GL Account, Vendor, Employee, GL Account Variables, Project, Project Task, and Product. The feature is optional and off by default.

In this article:

• How Reference Lookup Works
• Before You Begin
• Step 1: Enable Reference Lookup and Set the Key Template
• Step 2: Create & Maintain Lookup Reference Table
• Override vs. Fill-Only Behavior
• Relationship to Vendor Matching

How Reference Lookup Works

During each card transaction sync, the integration:

1. Computes a lookup key for each transaction using the Reference Key Template you configure
2. Stamps that key on the Reference field of every Journal Entry Line created for the transaction, including both expense lines and the card-clearing line
3. Matches the key (case-insensitive) against your Ramp Lookup Reference records
4. Applies the matching record's default values to the expense (debit) lines only

The card-clearing line is never modified by Reference Lookup. Its GL Account must remain the clearing offset established by your Default GL Account configuration.

Reference Lookup runs after Ramp's own transaction coding is read in. It layers on top of that coding and does not change how Ramp codes a transaction: it only affects what gets stamped on the Accounting Seed Journal Entry Lines.

Before You Begin

1. Complete the initial integration setup from this article: Ramp Integration One-time Setup.
2. Confirm card transactions are syncing into Accounting Seed successfully.
3. Identify which Ramp transaction attributes you want to use as your matching key (such as merchant name, memo, or merchant category).

Step 1: Enable Reference Lookup and Set the Key Template

1. In Salesforce, on the Ramp Home tab, click Configure (gear icon, top right) to open Setup & configuration.
2. Select the Reference Lookup tab.
3. Select Enable Reference Lookup.
4. Enter a Reference Key Template (see below).
5. Click Save. A confirmation message appears: "Reference Lookup settings saved. Changes apply on the next sync."

Important: Settings save asynchronously. Like other configuration tabs, saving deploys a Custom Metadata change in the background, so new values take effect on the next sync rather than immediately. Wait a few seconds after saving before running a sync.

The reference key template

The template is a text string with {token} placeholders. Each placeholder is replaced with the corresponding value from the raw Ramp transaction during sync. Text outside the braces, including dashes, slashes, or other characters, is kept verbatim. To write your template correctly follow these rules:

Rule	Detail
Token = Ramp field name	Tokens are Ramp transaction API field names, such as {merchant_name}, {memo}, {merchant_id}, and {sk_category_name}
Dotted paths for nested fields	Use dots to reach into nested objects, such as {card_holder.user_id}
Case-insensitive	Token names match without regard to case
Missing value = empty string	A token that resolves to null or is absent on the transaction becomes an empty string; the rest of the key still builds

Example: With the template {merchant_name}-{memo}, a transaction from "Amazon Web Services" with the memo "prod" produces the key Amazon Web Services-prod. Create a Ramp Lookup Reference record with that exact value in the Reference field and its defaults are applied every time that key appears during sync.

Note: Design the key to be stable and selective. If two different transaction types produce the same key, only one lookup row can apply to both. Choose template tokens that distinguish the cases you need to code differently. Adding {memo}, for example, lets the same merchant resolve to different rows based on context.

Step 2: Create & Maintain Lookup Reference Table

The lookup table is the Ramp Lookup Reference custom object, accessible from its own tab. Each record maps one key to a set of defaults. The Reference field is unique, so each key can have only one lookup row. The object is reportable, which makes it easy to audit and manage your lookup table at scale.

Field	Purpose
Reference (required, unique)	The lookup key. Must match a computed key exactly (case-insensitive). Duplicate values are not allowed.
Override	Controls whether this row replaces the GL Account on the expense line. See Override vs. Fill-Only Behavior below.
GL Account	Default GL Account for the expense line.
Vendor	Default Account (vendor) on the expense line.
Employee	Default Employee on the expense line.
GL Account Variable 1–4	Default Accounting Variables for the four GL variable slots.
Project / Project Task	Default Project and Project Task.
Product	Default Product.

Leave any field blank to skip it. A blank field on the lookup row never clears a value already on the line.

 

Override vs. Fill-Only Behavior

How defaults are applied depends on the field type and whether Override is selected on the lookup row.

Field	Override unchecked	Override checked
Vendor, Employee, GL Variables 1–4, Project, Project Task, Product	Overwrites the line's value	Overwrites the line's value
GL Account	Applied only if the line has no GL Account	Replaces the GL Account, including one coded by Ramp or the Suspense default

Important:

• If you want your lookup row's GL Account to win, you must check Override to force it to replace what's already there. Without it checked, the system sees that there already is a GL Account value and will leave it as is: by the time Reference Lookup applies, every expense line already carries a GL Account, either the one coded in Ramp or the Ramp Suspense GL Account for uncoded lines. Because the line is never empty at that point, a lookup row's GL Account only takes effect when Override is selected.
• Attribution fields (Vendor, Employee, GL Account Variables, Project, Project Task, and Product) always overwrite the line's existing value regardless of the Override setting.

Worked example:

• Template: {merchant_name}
• Lookup row: Reference = Uber, GL Account = Travel: Ground Transportation (example), GL Account Variable 1 = Sales, Override = checked
• Result: Every Uber card transaction syncs with its expense line coded to that GL Account with Variable 1 = Sales, regardless of how it was coded (or not coded) in Ramp

To code the same merchant differently based on context, make the key more specific. For example, use the template {merchant_name}-{memo} with separate rows for Uber-client visit and Uber-commute, each pointing to a different GL Account.

Relationship to Vendor Matching

When a card transaction syncs, the integration tries to fill in the vendor on the expense line automatically. It does this in two steps: first it checks how the transaction was coded in Ramp, and if that doesn't resolve to a vendor, it tries to match the merchant name against your existing vendor Accounts in Accounting Seed.

If you have a Reference Lookup row with a Vendor value, that always wins — it overwrites whatever the automatic matching found.

You can make automatic merchant-name matching more selective with the Vendor Match Requires Payment History setting on your Ramp Sync Settings record. When turned on, the system only considers vendor Accounts that have at least one Cash Disbursement on record, which keeps old or duplicate Accounts out of the match pool. See the "Inbound Vendor Matching" section of the Run & Monitor Ramp Sync Pipelines for more on how vendor matching works.

Related Articles:

• Ramp Integration Overview 
• Run and Monitor Ramp Sync Pipelines
• Ramp Integration - One-time Setup
• Ramp Integration Troubleshooting 
• Ramp Integration Developer API Documentation 

---

Return to top