Freshservice Integration

When a field tech scans a biomedical device or IT asset, Forager confirms their physical location matches the asset’s CMDB record. This guide connects that confirmation event directly to Freshservice — so every successful scan updates the asset’s location in Freshservice automatically, with no manual entry. Choose this approach if your organization uses Freshservice for IT Asset Management and wants physical location data to stay current without extra admin work.

What happens

Tech scans BIO-4721 in Biomedical Storage (Forager app)
  → Attestation recorded in Forager
  → Forager POSTs to your proxy endpoint
  → Proxy looks up the asset by tag in Freshservice
  → Asset updated: last_discovered_at, location, confirmed_by

The update happens within seconds of the scan — before the tech has left the room.

Freshservice setup

Step 1 — Create a dedicated API user

Create a Freshservice agent account that the integration will authenticate as. Using a dedicated account makes it easy to audit integration activity and revoke access without affecting human users.

Go to Admin → Agents → New Agent
Set:
- Full name: Forager Integration
- Email: forager@yourcompany.com (a real address you control)
- Role: IT Agent (minimum required for asset writes)
Save and copy the agent’s API key from Profile Settings → API Key

Do not use an admin account for the integration. The IT Agent role is sufficient and limits the blast radius if credentials are ever compromised.

Step 2 — Create custom fields on your asset type

Freshservice’s native location field is a hierarchical reference — it doesn’t accept freeform text. The simplest path is to add four custom fields to store Forager data directly.

Go to Admin → Asset Management → Asset Types
Select your primary asset type (e.g. Computer, Medical Device)
Go to the Fields tab → Add Field
Add these four fields:

Field label	Field type	Notes
Forager Location	Single-line text	Full breadcrumb, e.g. `Memorial Hospital / Floor 3 / Biomedical Storage`
Forager Room	Single-line text	Room name only, e.g. `Biomedical Storage`
Forager Confirmed By	Single-line text	Display name of the tech who scanned
Forager Result	Single-line text	`match`, `mismatch_confirmed`, `mismatch_dismissed`, or `new_asset`

Note the field name (not label) for each — it will look like forager_location, forager_room, etc. You’ll need these exact names in the proxy.

If you use Freshservice’s native location field on a per-asset basis, you can omit Forager Location and instead have the proxy do a location lookup by name. This adds complexity — the four custom fields approach is simpler and works with Freshservice’s standard plan.

Proxy deployment

The proxy is a lightweight serverless function. It sits between Forager and Freshservice, receives the webhook payload, looks up the asset by tag, and calls the Freshservice API to update the record.

Option A — Deploy to Vercel (recommended, free tier is sufficient)

Create a new directory and initialize a project:

mkdir forager-freshservice-proxy && cd forager-freshservice-proxy
npm init -y

Create api/forager.js:

export default async function handler(req, res) {
  // Validate the shared secret Forager sends
  const secret = req.headers['x-forager-secret']
  if (secret !== process.env.SHARED_SECRET) {
    return res.status(401).json({ error: 'Unauthorized' })
  }

  const { asset_tag, last_discovered_at, location, room, discovered_by, discovery_type } = req.body

  if (!asset_tag) {
    return res.status(400).json({ error: 'asset_tag is required' })
  }

  const FS_DOMAIN  = process.env.FS_DOMAIN   // yourcompany.freshservice.com
  const FS_API_KEY = process.env.FS_API_KEY
  const auth = Buffer.from(`${FS_API_KEY}:X`).toString('base64')
  const fsHeaders = {
    Authorization: `Basic ${auth}`,
    'Content-Type': 'application/json',
  }

  // 1. Find the asset by tag
  const searchRes = await fetch(
    `https://${FS_DOMAIN}/api/v2/assets?search[asset_tag]=${encodeURIComponent(asset_tag)}`,
    { headers: fsHeaders }
  )
  if (!searchRes.ok) {
    console.error('Freshservice search failed:', searchRes.status, await searchRes.text())
    return res.status(502).json({ error: 'Freshservice search failed' })
  }
  const { assets } = await searchRes.json()
  if (!assets?.length) {
    // Log but return 200 so Forager doesn't retry — this asset may not be in Freshservice yet
    console.warn('Asset not found in Freshservice:', asset_tag)
    return res.status(200).json({ skipped: true, reason: 'asset_not_found' })
  }

  const displayId = assets[0].display_id

  // 2. Update the asset
  const updateRes = await fetch(`https://${FS_DOMAIN}/api/v2/assets/${displayId}`, {
    method: 'PUT',
    headers: fsHeaders,
    body: JSON.stringify({
      asset: {
        last_discovered_at,
        custom_fields: {
          forager_location:     location,
          forager_room:         room,
          forager_confirmed_by: discovered_by,
          forager_result:       discovery_type,
        },
      },
    }),
  })

  if (!updateRes.ok) {
    const text = await updateRes.text()
    console.error('Freshservice update failed:', updateRes.status, text)
    return res.status(502).json({ error: 'Freshservice update failed', detail: text })
  }

  return res.status(200).json({ ok: true, display_id: displayId })
}

