The vFound API and webhooks

Connect the vFound suite to the systems you already run: property management, service desks, HR and student systems, mailroom scanners, data warehouses or your own apps. Read and change records in every product, keep your people list in sync, get a signed webhook within seconds when something happens, and let AI assistants help at the desk.

Want a guided setup? See the vFound integration guides for Cloudbeds, OfficeRnD Flex, Microsoft Entra, Slack, Microsoft Teams, Google Chat, calendars, Zapier and MCP clients.

Authentication

Every venue has the API. An owner or manager creates up to 10 keys in Settings, For developers, choosing what each key may do. The full key is shown once. Send it as a Bearer token:

curl https://vfound.io/api/v1/items \
  -H "Authorization: Bearer vf_live_xxxxxxxxxx_…"

Items, claims, lost reports and analytics need vFound Lost & Found; parcels need vFound Parcels; tickets need vFound Checkroom; equipment needs vFound Equipment; visits need vFound Visitors; the people list needs Parcels, Visitors or Equipment; hotel stays need Lost & Found or Parcels. A product that is not open for the venue answers 403.

A key acts as the person who created it and stops working if that person no longer manages the venue. Changes made with a key go through the same rules, emails and audit trail as the desk. Each key can make 120 requests a minute. Base address: https://vfound.io/api/v1. Lists return 25 records a page (up to 100 with per_page) and accept page; most also filter with updated_since (ISO 8601) and search, as listed below.

Safe retries

Send an Idempotency-Key header (any unique value up to 191 visible characters, such as a UUID) with a POST, PATCH or DELETE. If the connection drops and you send the same request again with the same key within 24 hours, vFound does not repeat the change: it answers with the first response and the header Idempotent-Replayed: true. The same key with a different request is refused (422, idempotency_key_reused); a key whose first request is still running answers 409 (idempotency_in_progress). Server errors are not kept, so retrying after one runs the request again. An answer that carries something shown only once, such as the signing secret from POST /webhooks or a kiosk pairing code, is never stored either: a retry runs the request again, so check GET /webhooks before you subscribe the same address twice.

OpenAPI

The whole API, every event and every object is described in an OpenAPI 3.1 file: vfound.io/openapi/v1.json. Import it into Postman, Insomnia or your own code generator. A test keeps it in step with the API, so it never lists an endpoint that does not exist or misses one that does.

Ready-made operational system connections

Owners and managers configure these read-only provider connections in Settings, Connections, Operational systems. They are separate from the public REST API: the customer creates and controls the provider credential, the connection must pass a test before activation, repeated failures pause only that connection, and manual work remains available.

These are customer-configured API connections, not vendor certification claims. In particular, the Entra connection is not a Microsoft Marketplace app.

Items

Add an item

curl https://vfound.io/api/v1/items -X POST \
  -H "Authorization: Bearer $VFOUND_KEY" -H "Content-Type: application/json" \
  -d '{"title":"Black leather wallet","category":"Wallets & Purses","found_date":"2026-09-23",
       "location":"Front desk","colour":"Black","brand":"Fossil","tags":["leather","cards"],
       "photo":"data:image/jpeg;base64,…","photo_public":true}'

Fields: title and category are required. Optional: found_date, found_time (HH:MM), keep_until, location, description, colour, brand, tags, value_band (unknown, low, medium, high), notes (staff only), photo (a base64 data URL up to 8 MB) and photo_public. Photos sent through the API are not checked by vFound AI’s privacy guard, so set photo_public to false for any photo that shows personal details.

The item object

{"id":"9b2f…","title":"Black leather wallet","status":"in_care","category":"Wallets & Purses",
 "found_date":"2026-09-23","found_time":"14:30","keep_until":"2026-10-21","location":"Front desk",
 "description":null,"colour":"Black","brand":"Fossil","tags":["leather","cards"],"value_band":"low",
 "photo_public":true,"photo_url":"https://vfound.io/uploads/…","created_at":"…","updated_at":"…"}

Status is one of in_care, claimed, expired, donated, disposed or trash. A PATCH may set in_care, expired, donated, disposed or trash; returns to a guest happen through claims.

Claims

{"id":"k3f9x2a1b7c4d8e6","status":"ready_for_pickup","item":{"id":"9b2f…","title":"Black leather wallet"},
 "claimant":{"first_name":"Ana","last_name":"Ruiz","email":"ana@example.com","phone":null},
 "description":"…","place_lost":"Bar","date_lost":"2026-09-22","language":"es","created_at":"…","updated_at":"…"}

