How can we help?

Custom First-Party Person & Company Signals lets you push your own first-party data — from Salesforce, your data warehouse, or any external system — directly into UserGems. Once ingested, that data can trigger Gem-E campaigns, feed account scoring models, and personalize AI-written outreach, just like any native UserGems signal.

Custom Signal is particularly powerful when you have proprietary behavioral or product data that third-party signals can't capture — events, inbound demo requests, warm MQLs, or any custom engagement metric that indicates buying intent.

How It Works

There are three methods for getting custom signals into UserGems:

• CSV Upload — Import a CSV file directly in the Signal setup flow
• Salesforce Reports — Import a SFDC report directly in the Signal setup flow
• API Push — Send data programmatically from your data warehouse or external system

Where to find Custom Signal
In UserGems, navigate to Signal > First Party Person/Company Signal > Create Signal

Method 1: Salesforce Reports

Use this method when your first-party data already lives in Salesforce and can be expressed as a SFDC report. This is the fastest path and recommended for dynamic reports.

Setup

1. In UserGems, open Signals and find "First-party Person Signals" or "First-party Company Signals"
2. Click "+Add" to create a new Custom Signal.
3. Select "Upload Salesforce Report" as your ingestion method.
4. Connect your Salesforce instance if not already linked.
5. Input the SFDC report ID that contains the relevant records.
6. Map the report fields
7. Under "Signal Information" you can map specific fields for more details (i.e., you might want to upload an Event Registrations list with a status to indicate "No Shows" VS "Attendees")
8. Set your refresh cadence (how often UserGems should re-import the report).
9. Check the "Create a company list" checkbox, if desired (if you upload a list of Past Inbound leads, UserGems can automatically create a report of the companies for those leads. Then, you can run a campaign to find prospects missing in CRM at companies with a past inbound lead)
10. Check the "Search prospects with persona" checkbox and select a persona, if desired. This will find persona matching prospects at these accounts.

Tip: Your SFDC report can contain contacts, leads, or accounts — UserGems will match records by email or domain. Make sure the report includes the fields needed for matching.

Common Use Cases

Method 2: API Push

Use this method when your data lives outside Salesforce — in a data warehouse, product analytics system, or custom backend. Once set up, data flows into UserGems automatically without manual exports.

Setup

1. In UserGems, go to Settings > Connected Applications > API.
2. Locate your UserGems API Token.
3. Use the API to push records (persons or companies) with the relevant signal data.
4. Map the payload fields to UserGems schema fields (email for persons, domain for companies).
5. Push records to UserGems via API
6. Check in Signals to review the data sent

Finding your API key
Settings > Integrations > API. Copy the key and store it securely — this key authenticates all data pushes.

Security: The API is write-only — responses return only "success" or "failed", so a leaked key cannot expose your data. The main risk of a leaked key is that incorrect data could be written to your account. Keys are not auto-rotated but can be changed upon request by contacting your CSM.

Sample API Payload

Signals appear in UserGems automatically as soon as a successful API call is received — no additional configuration required. Here is an example payload:

{
  "email": "contact@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "company": "Acme Corp",
  "signal": "Credit Limit Exceeded",
  "creditsUsed": 1250,
  "signalDate": "2026-05-15T14:00:00Z"
}

Custom parameters (like creditsUsed above) can be any key-value pair relevant to your use case. These values are stored with the signal record and can inform Gem-E personalization.

Common Use Cases

Method 3: CSV Upload

If your data does not live in Salesforce or cannot be sent via API, you can alternatively upload data via a CSV file.

1. In UserGems, open Signals and find "First-party Person Signals" or "First-party Company Signals"
2. Click "+Add" to create a new Custom Signal.
3. Select "Upload CSV report" as your ingestion method.
4. Map the report fields
5. Under "Signal Information" you can map specific fields for more details (i.e., you might want to upload an Event Registrations list with a status to indicate "No Shows" VS "Attendees")
6. Check the "Create a company list" checkbox, if desired. This will automatically create a report of the companies for those leads.
7. Check the "Search prospects with persona" checkbox and select a persona, if desired. This will find persona matching prospects at these accounts.

What You Can Do With Custom Signals

Once a Custom Signal is live in UserGems, it behaves like any other signal in the platform. You can:

• Use it as a trigger in Signal Sets to launch Gem-E campaigns
• Feed it into Account & Contact Scoring models or map Buying Stage to weight first-party intent higher
• Personalize Gem-E AI-written outreach by referencing the signal in the prompt context (we recommend going to Content → Conditional Instructions → add a filter for your custom signal and feeding custom instructions there)
• Combine it with other native signals in the UserGems Library (i.e., Customer Competitors, Job Changes, Contact-Level Intent, Website Visitors, etc)

Custom signals are most powerful when layered with other signals.

Data Requirements

Person Records

The following fields are required or recommended when pushing person-level signals:

Company Records

For company-level signals, match on domain:

FAQ

Can I use Custom Signal with Gem-E for AI outreach personalization?

Yes. Any custom signal field passed through the API can be referenced in Gem-E prompt configuration, allowing highly personalized messaging. For example, a credit overconsumption signal can tell Gem-E exactly which product feature the contact is using heavily — making outreach far more relevant than a generic expansion email.

How often can I push data via API?

There is no hard frequency limit for API pushes. Most teams push in real time (event-triggered) or on a scheduled batch (daily/hourly). Check with your UserGems CSM if you plan to push high volumes continuously.

What happens if a record doesn't match?

If UserGems cannot match an incoming record to an existing person or company (by email or domain), the record is flagged as unmatched.

Can Custom Signal feed account scoring?

Yes. Custom Signal data can be used as an input to UserGems' Account & Contact Scoring models. For example, you can create a scoring rule that boosts account score when a recent inbound demo request is detected via Custom Signal.

How does UserGems handle repeated events for the same person?

UserGems uses the latest received entry as the source of truth for each signal per person. New pushes overwrite the previous values — UserGems does not sum or aggregate across multiple calls.

The recommended pattern for cumulative metrics (e.g., number of logins, dashboard unlocks) is to maintain the running total in your system and send the updated total with each push. For example, if a user unlocks a dashboard for the 5th time, send a single call with { dashboardUnlocks: 5 } rather than five separate calls. This also makes corrections simple: if you send incorrect data, just push again with the correct values.

How are signals date-stamped?

Signals are automatically date-stamped by UserGems at the time the API call is received. If you need to record a specific event date (e.g., when an action occurred in your system rather than when you pushed it), include a signalDate field in your payload using ISO 8601 format (e.g., 2026-05-15T14:00:00Z).

Is the API key secure if leaked?

The API is write-only — the only response returned is success or failed. A leaked key cannot expose any of your data. The main risk is that an unauthorized party could write incorrect data to your account. Keys are not auto-rotated; contact your CSM to request a key rotation if needed.

Do I need engineering support to set up SFDC Reports ingestion?

No. The SFDC Reports method is self-serve and requires no code. You need Salesforce access to build or share the relevant report, but the UserGems setup itself is point-and-click. API Push does require engineering support to build the push logic.