How can we help?

Overview

The UserGems API lets you push first-party data from any external system — a product database, data warehouse, or custom backend — directly into UserGems. Once received, that data is associated with a Custom Signal where it can trigger Gem-E campaigns, feed account scoring models, and personalize AI outreach alongside any other native UserGems signal.

A few things to know before you start:

• The API is write-only. You push data in; you cannot query or pull data back out. To send data from UserGems to an external system, use the Send to Webhook action in a campaign.
• The API does not poll your system. It only processes records when you actively send them. If you stop sending updates, data in UserGems will go stale.
• Setting this up requires engineering support — someone on your team needs to write the code that sends records to UserGems.
• Rate limit: 20 requests per second, one record per request.

Looking for the full endpoint and parameter reference? See the UserGems Developer Hub.

Limitations

The API has five endpoints — all write or delete only:

‌

The following are not currently supported:

• Pulling data out via API — there are no read or GET endpoints
• Bulk uploads — one record per POST request
• Multiple API keys — there is one key per company, shared across all integrations. There is no way to issue separate keys per system, isolate a misbehaving integration, or create a sandbox key for testing
• HMAC webhook signing — outbound webhook verification uses header-based X-Api-Key only

Setup

Step 1: Get your API key

Your API key authenticates every request. Store it securely in an environment variable or secrets manager and never hard-code it. There is one key per company — if you need it rotated, contact your CSM or email support@usergems.com.

Go to Settings → Connected Applications and scroll to the bottom to find your API Token.

Step 2: Decide how your signal gets created

To configure it before any data arrives — navigate to Signal → First-Party Person/Company Signal → Create Signal and select API as your ingestion method. See Custom First-Party Person & Company Signals for the full walkthrough.

If you're only using the API to add contacts for job change tracking and don't need a Custom Signal at all, omit the signal field from your payload. Please note that a contact pushed for job change tracking will not appear in your prospects overview until a job change actually fires.

Step 3: Push records

All requests use the same authentication header:

X-Api-Key: your_api_key

‌

Adding a contact. email is the matching key.

curl -X POST -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "Acme Corp",
    "signal": "Credit Limit Exceeded",
    "creditsUsed": 1250
  }' \
  "https://api.usergems.com/v1/contact"

‌

Successful response:

{ "message": "Contact added to queue" }

‌

Full parameter list: Developer Hub → Add Contact

Adding an account. domain is the matching key.

curl -X POST -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reportId": 12345,
    "name": "Acme Corp",
    "domain": "acme.com",
    "signal": "High Intent Account"
  }' \
  "https://api.usergems.com/v1/account"

‌

Successful response:

{ "message": "Account added" }

‌

Full parameter list: Developer Hub → Add Account

Step 4: Build your Audience and Campaign

Once a successful API call is received, the data populates your Signal. From there, the signal does not automatically trigger any outreach — you need to set up the campaign yourself:

1. Go to Audience and build a new audience using your Custom Signal as a filter.
2. Go to Campaigns and create a new campaign on that audience.
3. Configure your Gem-E messaging, workflow actions, and any Conditional Instructions that reference your signal data.

This is the same process as any other signal in UserGems. The signal behaves like a native signal once data is in — it can be filtered in audiences, weighted in scoring models, and referenced in Gem-E personalization.

Before You Build

The Developer Hub has the complete parameter list for every endpoint. Four things it either gets wrong or doesn't make obvious:

• reportId is required when adding an account, even though the reference lists it as optional. Omit it and the request fails with a 422.
• Add and delete are not symmetrical. Adding an account uses reportId; deleting one uses reportName. Different field, different value.
• Deleting a contact removes it from everything by default. DELETE /v1/contact takes an optional relationshipType and signal — leave both out and the contact is removed from all relationship types and all signals, not just one.
• One record per request. There is no bulk endpoint, and the rate limit is 20 requests per second. Plan your throughput accordingly.

Common Use Cases

Trigger expansion plays on over-consumption

Push a record when a customer hits a usage threshold in your product. Include the specific metric as a Signal Field so Gem-E can reference it directly in outreach — making the message far more relevant than a generic expansion email.

‌

Real-time event-based signals

If your system generates time-sensitive signals — usage spikes, competitive triggers, crisis alerts — push those records as they occur. Your engineering team handles sending the alert; UserGems handles the outreach logic from there.

Connect your external data

If your first-party data lives outside Salesforce — in a product analytics system, a data warehouse, or a custom backend — the API push is how you get it into UserGems without routing it through your CRM first.

Tip: Custom signals are most powerful when layered with job change data. A contact who triggered a product usage signal and also recently changed jobs is one of the highest-intent outreach moments in the platform.

Error Codes

‌

FAQ

Can I use the API to pull data out of UserGems?

No. All five endpoints are write or delete only. For sending data from UserGems to an external system, see Send to Webhook.

Is my API key secure if it gets leaked?

The API is write-only, so a leaked key cannot expose any of your data. The risk is that an unauthorized party could write incorrect data to your account. Keys are not auto-rotated — contact your CSM to request a new key if needed.

Can I use signal data in Gem-E messaging?

Yes. Any Signal Field passed through the API can be referenced in Gem-E Conditional Instructions. Go to Content → Conditional Instructions, add a filter for your custom signal, and add your instructions there.

Do I need engineering support?

Yes — unlike the SFDC Report and CSV methods, the API push requires someone on your team to write the code that sends data to UserGems. Those two methods are self-serve and require no code.

‌