Claim status: unread, open, accepted, awaiting_information, ready_for_pickup, ready_for_shipment, shipped, closed, rejected or expired (accepted but never collected). Claimants’ details are personal data: keep them only as long as you need them.

Return shipping

GET /shipping and GET /shipping/{id} use claims:read to read order status, tracking, postage and the service fee. They return no delivery addresses, payment links or label PDFs. Paid return shipping is optional and is available only for enabled venues and reviewed routes. These reads cannot charge a card, buy a label or record physical carrier handoff.

Lost reports

GET/lost-reports lists what guests reported losing, with status (open or closed), the reporter’s contact details, the language they used and any Find My link they shared. Scope: lost_reports:read.

Analytics

GET/analytics?days=30 returns the same summary as Reports: items logged and returned, return rate, median days to return, where items ended up, categories, hotspots, busiest days, team output, the trend and guest feedback. days is 7, 30, 90 or 365. Scope: analytics:read.

Hotel stays

Stay context is private to the venue and deliberately minimal. It holds a stable stay reference, optional guest reference, guest name, arrival and departure, source timezone, current room, state and source timestamps. It never holds rates, payment details, loyalty data, identity documents, preferences or unrelated reservation notes.

curl https://vfound.io/api/v1/stays -X POST \
  -H "Authorization: Bearer $VFOUND_KEY" -H "Idempotency-Key: pms-event-901" \
  -H "Content-Type: application/json" \
  -d '{"external_stay_ref":"BOOK-100","guest_name":"Avery Chen","current_room":"412",
       "stay_state":"in_house","source_timezone":"America/New_York","source_updated_at":"2026-10-03T12:00:00Z"}'

Items and parcels accept optional stay_id and room_at_event. If room at event is omitted, vFound snapshots the stay’s current room. That snapshot does not change after a room move; the record also shows the current room, so the desk sees both.

Parcels

{"id":412,"status":"waiting","recipient":{"name":"Ana Ruiz","email":"ana@example.com","unit":"Room 214","reference":"S1044"},
 "carrier":"UPS","tracking":"1Z999AA10123456784","sender":null,"size":"small","shelf":"B2","pickup_code":"KQHRER",
 "notified_at":"…","collected_at":null,"collected_by":null,"returned_at":null,"created_at":"…","updated_at":"…"}

The pickup code is shown only while the parcel waits. Recipients’ details are personal data: keep them only as long as you need them.

Checkroom

Equipment

Visitors

Visitors’ details are personal data: keep them only as long as you need them.

People

The people list holds the residents, staff or students your desk serves. Parcels finds recipients in it, Visitors finds hosts, and Equipment suggests borrowers. Keep it in step with your HR, student or property system through the API.

Owners and managers can also connect a public HTTPS CSV link from People. vFound checks it hourly, follows at most three redirects after checking each destination, accepts at most 10 MB, and in mirror mode stops before making changes when the valid row count falls by more than 30 percent. Connected fields are changed at their source.

Automatic directory provisioning

Microsoft Entra has the ready-made customer-configured connection described above. Identity directories including Okta, OneLogin and JumpCloud can instead provision the people list at https://vfound.io/api/scim/v2/Users with a vFound API key that has people:write. Use the bearer key as the secret token. Deactivation removes the person from suggestions; DELETE anonymises links through the same People rules. This endpoint creates people-list entries only and never team logins.

Webhooks

Add up to 25 HTTPS addresses in Settings, For developers, or through the API below, and choose which of the events below each one receives. vFound sends a JSON POST within seconds, retries failures for about three hours, and pauses an address after 15 failed deliveries in a row.

{"id":"evt_…","type":"claim.created","created":"2026-09-23T14:30:00+00:00",
 "venue":{"code":"harbourhotel","name":"Harbour Hotel"},"data":{ …the claim… }}

Check the signature

Every delivery carries Vfound-Signature: t=<unix time>,v1=<hex>, where the hex is an HMAC SHA256 of t + "." + raw body with your endpoint’s secret. Reject deliveries older than five minutes. After you make a new signing secret, deliveries carry two v1 values for 24 hours, one for each secret, so accept the delivery if any of them matches.

// Node.js
const crypto = require("crypto");
function verified(rawBody, header, secret) {
  const parts = header.split(",").map((p) => p.split("="));
  const t = (parts.find(([k]) => k === "t") || [])[1];
  const expected = crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && parts.some(([k, v]) => k === "v1" && v.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v)));
}