Create .env (for local testing only — never commit this):

FS_DOMAIN=yourcompany.freshservice.com
FS_API_KEY=your_api_key_here
SHARED_SECRET=choose_a_random_string_here

Deploy to Vercel:

npx vercel --prod

Copy the production URL (e.g. https://forager-freshservice-proxy.vercel.app).

Set environment variables in the Vercel dashboard: Project → Settings → Environment Variables. Add FS_DOMAIN, FS_API_KEY, and SHARED_SECRET.

Option B — AWS Lambda (Node.js 20.x)

Use the same handler code above. Set the three environment variables in the Lambda function’s configuration. Use an API Gateway HTTP API trigger and copy the invoke URL as your webhook endpoint.

Forager configuration

Go to Dashboard → Settings → Webhooks → Add Webhook
Fill in:

Field	Value
Name	`Freshservice`
Endpoint URL	Your proxy URL + `/api/forager`
Target Platform	`Freshservice`
Auth Header Name	`X-Forager-Secret`
Auth Header Value	The `SHARED_SECRET` value you set in the proxy

Click Add Webhook. The webhook fires on every attestation from this point forward.

Testing

Send a test payload to your proxy to verify the Freshservice update works before relying on real scan data:

curl -X POST "https://your-proxy.vercel.app/api/forager" \
  -H "Content-Type: application/json" \
  -H "X-Forager-Secret: your_shared_secret" \
  -d '{
    "event": "forager.attestation",
    "asset_tag": "BIO-4721",
    "last_discovered_at": "2026-06-07T14:23:11Z",
    "location": "Memorial Hospital / Floor 3 / Biomedical Storage",
    "room": "Biomedical Storage",
    "discovered_by": "Maria Ortega",
    "discovery_type": "match"
  }'

Expected response:

{ "ok": true, "display_id": 42 }

Then open the asset in Freshservice and confirm:

Last discovered at is updated
Forager Location custom field shows Memorial Hospital / Floor 3 / Biomedical Storage
Forager Confirmed By shows Maria Ortega

Troubleshooting

Symptom	Likely cause	Fix
Proxy returns `401`	`X-Forager-Secret` doesn’t match	Verify the secret in Forager’s webhook config matches `SHARED_SECRET` in the proxy
Proxy returns `skipped: asset_not_found`	Asset tag doesn’t exist in Freshservice	Check the asset tag in both systems — they must match exactly, including case
`502` on search	`FS_API_KEY` or `FS_DOMAIN` wrong	Test the key directly: `curl -u "API_KEY:X" "https://DOMAIN/api/v2/assets?per_page=1"`
`502` on update	Custom field names wrong	Check the field names on the Freshservice asset type — they must match the `custom_fields` keys in the proxy exactly
Fields update but `last_discovered_at` doesn’t	Freshservice plan limitation	`last_discovered_at` updates require the Asset Management add-on on some Freshservice plans
Webhook fires but proxy logs nothing	Proxy URL is wrong	Test the URL with curl; check Vercel/Lambda logs for incoming requests

What your team gains

Every scan a biomedical or IT tech performs while working a ticket automatically updates Freshservice — with no dedicated inventory walk. After 30 days of normal field operations, the vast majority of active assets will have current, attestation-backed location data in Freshservice. Before your next Joint Commission or ISO 55001 audit, export the Freshservice asset list instead of scheduling a manual walkdown.

Getting Started

Field Tech Guide

Dashboard

EC Inspection Rounds

Admin

Integrations

API Reference

Troubleshooting

What happens

Freshservice setup

Step 1 — Create a dedicated API user

Step 2 — Create custom fields on your asset type

Proxy deployment

Option A — Deploy to Vercel (recommended, free tier is sufficient)

Option B — AWS Lambda (Node.js 20.x)

Forager configuration

Testing

Troubleshooting

What your team gains

​What happens

​Freshservice setup

​Step 1 — Create a dedicated API user

​Step 2 — Create custom fields on your asset type

​Proxy deployment

​Option A — Deploy to Vercel (recommended, free tier is sufficient)

​Option B — AWS Lambda (Node.js 20.x)

​Forager configuration

​Testing

​Troubleshooting

​What your team gains

What happens

Freshservice setup

Step 1 — Create a dedicated API user

Step 2 — Create custom fields on your asset type

Proxy deployment

Option A — Deploy to Vercel (recommended, free tier is sufficient)

Option B — AWS Lambda (Node.js 20.x)

Forager configuration

Testing

Troubleshooting

What your team gains