// PHP
$t = null; $signatures = [];
foreach (explode(',', $header) as $part) {
    [$k, $v] = array_pad(explode('=', $part, 2), 2, '');
    if ($k === 't') { $t = $v; } elseif ($k === 'v1') { $signatures[] = $v; }
}
$expected = hash_hmac('sha256', $t.'.'.$rawBody, $secret);
$ok = abs(time() - (int) $t) < 300
    && count(array_filter($signatures, fn ($s) => hash_equals($expected, $s))) > 0;

Headers also include Vfound-Event and a unique Vfound-Delivery id you can use to ignore repeats. Webhooks are sent only to public HTTPS addresses on port 443.

Subscribe through the API

Tools such as Zapier can add and remove their own addresses with a key that has webhooks:manage. The signing secret is shown once, in the answer to the POST. The response also carries a Location header with the address to call with DELETE when the subscription is removed.

A key can subscribe only to events whose data it could read: each event needs the read scope of its product (items:read for item events, claims:read for claim events, lost_reports:read, parcels:read, checkroom:read, loans:read for equipment events, visitors:read for visit, visitor type, kiosk and courier events, and people:read for person and people list events). A key lists and removes only the addresses it created itself; addresses added in Settings, or by another key, are not visible to it.

Delivery history

Settings, For developers, lists every delivery to each address from the last 30 days, with how it went, and sends any of them again with the same Vfound-Delivery id. There you can also edit an address, switch a paused one back on, and make a new signing secret. An address that fails 15 deliveries in a row is paused, and the venue owner gets an email.

Shipping reads: list_return_shipping and return_shipping_status.

AI assistants (MCP)

vFound is a Model Context Protocol server at https://vfound.io/api/mcp, so AI assistants can look things up and help at the desk. Connect one in either of two ways: sign in with vFound, for assistants whose connectors sign in with OAuth, or an API key, for clients that send a header, such as Claude Code, Cursor and Visual Studio Code. Either way it sees only the tools its scopes allow, for the products your venue has open.

# Claude Code
claude mcp add --transport http vfound https://vfound.io/api/mcp \
  --header "Authorization: Bearer $VFOUND_KEY"

// Cursor (.cursor/mcp.json)
{"mcpServers":{"vfound":{"url":"https://vfound.io/api/mcp","headers":{"Authorization":"Bearer vf_live_…"}}}}

// Visual Studio Code (.vscode/mcp.json)
{"servers":{"vfound":{"type":"http","url":"https://vfound.io/api/mcp","headers":{"Authorization":"Bearer vf_live_…"}}}}

Each tool runs the API request above with the same checks, so an assistant can never do more than its key or connection. There are no tools that hand anything over, sign anyone in or out, decide a claim or delete. Each answer counts toward the key’s or connection’s 120 requests a minute.

Sign in with vFound

Add https://vfound.io/api/mcp as a connector in your own assistant. The assistant finds how to sign in by itself and opens a vFound page, where an owner or manager signs in to their workspace as usual, chooses the venue and sees in plain words what the assistant may do, and can untick anything. Staff and view-only members cannot connect an assistant. The assistant is your venue’s own: your subscription with its provider pays for its AI, and vFound receives only the tool requests it sends.

A connection acts as the person who allowed it, with the same checks as an API key: it stops working if that person no longer manages the venue or the venue is not active, it changes nothing while the subscription is paused, and it sees tools only for open products. Its access token lasts an hour and the assistant renews it by itself; a connection unused for 30 days signs in again. See each one, who connected it and when it was last used in Settings, For developers, where Disconnect stops it at once. The token works only on the MCP endpoint, not on the REST API.

For client developers: OAuth 2.1 as the MCP authorization specification describes, with the authorization code flow and PKCE (S256) only. Discovery: /.well-known/oauth-protected-resource (RFC 9728, resource https://vfound.io/api/mcp) and /.well-known/oauth-authorization-server (RFC 8414); a request without a token gets a WWW-Authenticate header that names the first. Clients register themselves at /oauth/register (RFC 7591) as public clients with no secret; redirect addresses must use https, or http only for localhost or 127.0.0.1, and must then match exactly. Then /oauth/authorize, /oauth/token (codes last 60 seconds and work once; refresh tokens are replaced on each use, and reusing an old one disconnects the assistant) and /oauth/revoke (RFC 7009). Scopes use the API key names above; send resource=https://vfound.io/api/mcp (RFC 8707).

Errors

Errors are JSON with a message; validation errors add errors by field. 401 means no valid key, 403 a missing scope, a key whose creator no longer manages the venue, a venue that is not active, or a change sent while the subscription is paused, 404 not found in your venue, 422 invalid input and 429 too many requests.

When a change cannot happen because of the record’s current state, the answer is 422 with a stable code as well. The codes never change name:

Retries with an Idempotency-Key header can also answer with a code: