vFound homeRequest your free trial
DEVELOPERS

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 site 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_…"
ScopeAllowsEndpoints
items:readRead found items, categories and moves between sitesGET /items, /items/{id}, /categories, /item-transfers
items:writeAdd and update found items, and send or receive them between sitesPOST /items, PATCH /items/{id}, POST /item-transfers and its cancel and receive
claims:writeRecord human ownership reviews, decisions, release approval and pickupPOST /claims/{id}/verification, /claims/{id}/decision, /claims/{id}/release-approval, /claims/{id}/handover
lost_reports:writeCreate guest reports for a contact centrePOST /lost-reports
claims:readRead claims, with the claimant’s contact detailsGET /claims, /claims/{id}
lost_reports:readRead guests’ lost reportsGET /lost-reports
analytics:readRead the analytics summaryGET /analytics
parcels:readRead parcels, with each recipient’s name and emailGET /parcels, /parcels/{id}
parcels:writeLog, hand over, return and remindPOST /parcels and its actions
checkroom:readRead tickets, stations, events, the exit queue and reportsGET under /checkroom
checkroom:writeCheck in, hand back, mark ready and manage stations or eventsPOST and PUT under /checkroom
loans:readRead equipment and who has itGET /loans, /loans/items and one of each
loans:writeAdd equipment, hand it out, extend and take backPOST and PATCH under /loans
visitors:readRead visitsGET /visitors, /visitors/{id}
visitors:writeInvite, sign in and out, cancel, send a passPOST /visitors and its actions
visitors:screeningConfirm that a visitor’s screening match was checked: send screening_reviewed, or approve a visit a match holds. Off by default; what the key does is recorded as the key’s, with its namePOST /visitors, /visitors/{id}/sign-in, /visitors/{id}/approve
people:readRead the people listGET /people, /people/{id}
people:writeAdd, update, sync and remove peoplePOST, PATCH and DELETE under /people
stays:readRead private hotel stay context and its correction historyGET /stays, /stays/{stay}
stays:writeIdempotently add or update stay context from a hotel systemPOST /stays
school:readRead pupils’ late arrivals and early leaves from the school officeGET /school/movements
school:writeAdd or update pupils from the school information systemPUT /school/pupils
queue:readRead queue lines, tickets, booked times, messages, survey figures and the queue reportGET under /queue
queue:writeAdd people to a line, call them, finish their tickets, book and cancel times and write to people in linePOST under /queue
webhooks:manageSubscribe and unsubscribe the key’s own webhook addresses, for events whose data the key can readGET, POST and DELETE /webhooks

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; the school office needs Visitors with the school office turned on (it answers 404 while it is off); queue lines and tickets need vFound Queue. A product that is not open for the site answers 403.

A key acts as the person who created it and stops working if that person no longer manages the site, unless the request names a team member in X-Acting-User (see Acting for a team member). Changes made with a key go through the same rules, emails and audit trail as the desk, and each audit entry records the key that made the change. 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.

Test keys

A key made as a test key starts with vf_test_ and can hold only queue:read and queue:write. It works on one labelled test line, Test line (sandbox) (line 1, counter 1), and nowhere else: the same Queue addresses as a live key for lines, slots, tickets, /queue/join, call next, call, served, no-show and remove answer from the test line; every other address answers 403 with code: test_key. A test key never reads or changes a real line or ticket and sends no email, text, browser alert or webhook. A test key ignores Idempotency-Key: the same request sent twice runs twice. Answers carry "sandbox": true and the header X-Vfound-Sandbox: 1. A test line holds up to 100 tickets per key, with no email address, and they are deleted with the key and after seven days. Use made-up names.

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). After finder or claimant personal details are erased, stored responses for that site instead return 410 with no erased details; refresh the record rather than retrying the old write with a new key. 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.

Acting for a team member

An app your team uses at the desk, such as a station or depot app, can say which team member it is acting for. Send X-Acting-User with the person’s sign-in email or their user id. They must be an active member of the key’s site right now. The request then runs as them: the item history and the claim history name that person instead of the key’s creator, and the audit trail names that person, the key and the manager who created the key. They can do only what both the key’s scopes and their own role at the site allow: a viewer can only read, staff can also change items, claims, lost reports, parcels, checkroom tickets, equipment, visits and hotel stays, and owners and managers can use every scope the key has. A name that is not an active member of the site is refused with 403 and acting_user_refused, with the same message whether or not the address exists; a scope the person’s role does not allow is refused with 403 and acting_user_role. Safe retries are kept per person, so one person’s saved answer is never replayed for another. The header works with site keys only, not with an assistant connected by signing in, which already acts as the person who connected it. vFound checks that the named person is an active member; it does not ask them to sign in, so name people only from an app your team signs in to. Without the header a key works exactly as before.

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.

SystemWhat vFound readsvFound areas
CloudbedsMinimal reservation and room context through a customer-controlled property key limited to read:reservation. Part of vFound Enterprise.Private Stays for Lost & Found and Parcels
OfficeRnD FlexMember ID, name, email and active state through flex.community.members.read, with an optional location filter.The shared people list for Parcels, Equipment and Visitors
Microsoft Entra IDUser ID, display name, email and active state through Microsoft Graph delta updates and administrator-consented User.Read.All.The shared people list for Parcels, Equipment and Visitors

These are customer-configured API connections, not vendor certification claims. Testing, turning on and syncing a connection are part of vFound Enterprise. In particular, the Entra connection is not a Microsoft Marketplace app.

Oracle OPERA Cloud is not available. The fail-closed server adapter remains disabled until Oracle access, the hotel's approval, exact environment configuration and live acceptance are complete. It is not advertised as certified or customer-validated.

Items

RequestWhat it doesScope
GET/itemsItems, newest change first. Filters: status, search (words in the title, description, brand, colour or tags), updated_since (ISO 8601), page, per_page (up to 100).items:read
GET/items/{id}One item by its id.items:read
GET/categoriesThe category names an item can use.items:read
POST/itemsAdd a found item. It is published to your guest page, runs alerts and matching, and appears in your audit trail like one added by hand.items:write
PATCH/items/{id}Change details or status.items:write
GET/item-transfersFound items this site sent to, or receives from, another site of the same customer group, items on their way first. Also lists the sites you can send to (destinations) and this site’s storage bins (bins). Filters: status (in_transit, received or cancelled), direction (incoming or outgoing).items:read
POST/item-transfersSend an item waiting for its owner to another site of the group: item_id, destination_business_id and an optional note. Only for keys made by an owner or manager. The item leaves the sending venue's guest page (if that venue shows its found items) and cannot change until it arrives. An item with any claim stays where it is.items:write
POST/item-transfers/{id}/cancelThe sending site takes the item back before it is received.items:write
POST/item-transfers/{id}/receiveThe receiving site confirms it arrived, with bin_id (required when the site has storage bins) or location. The item then belongs to this site with its photos, history and dates, and is matched against this site’s lost reports like a newly logged item.items:write

Lost & Found and Checkroom desk tools

New email settings default off. Scan counts and closing discrepancies are review-only. P90 uses the nearest-rank 90th percentile of valid timestamp intervals; absent samples return null. Physical piece capacity warns but never blocks check-in. See the OpenAPI description for request fields. Setup templates and settings require an owner or manager.

Method and pathWhat it doesScope
GET /lost-found/context-schemaRead versioned private context field definitions, without record values. Either listed read scope is sufficient.items:read or lost_reports:read
GET /lost-found/desk-settingsRead optional desk settings.lost_reports:read
PUT /lost-found/desk-settingsReplace desk settings; owner or manager only. New mail settings default off.lost_reports:write
GET /checkroom/desk-settingsRead optional desk settings.checkroom:read
PUT /checkroom/desk-settingsReplace desk settings; owner or manager only. New mail settings default off.checkroom:write
GET /lost-found/countsList the latest 30 scan-count sessions.items:read
POST /lost-found/countsSnapshot held item identifiers for a report-only count; no custody changes.items:write
GET /lost-found/counts/{id}Read a count with missing, unexpected and no-longer-here figures.items:read
POST /lost-found/counts/{id}/scanRecord a QR or short item-label scan; duplicate known items count once.items:write
POST /lost-found/counts/{id}/finishFinish a count without changing items.items:write
GET /lost-found/queuesList the current key creator’s saved work queues in this site.lost_reports:read
PUT /lost-found/queues/{id}Replace your own saved queue; underlying items and claims are unchanged.lost_reports:write
DELETE /lost-found/queues/{id}Delete your own saved queue; underlying items and claims are unchanged.lost_reports:write
POST /lost-found/queuesSave a named work-queue preset for the current key creator.lost_reports:write
GET /lost-found/queues/{id}Read current records behind a saved queue. Incoming transfers open the existing permissioned transfer view.lost_reports:read, items:read, claims:read
POST /lost-found/intake-reviewReturn deterministic completeness and privacy prompts; no AI or mutations.items:read
GET /checkroom/templatesList configuration-only setup templates; manager only.checkroom:read
PUT /checkroom/templates/{id}Replace a setup template as a manager; underlying events, stations and tickets are unchanged.checkroom:write
DELETE /checkroom/templates/{id}Delete a setup template as a manager; underlying events, stations and tickets are unchanged.checkroom:write
POST /checkroom/templatesSave an event’s station configuration without guests or tickets; manager only.checkroom:write
POST /checkroom/templates/{id}/applyCreate a new event and stations; active number-range collisions reject the entire operation.checkroom:write

Lost & Found contact centre and custody

Human-operated integrations can create a guest report, record an ownership review, decide a claim and record physical pickup. New write scopes must be selected explicitly; existing keys do not gain them. None of these claim or disposition writes is offered as an MCP or Ask vFound tool. Your integration is responsible for identifying and authorising its human operator: the audit names the manager who created the key and, when the integration sends X-Acting-User, also the team member it named, whom vFound does not authenticate.

Method and pathWhat it doesScope
POST /lost-reportsContact-centre intake: first_name, last_name, email, title and description; optional phone, category id, colour_brand, place_lost, date_lost and language. Sends the normal guest confirmation/private link and starts the 90-day watch. Phone consent is never inferred. Existing open-report limits apply.lost_reports:write
PUT /lost-reports/{id}Edit what was lost using the fingerprint returned by GET /lost-reports. Title and description are required. Omitted journey preserves saved details; disabled collection refuses context changes. Contact changes require the separate verified contact flow.lost_reports:write
GET /lost-reports/{id}/matchesUp to 24 live text/category candidates, each with match.label, reason and source. Fresh stored AI verdicts use cached_ai; otherwise a keyword suggestion is labelled possible. No new model call or ownership decision.lost_reports:read and items:read
GET /items/{id}/matchesMatching report id/title without reporter contact details; up to 24 matches from the latest 1,000 open reports. Same source labels and no new model call.items:read and lost_reports:read
POST /claims/{id}/verificationRecord verified (boolean) and method (distinctive_details, purchase_proof or staff_review). Human attestation, not automated document authentication; no document copy or free-text evidence. Latest review must pass before API acceptance.claims:write
POST /claims/{id}/decisionstatus: open, accepted, rejected, expired, ready_for_pickup, ready_for_shipment, shipped or handed_to_courier. The existing state machine and second approval apply. Manual shipment fields use the workspace rules. With accepted, an optional return (pickup or shipment) moves the claim on to that stage in the same request, with one email to the claimant; when a high-value release still needs its second approval, the claim stays accepted and return_notice says why (the same request again changes nothing). An optional arranged_by (site or owner) says who books a courier or post return, and every claim answer shows it. Without arranged_by, a delivery address sent in shipment (or one the claim already has) means your team posts it, as before; otherwise the site’s Lost & Found setting decides. owner means the claimant’s own courier collects the item: no address is asked for, an address sent with owner is refused, and shipped is refused. When their courier collects it, send handed_to_courier with the courier company in shipment.carrier and its booking reference in shipment.tracking_number; the claim closes. To change who books it, move the claim to ready_for_pickup and back to ready_for_shipment with arranged_by.claims:write
POST /claims/{id}/release-approvalA different manager approves an accepted high-value release, under the same checks as the workspace.claims:write
GET /claims/{id}/custodyReview and stage history, approver and pickup name/time. signature_recorded is a boolean; no signature image or private file address is exposed.claims:read
POST /claims/{id}/handoverRecord physical pickup from ready_for_pickup, with handover.name and a PNG data URL in handover.signature when required. Repeated closed calls preserve the first receipt.claims:write
POST /items/{id}/dispositionkind donated/disposed, recipient for a donation, optional notes. The holding date and pending/accepted claim checks apply. Returns the numbered batch receipt.items:write

Use an Idempotency-Key for write retries. A verification record does not authenticate an identity document or itself approve ownership. Initial report creation follows the guest workflow, including site-enabled AI; match-list GETs use cached verdicts and text search only. These are generic REST/OpenAPI operations; no WSO2 installation or native connector has been certified.

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/…","transfer":null,"created_at":"…","updated_at":"…"}

Status is one of in_care, in_transit (on its way to another site; transfer then names both sites), 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

RequestWhat it doesScope
GET/claimsClaims, newest change first. Filters: status, updated_since, page, per_page.claims:read
GET/claims/{id}One claim by its reference.claims:read
{"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","arranged_by":null,"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). arranged_by says who books a courier or post return: venue (your team posts it) or owner (the claimant’s own courier collects it); null when the claim has no such return. Claimants’ details are personal data: keep them only as long as you need them.

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 site 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.

RequestWhat it doesScope
GET/staysList stays. Filters: search (guest, stable reference or current room), state, source, page and per_page. A room match helps navigation only; it never suggests ownership.stays:read
GET/stays/{stay}One stay and its auditable source/correction history.stays:read
POST/staysCreate or update the API source record identified by external_stay_ref. Send source_updated_at; delayed or replayed events no newer than the saved event are acknowledged without replacing newer data.stays:write
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

RequestWhat it doesScope
GET/parcelsParcels, newest change first. Filters: status (waiting, collected or returned), search (recipient, unit, tracking number, sender or pickup code), updated_since.parcels:read
GET/parcels/{id}One parcel.parcels:read
POST/parcelsLog a parcel for recipient_email (matched to your people list) or recipient_name, with optional unit, carrier, tracking, sender and shelf. The person is emailed their pickup code unless notify is false.parcels:write
POST/parcels/{id}/collectHand it over: collected_by (required) and an optional signature (a PNG data URL).parcels:write
POST/parcels/{id}/returnReturn it to the sender, with an optional note.parcels:write
POST/parcels/{id}/remindEmail the recipient a reminder to collect it.parcels:write
POST/parcels/trackingNormalise a tracking number and detect UPS, FedEx, USPS, DHL, Amazon or an S10 international carrier. A valid GS1 SSCC is accepted as shipment tracking; a GS1 product identifier is identified but never treated as a parcel number.parcels:read
GET/parcels/pickup-queuePeople who said they are at the desk, with their parcel count and shelves.parcels:read
POST/parcels/pickup-queue/{id}/serveMark one desk arrival as served.parcels:write
POST/parcels/bulk-remindEmail reminders for up to 200 selected waiting parcels.parcels:write
POST/parcels/bulk-returnReturn up to 200 selected waiting parcels to sender.parcels:write
GET/parcels/shelvesParcel shelf capacities and current occupancy.parcels:read
POST/parcels/shelvesCreate a shelf or change its capacity.parcels:write
GET/parcels/analyticsVolume, carrier mix, collection time, uncollected rate and busiest shelves.parcels:read
GET/parcels/outgoingOutgoing parcels ready for a courier or handed over.parcels:read
POST/parcels/outgoingLog an outgoing parcel.parcels:write
POST/parcels/outgoing/{id}/handoffRecord the courier and signature at handoff.parcels:write
GET/parcels/roundsDelivery rounds and their stops.parcels:read
POST/parcels/roundsCreate a campus or office round from waiting parcels.parcels:write
POST/parcels/rounds/{round}/stops/{stop}/deliverComplete a stop with the recipient name and signature.parcels:write
GET/parcels/couriersCouriers logged through Visitors, with status in or out.parcels:read
{"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

RequestWhat it doesScope
GET/checkroom/ticketsTickets, newest change first, with status (pending, in, returned, left or moved), the number, what was handed in, individually tagged piece_records, the guest’s details if given, the fee recorded at the desk and the times. Filters: status, search (guest, room, ticket number, piece tag or ticket code), updated_since.checkroom:read
GET/checkroom/tickets/{id}One ticket.checkroom:read
POST/checkroom/ticketsCheck something in and get the next free number: kind (coat, bag, luggage or other, required), pieces, optional piece_details with one kind and storage location for each piece, guest_name, guest_email, guest_room, collect_by for luggage, notes, fee_method (cash or card), station_id, event_id, storage_location, language and photo. The answer also carries guest_ticket (the code and the private ticket address) once, to show as a QR code or print for the guest; reads, lists and webhooks never include it.checkroom:write
POST/checkroom/tickets/{id}/hand-backHand it back once your system has read the guest’s ticket, with optional collected_by and signature. Send piece_ids to return selected pieces and leave the others open; omit it to return every open piece. without_ticket records that the guest lost their ticket and then needs collected_by and signature.checkroom:write
GET/checkroom/stationsList the site's checkroom stations, number ranges and storage locations.checkroom:read
POST/checkroom/stationsCreate a station with a non-overlapping number range.checkroom:write
PUT/checkroom/stations/{id}Change a station, its number range, storage locations or active state.checkroom:write
GET/checkroom/eventsList recent and upcoming checkroom events.checkroom:read
POST/checkroom/eventsCreate an event with its expected volume and stations.checkroom:write
PUT/checkroom/events/{id}Change an event's times, forecast or stations.checkroom:write
GET/checkroom/exit-queueTickets whose guests asked the desk to get their things ready.checkroom:read
POST/checkroom/tickets/{id}/readyMark a waiting ticket ready and notify the guest.checkroom:write
GET/checkroom/reportTicket volume, peak hours, return time and fees by method and staff.checkroom:read
GET/checkroom/exportDownload the checkroom report rows as formula-safe CSV.checkroom:read

Queue

Lines, the people waiting in them and the counters they are called to. Every change runs the same steps as the desk, with the same history, as the key's creator or the team member named in X-Acting-User. A ticket never carries the guest's email or their answers to the line's questions.

RequestWhat it doesScope
GET/queue/linesLines with their state now, people waiting and an estimated wait for someone joining now.queue:read
GET/queue/lines/{id}One line.queue:read
GET/queue/ticketsTickets of one site day (day, today by default), in calling order; filter by line and status.queue:read
GET/queue/tickets/{id}One ticket.queue:read
GET/queue/reportTickets, people served, no-shows, people who left, and median wait and service minutes for the last days.queue:read
POST/queue/ticketsAdd a person to a line, as the desk does.queue:write
POST/queue/call-nextCall the next person to a counter (counter_id). Two callers never get the same person; data is null when nobody is waiting.queue:write
POST/queue/tickets/{id}/callCall a chosen person to a counter.queue:write
POST/queue/tickets/{id}/servedMark the person at a counter served.queue:write
POST/queue/tickets/{id}/no-showMark a called person who did not come as a no-show.queue:write
POST/queue/tickets/{id}/removeTake a person out of the line.queue:write
GET/queue/bookingsBooked times, earliest first, with from, to, line, status and paging. Never the person's email.queue:read
POST/queue/bookingsBook one of the free times of a line's booked-times page for a person (line_id, starts_at, email).queue:write
POST/queue/bookings/{id}/cancelCancel a booked time; the person is emailed that the team cancelled it.queue:write
POST/queue/bookings/{id}/arrivedCheck a booked person in; their ticket is placed by the booked time.queue:write
POST/queue/tickets/{id}/arrivedMark a person who joined before arriving as here.queue:write
GET/queue/tickets/{id}/messagesThe messages between a person in line and the team, oldest first. Reading marks the person's messages as read.queue:read
POST/queue/tickets/{id}/messagesWrite to a person in line (body, 1 to 500 characters), as the key's team member.queue:write
GET/queue/surveySurvey figures after service: answers, average, each rating, by line, service, counter and team member (a team member's average appears from 5 answers). Never comments.queue:read
GET/queue/performancePlain figures for each team member over the same days as the report. No score and no ranking.queue:read
GET/queue/lines/{id}/slotsThe open booked times of a line, as its booking page offers them.queue:read
POST/queue/joinTake a number for a guest of your own website, under the guest rules (open line, limits, required answers and consent boxes). Send it from your server: the key replaces the captcha.queue:write
GET/queue/tickets/lookupFind tickets by the number the guest holds.queue:read
GET/queue/tickets/{id}/statusWhat the guest's own ticket page shows: place, estimate and sentence.queue:read
GET/queue/tickets/{id}/historyThe steps of one ticket. Who did each is team, guest, api (a join through a key) or system (done automatically, such as the automatic no-show), never a name.queue:read
GET/queue/customers/historyVisits of someone who asked to be remembered, found by email, while the site has recognition on. It tells the key holder whether an email address belongs to a remembered visitor.queue:read
GET/queue/insightsCounts for the same days as the report: people who left before being called, booked and walk-in people, the share called within the wait target by line and week, and busy hours from past weeks. Counts only; never a name or an answer.queue:read
GET/queue/report-dataThe Queue tickets as the report builder reads them (fields[], limit up to 1000, offset), for BI tools. The guest name is never included.queue:read

Equipment

RequestWhat it doesScope
GET/loansEquipment handed out, newest change first, with status (out, returned or lost), whether it is overdue, the item, the borrower and the times. Filters: status (out, returned, lost or overdue), search (borrower name, email or reference), updated_since.loans:read
GET/loans/{id}One loan.loans:read
POST/loansHand something out: item_id or item_code (the code on its label, or the link its QR code holds), borrower_name (required), optional person_id to link the people list, borrower_email for a receipt, borrower_reference, due_at, note, language and signature.loans:write
POST/loans/{id}/extendGive more time: a new due_at. The borrower is emailed the new time.loans:write
POST/loans/{id}/returnTake it back, with an optional condition (good, damaged or incomplete), note, and set_aside to put the item aside for repair.loans:write
POST/loans/returnsTake several things back together: loan_ids (1 to 50), with the same optional condition, note and set_aside for all of them. All or nothing: if one is already back or not found, nothing changes. A borrower with an email address gets one receipt for each checkout, listing everything that came back, and each loan sends its own loan.returned event.loans:write
GET/loans/itemsEverything the desk hands out, by name. Filters: status (available, out, repair or retired), search (name, asset tag or label code), updated_since.loans:read
GET/loans/items/{id}One item, with the link its label’s QR code holds.loans:read
GET/loans/items/{id}/ticketsTickets sent to the site’s own Jira, Zendesk or ServiceNow for this item (beta), with the status last read back.loans:read
POST/loans/itemsAdd equipment: name (required), category, tag, location, notes, loan_hours (how many hours it usually goes out for), photo, product and variant (units of one product and variant can be booked as one), and copies to add up to 50 identical items, numbered.loans:write
PATCH/loans/items/{id}Change its details, or set status to available, repair or retired. product and variant change its product family; cleaning_status needs_cleaning marks it as waiting to be cleaned and null marks it cleaned. Items show product, variant, cleaning_status and cleaning_since.loans:write
GET/loans/items/{id}/tagWhether an NFC or RFID tag is linked, and the last four hex digits of its serial number.loans:read
PUT/loans/items/{id}/tagLink a tag by its serial number, as a phone reads it or as a keyboard-type reader types it (hex, reversed hex or decimal); it replaces any tag the item had.loans:write
DELETE/loans/items/{id}/tagRemove the item’s tag.loans:write
POST/loans/checkoutsHand out one to 50 items in one atomic checkout, or hand out a saved kit. It accepts a person, due time, note and optional signature, and stock lines (stock) handed out on the same receipt, listed back in stock. custom_values sets the site's custom attributes for the check-out.loans:write
GET/loans/kitsSaved groups of equipment that are usually handed out together.loans:read
POST/loans/kitsSave a kit of at least two parts in all: named item_ids, lines (a number of a category) and child_kit_ids (kits inside it, up to three levels), stock_lines (counted stock handed out with it, never held for a booking), optionally locked so its named items go out only together.loans:write
PUT/loans/kits/{id}Change a saved kit and its items.loans:write
GET/loans/trainingsThe trainings a category or item can require before someone borrows it (set up in Equipment, Policies, Training).loans:read
GET/loans/trainings/{id}/holdersWho holds a training, from when and until when, and whether it has expired.loans:read
POST/loans/trainings/{id}/holdersGive a person on the people list a training, or renew it, with an optional proof document.loans:write
DELETE/loans/trainings/{id}/holders/{person}Take a training away from a person, with its proof document.loans:write
GET/loans/borrower-typesThe borrower types: each one's item limit, usual length and the categories its people see and borrow (set up in Equipment, Policies). An empty limit or length means the site's own applies.loans:read
GET/loans/borrower-types/{id}/membersWho has a borrower type.loans:read
POST/loans/borrower-types/{id}/membersGive people on the people list a borrower type (up to 500 at once).loans:write
PUT/loans/borrower-types/{id}/members/{person}Change a person's membership of a borrower type: its start day, its end day (after it they still see what the type shows but cannot reserve or borrow it) and a note about where a fee was taken. vFound takes no payment.loans:write
DELETE/loans/borrower-types/{id}/members/{person}Take a borrower type away from a person.loans:write
GET/loans/creditsBooking credits given recently, and one person's balance. Credits are a count that bookings spend, never money.loans:read
POST/loans/creditsGive a person booking credits, or take some back with a negative number (owners and managers).loans:write
GET/loans/holdsActive holds on borrowing: while one lasts, nothing goes out to the person and they cannot book.loans:read
POST/loans/holdsPut a hold on a person's borrowing, with an optional reason (kept for the team, never in the email), end time and email to the person.loans:write
POST/loans/holds/{id}/liftLift a hold.loans:write
GET/loans/spacesRooms, desks, parking spaces and other places the site books for a time, optionally filtered by type. Each is an item with kind space, never handed out.loans:read
POST/loans/spacesAdd a room or space with its type, how many people it holds and where it is.loans:write
PUT/loans/spaces/{id}Change a room or space.loans:write
GET/loans/spaces/availabilityEach room or space with its open bookings between from and to (up to 31 days), with the borrower's name, how many people come and any set-up instructions.loans:read
POST/loans/spaces/{id}/bookBook a room or space for a person and time, alone or with equipment (all or nothing), with set-up instructions for the team.loans:write
POST/loans/reservation-groups/{id}/partsAdd one item, or one of a category, to a kit or cart booking, checked as a new booking. Refused for a locked kit. A part of a category the site’s risk form covers needs risk_answers, and the booking’s assessment waits for a new review.loans:write
POST/loans/reservations/{id}/remove-partTake one part out of a kit or cart booking; the last part is cancelled with the booking.loans:write
GET/loans/placesThe site's own nested places: buildings, rooms, shelves, job sites and trucks. An item's place_id sets where it sits and fills its location and sub_location.loans:read
GET/loans/category-treeThe equipment categories grouped into a tree, parents first. Rules and bookings still apply to an item's own category.loans:read
GET/loans/asset-modelsModels new items are made from. Send asset_model_id on POST /loans/items to fill every detail left empty.loans:read
GET/loans/items/{id}/linksThe links of an item to other items of the same site: works with, an alternative, replaces.loans:read
POST/loans/items/{id}/linksLink an item to another of the same site, with a note.loans:write
DELETE/loans/items/{id}/links/{link}Remove a link from both items.loans:write
POST/loans/kits/{id}/moveMove a kit to a place of the site: every named item in it, and in the kits inside it, goes there in one go (owners and managers).loans:write
GET/loans/items/{id}/meter-readingsMeter readings typed in for an item, newest first.loans:read
POST/loans/items/{id}/meter-readingsRecord a meter reading. A service schedule with every_meter is due once the meter has run that far; readings only go up.loans:write
GET/loans/contractsSupplier contracts linked to the items they cover (owners and managers).loans:read
GET/loans/resaleItems listed for sale with their asking price and book value (owners and managers). A list only: nothing is advertised or sold.loans:read
GET/loans/pointsPickup and drop-off points a booking can name.loans:read
POST/loans/pointsAdd a point (owners and managers). A booking names one to collect from and one to return to with pickup_point_id and dropoff_point_id.loans:write
PUT/loans/points/{id}Change a point or switch it off.loans:write
GET/loans/projectsProjects a booking can belong to. Nothing is collected for a project until it is approved.loans:read
POST/loans/projectsAdd a project (waiting for approval).loans:write
POST/loans/projects/{id}/decisionApprove or reject a project (owners and managers).loans:write
GET/loans/risk-assessmentsRisk assessments waiting for a review (or by status), with the borrower's answers.loans:read
POST/loans/risk-assessments/{id}/reviewApprove or reject a risk assessment (owners and managers). A rejection cancels the booking.loans:write
POST/loans/reservation-seriesBook one item, one category or one room or space every day or week (repeat: frequency, every, weekdays, count or until, skip_conflicts). Each time follows the booking rules and counts the times before it; nothing is booked if one is taken unless skip_conflicts is on. At most 52 times, within a year.loans:write
POST/loans/reservations/{id}/moveMove a reservation, with every part of a kit or cart booked together, to new times or another item of the same category. Checked again as a new booking; all or nothing.loans:write
GET/loans/waitlistPeople waiting for a time that was taken, by status (waiting by default).loans:read
POST/loans/waitlistAdd someone to the waiting list for an item, a category or a space and a time. When it frees up, the first person whose time now fits is booked and emailed.loans:write
POST/loans/waitlist/{id}/cancelRemove someone from the waiting list.loans:write
GET/loans/feesThe fees ledger, newest first (filter by party_key, kind, status, billing_code, from, to), with the site's fee settings and everyone who owes something or has a deposit held. Amounts are integers in the currency's minor unit. vFound records fees; it never processes a payment.loans:read
GET/loans/fees/partyOne borrower (person_id or party_key): what they owe per currency, deposits held, entries and invoices.loans:read
GET/loans/fees/billing-codesCharged, waived, settled and still owed per billing code and currency for a period; format=csv for a CSV.loans:read
POST/loans/fees/chargesRecord a damage, replacement or other fee, or a priced fee by fee_template_id. The site's tax applies unless taxable is false.loans:write
POST/loans/fees/paymentsRecord money the site took itself (cash, its own card terminal, a transfer). It settles open charges oldest first.loans:write
POST/loans/fees/depositsRecord a deposit the site took; held until given back or kept.loans:write
POST/loans/fees/deposits/{id}/returnGive a held deposit back.loans:write
POST/loans/fees/deposits/{id}/keepKeep a held deposit or part of it (owners and managers, with a reason); the kept part counts as a payment.loans:write
POST/loans/fees/{id}/waiveWaive what a charge still needs (owners and managers, with a reason).loans:write
POST/loans/fees/{id}/voidVoid a payment recorded by mistake (owners and managers, with a reason). Voiding the payment a kept deposit made holds that amount again as a deposit.loans:write
GET/loans/{id}/feesWhat the desk is offered for a loan that is back: the late fine not yet recorded, the replacement value when lost or damaged, deposits held.loans:read
POST/loans/{id}/late-fineAdd the late fine for a loan that came back late, counted from when it came back. Once per loan.loans:write
GET/loans/invoicesInvoices, newest number first.loans:read
POST/loans/invoicesIssue a numbered invoice for a borrower's open charges in one currency.loans:write
POST/loans/invoices/{id}/voidVoid an invoice (owners and managers, with a reason); reissue puts its open charges on a new one that replaces it.loans:write
GET/loans/reservationsReservations by start time, optionally filtered by status or from.loans:read
POST/loans/reservationsReserve a specific item or one item in a category for a person and time window. custom_values sets the site's custom attributes for the booking.loans:write
POST/loans/reservations/{id}/approveApprove a reservation that is waiting for review. When the site has approval steps, a key signs a step only for the team member it names in X-Acting-User, an assistant connection never signs one, and nobody signs a step of a booking they made (approval_not_yours). Booking over a conflict follows the same rule.loans:write
POST/loans/reservations/{id}/cancelCancel a pending, approved or ready reservation.loans:write
POST/loans/reservations/{id}/pickupAtomically hand over the reserved item and close the reservation as collected.loans:write
POST/loans/reservation-groupsReserve a kit (kit_id) or a cart (items: an item, or a category and quantity, per line) for one person and time window: every part or none. Approving, cancelling or collecting any part acts on every open part.loans:write
GET/loans/downtimesDated windows when one item cannot be booked or handed out that have not ended yet (item_id narrows to one item).loans:read
POST/loans/downtimesAdd a window to an item: loan_item_id, starts_at, ends_at and an optional reason. Refused while a booking or loan holds the item for any of that time.loans:write
DELETE/loans/downtimes/{id}Remove a window.loans:write
GET/loans/extra-values/{type}/{id}The site's custom attributes for a borrower (person), a reservation or a checkout, with the fields defined for that kind of record.loans:read
PUT/loans/extra-values/{type}/{id}Set those attributes, checked against the site's fields and their show-when conditions.loans:write
GET/loans/closuresDays the equipment desk is closed that have not ended yet.loans:read
POST/loans/closuresAdd a closure: starts_on and ends_on dates in the site's time zone, up to 366 days. Optional note stays internal; public_message (up to 300 characters) is shown to borrowers. Existing notes are never copied into the borrower message.loans:write
DELETE/loans/closures/{id}Remove a closure.loans:write
GET/loans/rulesSite defaults, category rules for duration, limits, overdue blocks, approval and booking rules (turnaround buffers, minimum notice, how far ahead), and closures.loans:read
POST/loans/rulesCreate or replace one category rule. Booking rule fields left out keep their saved values.loans:write
GET/loans/timelineWhole-day item/category capacity checks. Required inclusive site-local from and until dates, at most 31 days from today through next year; optional group=item|category, item_id, exact category, page (50 rows). Cells are true, false or null (uncertain). Adjacent days do not guarantee a continuous booking.loans:read
GET/loans/warrantiesRecorded warranty dates; filter=soon|expired|all, exact category, page (50 rows). Soon includes today through 30 days ahead. Personal reminder opt-in is in the workspace.loans:read
GET/loans/utilizationPer-asset elapsed hours from recorded status history. Required inclusive site-local from and until within the last 365 days, capped at now; optional item_id, exact category, format=csv. JSON gives exact seconds; CSV hours use six decimals. Available includes borrowed; repair/service and other unavailable time are excluded. Prior downtime is unknown. Totals reconcile with asset rows.loans:read
GET/loans/maintenanceService, calibration, safety-test, inspection, cleaning, repair and note history; filter by item, upcoming work, or work orders (open or all) and their technician.loans:read
POST/loans/maintenanceRecord maintenance and the next due time for an item. With plan_id, the work done for a repeating schedule, which starts its next round.loans:write
GET/loans/service-plansRepeating service, calibration, safety-test, inspection and cleaning schedules, with whether each is due by date, hours checked out or number of checkouts.loans:read
POST/loans/service-plansAdd a repeating schedule to an item (owners and managers).loans:write
PUT/loans/maintenance/{id}Change or close a work order: status, technician, supplier, cost, and for done its result and whether the item goes back in service.loans:write
GET/loans/maintenance/costsService, repair and cleaning cost per item, from finished entries and done work orders.loans:read
GET/loans/items/{id}/lifecycleAn item's purchase, depreciation, insurance and disposal record, with its value today (owners and managers).loans:read
PUT/loans/items/{id}/lifecycleSave the purchase price, date, supplier and order, the depreciation method (straight line or declining balance), useful life and salvage value, and the insurance (owners and managers).loans:write
POST/loans/items/{id}/disposeRecord how an item left (sold, scrapped, donated, recycled, lost or stolen); it is retired and its open bookings and work orders are cancelled.loans:write
DELETE/loans/items/{id}/disposeUndo a disposal made by mistake; the item is available again.loans:write
GET/loans/valuationThe value of the equipment on a date, to the cent, with totals for what is still held (owners and managers).loans:read
POST/loans/service-plans/importCheck or add schedules from a CSV in the documented columns, naming equipment by asset tag (owners and managers).loans:write
POST/loans/maintenance/work-orders/importCheck or add open work orders from a CSV in the documented columns (owners and managers).loans:write
GET/loans/maintenance/plannerScheduled work and open work orders by the site's own day for up to 62 days, optionally for one technician.loans:read
GET/loans/fundingWhat each fund, grant or cost centre bought and what work was charged to it, filterable by fund and dates (owners and managers). A record only: vFound takes no payment.loans:read
GET/loans/substancesThe hazardous-substances register: substance, place, hazard classes and review dates. A record of what the site says; vFound gives no safety advice.loans:read
POST/loans/substancesAdd a substance, with its safety data sheet as a PDF or photo (owners and managers).loans:write
PUT/loans/substances/{id}Change a substance or replace its data sheet (owners and managers).loans:write
DELETE/loans/substances/{id}Remove a substance and its kept data sheet (owners and managers).loans:write
GET/loans/licencesLicences for the site's equipment with seats, end date and the items they are installed on (owners and managers). No licence key is stored.loans:read
POST/loans/licencesAdd a licence (owners and managers).loans:write
PUT/loans/licences/{id}Change a licence and where it is installed.loans:write
DELETE/loans/licences/{id}Remove a licence.loans:write
GET/loans/expiriesInsurance and licences ending soon or already ended (owners and managers).loans:read
GET/loans/stocktakesRecent equipment stock-takes with scanned and missing counts.loans:read
POST/loans/stocktakesStart one open stock-take for the site, for everything, for one location, category or kit, or for what one person holds (custodian_id), optionally assigned to a team member (assigned_to).loans:write
POST/loans/stocktakes/{id}/scanScan an equipment label, asset tag or serial number into the open stock-take.loans:write
POST/loans/stocktakes/{id}/scan-manyCount up to 2,000 codes at once (a keyboard-type RFID reader or a list); each counts once and unmatched codes come back.loans:write
PUT/loans/stocktakes/{id}/assignGive the open stock-take to one team member to count (assigned_to), or to nobody (null).loans:write
POST/loans/stocktakes/{id}/finishFinish the stock-take and return the missing-item list.loans:write
GET/loans/stocktake-schedulesStock-takes that open by themselves, once or repeating.loans:read
POST/loans/stocktake-schedulesSchedule a stock-take, once, weekly, monthly, every three months or yearly, at the site's own time of day.loans:write
PATCH/loans/stocktake-schedules/{id}Change, pause or resume a schedule.loans:write
DELETE/loans/stocktake-schedules/{id}Delete a schedule; stock-takes it opened stay.loans:write
GET/loans/last-seenWhere each item was last scanned, when the site saves scan positions (team members who agreed only; never from a key).loans:read
GET/loans/transfersIncoming and outgoing equipment transfers for this site.loans:read
POST/loans/transfersPrepare equipment for another authorised site in the same customer group.loans:write
POST/loans/transfers/{id}/sendRecord that prepared equipment left the source site.loans:write
POST/loans/transfers/{id}/receiveReceive equipment at the destination with its location and arrival state.loans:write
POST/loans/transfers/{id}/cancelCancel a prepared transfer before dispatch.loans:write
POST/loans/transfers/{id}/rejectReject a prepared transfer at the destination before dispatch.loans:write
POST/loans/transfers/{id}/exceptionRecord a problem while equipment is in transit.loans:write
POST/loans/importPreview or import up to 5,000 CSV rows using vFound, Snipe-IT, Sortly or Cheqroom headings.loans:write

Visitors

RequestWhat it doesScope
GET/visitorsVisits, newest change first, with status (expected, in, out, cancelled or missed), the visitor, the host, the pass code while it is valid, and the times. Filters: status, search (visitor, company, host or pass code), updated_since.visitors:read
GET/visitors/{id}One visit.visitors:read
POST/visitorsInvite a visitor or sign one in. It accepts the visitor, host and time fields plus visitor_type_id, answers, valid dates and a daily or weekday recurrence.visitors:write
POST/visitors/{id}/sign-inSign an expected visitor in; the host is told. Send answers for a group member whose type has required questions, and id_expires_on with identity_checked when the site records a physical ID's expiry date. The visit then carries id_expires_on and id_expired.visitors:write
POST/visitors/{id}/group/sign-inSign in everyone in the visit's group who is expected today, with one email to the host; anyone who needs their own photo, ID check, signature, answers or terms is listed in skipped.visitors:write
POST/visitors/{id}/sign-outSign them out.visitors:write
POST/visitors/{id}/cancelCancel an invitation.visitors:write
POST/visitors/{id}/send-passEmail the pass again.visitors:write
POST/visitors/{id}/approveApprove a pending visit and send the pass.visitors:write
POST/visitors/{id}/denyDeny a pending visit.visitors:write
GET/visitors/{id}/badgeDownload the browser-printable badge. Choose size 4x3, brother or dymo.visitors:read
GET/visitors/{id}/cardWhether the visit has an RFID card and its last four characters (never the number). Off until the site turns Cards and fobs on.visitors:read
POST/visitors/{id}/cardGive an expected or signed-in visit a card by its number; one number is live on one visit at a time.visitors:write
DELETE/visitors/{id}/cardTake the card back.visitors:write
GET/visitors/{id}/assetsThe things handed to the visit, typed by hand.visitors:read
POST/visitors/{id}/assetsRecord a thing handed to the visit, with an optional tag.visitors:write
POST/visitors/{id}/assets/{asset}/returnMark a thing as returned.visitors:write
GET/visitor-assets/not-returnedThings handed to visitors and not yet returned, newest first.visitors:read
GET/visitors/{id}/fast-trackWhether the visit has a live fast-track code, until when and how often it was used (never the code, which only the visitor sees).visitors:read
POST/visitors/{id}/fast-trackGive a returning visitor a fast-track code that lasts days (1 to 365).visitors:write
DELETE/visitors/{id}/fast-trackTake the code back.visitors:write
GET/visitor-typesList visitor types and their questions, terms, badges, approvals and retention (retention_days is null when the type follows the site default).visitors:read
POST/visitor-typesCreate a visitor type.visitors:write
PATCH/visitor-types/{id}Change the visitor type fields you send.visitors:write
DELETE/visitor-types/{id}Deactivate a visitor type without changing earlier visits.visitors:write
GET/visitor-roll-callGet the latest roll call and its live counts. A running roll call adds anyone who signed in since it started; one left running for 6 hours is closed.visitors:read
POST/visitor-roll-callStart a roll call, optionally including visitors expected today and anyone waiting for approval.visitors:write
PATCH/visitor-roll-call/entries/{entry}Mark one entry safe or missing.visitors:write
POST/visitor-roll-call/{id}/finishFinish the active roll call and keep its report.visitors:write
GET/staff-attendanceList staff attendance for a date range on the site's clock (today by default, at most 366 days), or only people signed in now with open=true. Never includes the person's email.visitors:read
POST/staff-attendanceSign a person on the staff list in (mode office or remote) or out, with the same rules as the desk. Needs staff sign-in turned on at the site.visitors:write
POST/staff-presenceSend up to 50 presence events (in, out or muster) from your badge, time clock or Wi-Fi system, each naming a person on the staff list by reference, external ID or email. Needs staff sign-in and the presence feed turned on at the site. Answers what happened per event, never who.visitors:write
POST/visitors/{id}/cateringMake, change or (with no items) remove the catering request of an expected or signed in visit, from the options the site lists. Sends one email to the site's catering inbox; vFound orders nothing and takes no payment. Needs catering turned on at the site.visitors:write
GET/workplace/spacesList the desks, meeting rooms and parking spaces people may book at the site.visitors:read
GET/workplace/freeFind spaces free for a whole time (at most 7 days), leaving out a desk kept for another person.visitors:read
GET/workplace/bookingsList desk, room and parking bookings in a time range of at most 31 days. Never includes the person's email.visitors:read
POST/workplace/bookingsBook a space for a person, once or as a repeating booking (daily or weekly, up to 52 times, all or none), by Equipment's reservation rules.visitors:write
POST/workplace/bookings/{id}/cancelCancel a booking, or with scope following or series its later times.visitors:write
POST/workplace/bookings/{id}/check-inCheck a booking in, from 15 minutes before it starts until it ends.visitors:write
POST/visitors/{id}/roomBook a meeting room for a visit, from the visit's time; the room follows the visit.visitors:write
GET/appointment-pagesList the site's appointment pages, their hours and whether each is open to visitors now.visitors:read
GET/visitor-roll-call/archiveList ended roll calls (emergencies, drills and notices), newest first.visitors:read
GET/visitor-roll-call/{id}One roll call with its people, timeline, sweeps and message counts.visitors:read
POST/visitor-roll-call/{id}/peopleAdd a person (an employee, other or contractor) to the running roll call.visitors:write
POST/visitor-roll-call/{id}/scanMark a visitor safe from their pass link or code, at a muster point.visitors:write
POST/visitor-roll-call/{id}/sweepsRecord a zone as swept clear or as having people in it.visitors:write
POST/visitor-roll-call/{id}/messagesSend a message to everyone, to people not yet safe or to people who need help. It goes by email, browser alert and, on the site's own provider, SMS or WhatsApp, with a private link to answer safe or need help.visitors:write
GET/visitor-roll-call/{id}/people/{entry}/messagesThe conversation with one person on a roll call: what the team sent them and what they wrote back from their private link, oldest first. Write back with the message endpoint and audience entry.visitors:read
POST/visitor-hazard-alertsA warning a team member writes and sends to a chosen group: hazard, message and group (on_site, visitor_type, host or tenant, with group_ref). It starts a roll call of the kind hazard for that group. vFound reads no weather, news or threat feed: nothing is sent unless you send this request. Answers 409 while another roll call is running.visitors:write
POST/visitor-help-alertsAsk for help quietly: the team members chosen for it are told; no visitor sees anything.visitors:write
GET/visitor-kiosksList paired, pending and revoked kiosk devices.visitors:read
POST/visitor-kiosks/pairingCreate an eight-character pairing code that lasts ten minutes.visitors:write
DELETE/visitor-kiosks/{id}Revoke a kiosk device.visitors:write
PUT/visitor-kiosks/{id}/settingsChange one kiosk’s settings: an email when it has not been seen for a number of minutes, return to the start after a quiet time, a signature at sign-in, and printing the badge from the tablet. Everything starts off.visitors:write
GET/visitor-analyticsTotals by day, hour, type and host, plus average stay for the last year.visitors:read
GET/visitor-registrationGet the site's self-registration link and whether it is enabled.visitors:read
GET/school/movementsPupils’ late arrivals and early leaves, oldest first, from since (default the last 24 hours), with each pupil’s reference for the school information system. A view only team member named in X-Acting-User cannot use it.school:read
PUT/school/pupilsAdd or update up to 500 pupils by reference; send active false for a pupil who left. Nothing is deleted here.school:write

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.

RequestWhat it doesScope
GET/peopleThe list, by name. Filters: search (name, email, unit or reference), updated_since.people:read
GET/people/{id}One person.people:read
POST/peopleAdd someone: name (required), email, unit, reference and language for their emails.people:write
POST/people/upsertAdd or update up to 500 people in one call: people is a list of the same fields. Someone whose email is already on the list is updated. Answers how many were added, updated and skipped.people:write
PATCH/people/{id}Change only the fields you send.people:write
DELETE/people/{id}Remove someone. Their parcels, visits and loans keep the name they had.people:write
GET/people/exportDownload the complete people list as a formula-safe CSV.people:read
POST/people/{id}/send-my-vfoundEmail one active person the signed page for their linked parcels, visitors and equipment.people:write
GET/people/sync-sourceShow the saved CSV directory and the latest sync result.people:read
PUT/people/sync-sourceSave a public HTTPS CSV url and mode (upsert or mirror).people:write
DELETE/people/sync-sourceRemove the connection and keep the people already imported.people:write
POST/people/sync-source/runRun the saved connection now.people:write

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.

Equipment training rosters can come from the same directory: link a training to a directory group by its name (Equipment, Policies, Training), then assign that group to the vFound application. https://vfound.io/api/scim/v2/Groups answers only for groups a training names, and refuses any other group. Its members are the people (by their SCIM user id) who hold the training; a person leaving the group loses the training only when the directory gave it, so a record staff added stays. A record the directory gave that has expired is renewed from that day when the directory sends the group again with the person still in it. Groups answer only for a site with Equipment. Because group membership gives a training, and a training lets people take out the equipment that requires it, a key with people:write can grant trainings this way: keep that key for your identity provider.

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.

EventWhenData
item.createdA found item is addedItem
item.updatedIts status, title, location, category, keep until date or photo visibility changesItem
item.transfer_sentA found item is sent to another site of the group (both sites receive it)Item transfer
item.transfer_cancelledThe sending site takes it back before it arrivesItem transfer
item.transfer_receivedThe receiving site confirms it arrivedItem transfer
claim.createdA guest submits a claimClaim
item.disposition_recordedAn item is donated or disposed ofItem
item.match_updatedA stored AI match verdict changes; report_id, item_id, label and reasonMatch pair
lost_report.match_updatedA stored AI match verdict changes; report_id, item_id, label and reasonMatch pair
claim.ownership_reviewedA manager records an ownership review; fetch custody for the review historyClaim
claim.decision_recordedA claim is accepted or rejectedClaim
claim.release_approvedA different manager approves releaseClaim
claim.handover_recordedPhysical pickup closes a ready-for-pickup claimClaim
claim.status_changedA claim moves to a new statusClaim
lost_report.updated, lost_report.closed, lost_report.contact_updated, lost_report.createdA guest reports a lossLost report
parcel.loggedA parcel is logged at the desk or through the APIParcel
parcel.updatedAny of its details change at the desk, such as its recipient, tracking number or shelfParcel
parcel.remindedThe recipient is sent a reminder, by the desk or automaticallyParcel
parcel.collectedA parcel is handed overParcel
parcel.returnedA parcel is returned to the senderParcel
parcel.recipient_arrivedA recipient says they are at the deskPickup queue entry
parcel.reminders_snoozedA recipient pauses their remindersPerson and parcel count
parcel.heldA recipient sets a hold datePerson, date and parcel count
parcel.proxy_createdA recipient emails a delegate a collection codePerson, delegate and expiry
parcel.pickup_servedThe desk marks an arrival servedPickup queue entry
parcel.escalatedA waiting parcel reaches the site's escalation ageParcel
parcel.outgoing_loggedAn outgoing parcel is loggedOutgoing parcel
parcel.outgoing_handed_overAn outgoing parcel is handed to a courierOutgoing handoff
parcel.round_createdA delivery round is createdRound summary
parcel.round_deliveredA delivery round stop is completedRound, stop and parcel ids
checkroom.checked_inSomething is checked in and given a numberTicket
checkroom.handed_backIt is handed backTicket
checkroom.leftThe night is closed with it still at the checkroomTicket
checkroom.self_checkin_startedA guest starts a ticket from a paired kioskTicket
checkroom.ready_requestedA guest asks the desk to get their things readyTicket
checkroom.readyThe desk marks a guest's things readyTicket
checkroom.station_createdA checkroom station is createdStation
checkroom.station_updatedA checkroom station changesStation
checkroom.event_createdA checkroom event is createdEvent
checkroom.event_updatedA checkroom event changesEvent
loan.checked_outAn item is handed outLoan
loan.due_soonIts due time is less than two hours away, once per due timeLoan
loan.overdueIts due time passes and it is not back, once per due timeLoan
loan.extendedIts due time changesLoan
loan.returnedIt comes back to the deskLoan
loan.lostIt is recorded as not coming backLoan
loan.checkout_createdOne atomic multi-item checkout is createdCheckout, with any stock on the same receipt in stock
loan.self_checkoutA borrower completes kiosk checkoutCheckout
loan.kit_createdA saved equipment kit is createdKit
loan.kit_updatedA saved equipment kit changesKit
loan.reservation_requestedA reservation waits for approvalReservation
loan.reservation_createdA reservation is confirmed immediatelyReservation
loan.reservation_approvedA pending reservation is approvedReservation
loan.reservation_readyReserved equipment is ready for collectionReservation
loan.reservation_cancelledA reservation is cancelledReservation
loan.reservation_collectedReserved equipment is handed overCheckout
loan.extension_requestedA borrower asks for more timeLoan
loan.problem_reportedA borrower reports an equipment problemLoan
loan.rule_updatedA category checkout rule changesRule
loan.maintenance_loggedMaintenance is recordedMaintenance
loan.maintenance_dueScheduled maintenance becomes dueMaintenance
loan.service_dueA repeating service schedule becomes due (by date, hours checked out or number of checkouts), once per roundMaintenance
loan.work_order_openedA work order is opened, by staff or by a return the site asks to open one forMaintenance
loan.work_order_closedA work order is done or cancelledMaintenance
loan.item_disposedAn item is disposed of (sold, scrapped, donated, recycled, lost or stolen)Equipment
loan.stocktake_startedAn equipment stock-take startsStock-take
loan.stocktake_completedAn equipment stock-take finishesStock-take
loan.transfer_preparedAn authorised site prepares equipment to moveTransfer
loan.transfer_sentPrepared equipment leaves its source siteTransfer
loan.transfer_receivedThe destination receives the equipmentTransfer
loan.transfer_rejectedThe destination rejects a prepared transferTransfer
loan.transfer_cancelledThe source cancels a prepared transferTransfer
loan.transfer_exceptionAn in-transit transfer needs attentionTransfer
loan.transfer_lostThe source closes a transfer that never arrivedTransfer
loan.charge_recordedA fine, damage, replacement, usage or other charge is recordedFees entry
loan.charge_waivedA manager waives what a charge still needs, with a reasonFees entry
loan.payment_recordedStaff record money the site took itself (vFound never processes a payment)Fees entry
loan.payment_voidedA manager voids a payment recorded by mistakeFees entry
loan.deposit_recordedStaff record a deposit the site tookFees entry
loan.deposit_resolvedA held deposit is given back or keptFees entry
loan.invoice_issuedAn invoice is issued for a borrower's chargesInvoice
loan.invoice_voidedA manager voids an invoice, with a reasonInvoice
loan.quote_acceptedThe team accepts a quote and its bookings are madeQuote
loan.payment_request_createdThe team records a payment request (nothing is sent to the person)Payment request
loan.payment_request_paidPayments recorded against a request cover it in fullPayment request
loan.delivery_doneA delivery or a collection is marked doneDelivery
loan.items_importedAn equipment CSV import completesCounts
visit.expectedA visitor is invitedVisit
visit.signed_inA visitor signs in, at the desk or from your QR signVisit
visit.host_confirmedThe desk confirms who a self signed in visitor came to seeVisit
visit.signed_outThey sign out, at the desk, from their pass or automatically after the day endsVisit
visit.cancelledAn invitation is cancelledVisit
visit.approval_requestedA visit waits for staff approvalVisit
visit.approvedA pending visit is approvedVisit
visit.deniedA pending visit is deniedVisit
visit.host_repliedA host replies from their private linkVisit
visit.roll_call_startedA live roll call (an emergency, a drill or a notice) startsRoll call summary
visit.roll_call_completedA live roll call finishesRoll call summary
visitor_type.createdA visitor type is createdVisitor type
visitor_type.updatedA visitor type changesVisitor type
visitor_type.deactivatedA visitor type is deactivatedVisitor type
visitor_agreement.signedA visitor signed an agreement document, with a link to the signed copy that works for seven daysAgreement signature
kiosk.pairedA visitor kiosk is pairedKiosk
kiosk.revokedA visitor kiosk is revokedKiosk
courier.signed_inA delivery visitor is logged in ParcelsCourier
courier.signed_outA delivery visitor leavesCourier
staff.signed_inA person on the staff list signs in, in the office or remoteStaff attendance
staff.signed_outA person on the staff list signs out, or is signed out automaticallyStaff attendance
person.createdA person is addedPerson
person.updatedA person is changedPerson
person.deactivatedDirectory provisioning deactivates a personPerson
person.deletedA person is removedPerson
people.sync.completedA connected CSV sync completesCounts
people.sync.failedA connected CSV sync fails safelyError
report.deliveredA scheduled report from Reports & Analytics, shared with the site, runs with delivery to webhooks chosen (a private report is never sent to webhooks); subscribe to it in Settings, For developers (an API key cannot subscribe to it)Every column the report names and up to 5,000 rows, or every group
queue.ticket_joinedA person joins a line, from their phone, a kiosk, the desk or the APIQueue ticket
queue.ticket_calledA person is called to a counter, or called againQueue ticket
queue.ticket_servedA person is marked servedQueue ticket
queue.ticket_no_showA called person is marked a no-show, by the team or after the line's minutesQueue ticket
queue.ticket_leftA person leaves the line from their ticket, or the team takes them outQueue ticket
queue.ticket_transferredA person is moved to another line or counterQueue ticket
queue.ticket_closedA ticket still open at the end of the site's day, or in an archived line, is closedQueue ticket
queue.booking_createdA person books a time on a line's booked-times page, or the API books oneQueue booking
queue.booking_cancelledA booked time is cancelled by the person, the team or the APIQueue booking
queue.ticket_arrivedA person who joined before arriving says they are here, or the team marks them arrivedQueue ticket
queue.message_receivedA person in line writes to the team from their ticket page; the event carries no wordsQueue message
queue.message_sentThe team writes to a person in line; the event carries no wordsQueue message
queue.survey_answeredA served person answers the survey; the event carries the rating and never the commentQueue survey answer
{"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.

RequestWhat it doesScope
GET/webhooksThe addresses this key created, and their events.webhooks:manage
POST/webhooksAdd an address: url (public HTTPS on port 443) and events, a list of the events above that the key can read.webhooks:manage
DELETE/webhooks/{id}Remove an address this key created, and its delivery history.webhooks:manage

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 site owner gets an email.

Report data feed (Power BI)

An owner or manager makes a feed link in Reports & Analytics, under Power BI data feed, for the products they choose. The link is shown once. In Power BI choose Get data, then Web, and paste it. Each link reads one site only, and stops at once when it is revoked, when the person who made it is no longer an owner or manager of the site, or when the site is paused or closed.

GET /api/feeds/reports/{token}/{dataset} answers the rows of one dataset: equipment_loans, equipment_activity, visits or checkroom_tickets. Choose its period with days (1 to 366, 90 when left out) or from and to (YYYY-MM-DD, on the site's clock). GET /api/feeds/reports/{token}/saved/{id} answers a saved report that is shared with the whole site, for that report's own period; days, from and to do not change it. You can also send the token as Authorization: Bearer <token> to /api/feeds/reports/{dataset} or /api/feeds/reports/saved/{id}. One answer holds up to 100,000 rows in value, so Get data, Web reads the whole result; then turn the value list into a table. The answer ends with total and truncated: when more rows match than one answer holds, truncated is true and @odata.nextLink names the rest ($top and $skip page through them, for tools that follow it); Get data, Web does not follow it, so choose a shorter period instead. When the rows of a report would need more than 400,000 rows read or more than 20 seconds, the answer ends with error, total null and truncated true; a grouped saved report answers 422 with the reason instead. Rows come in the order they were recorded. Times in rows are UTC (ISO 8601); a saved report grouped by a date labels each group by the day, week, month, weekday or hour on the site's clock. Email addresses and a checkroom guest's name and room are left out unless the link was made to include contact details.

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 site has open. A client connected with an API key may also send X-Acting-User; each tool then runs as that team member, within their role.

# 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_…"}}}}
ToolWhat it doesScope
search_found_itemsSearch found items by words such as “black iPhone”items:read
list_expected_visitorsVisitors invited and not here yetvisitors:read
list_visitors_on_siteVisitors signed in nowvisitors:read
list_visitor_typesVisitor types and their rulesvisitors:read
visitor_analyticsVisitor totals, patterns and average stayvisitors:read
visitor_registration_linkThe site's self-registration linkvisitors:read
list_couriers_on_siteCouriers signed in through Visitorsparcels:read
list_waiting_parcelsParcels waiting to be collectedparcels:read
detect_parcel_trackingNormalise a tracking number and detect its carrierparcels:read
parcel_pickup_queuePeople waiting at the parcel deskparcels:read
parcel_shelvesParcel shelf capacity and occupancyparcels:read
parcel_analyticsParcel volume, carriers and collection performanceparcels:read
list_outgoing_parcelsOutgoing parcels and their handoff stateparcels:read
list_parcel_roundsParcel delivery rounds and stopsparcels:read
list_checkroom_exit_queueTickets whose guests are waiting at the exitcheckroom:read
mark_checkroom_readyMark a waiting ticket ready and notify the guestcheckroom:write
list_checkroom_stationsCheckroom stations and number rangescheckroom:read
list_checkroom_eventsRecent and upcoming checkroom eventscheckroom:read
checkroom_reportCheckroom volume, return time and fee totalscheckroom:read
list_queue_linesLines, people waiting and the estimated wait nowqueue:read
list_queue_waitingPeople waiting today, in calling orderqueue:read
queue_reportQueue totals and median wait and service minutesqueue:read
call_next_in_queueCall the next person to a counterqueue:write
mark_queue_ticket_servedMark the person at a counter servedqueue:write
list_overdue_equipmentEquipment past its due time, and who has itloans:read
list_equipment_kitsSaved groups of equipmentloans:read
create_equipment_kitSave a reusable equipment kit without handing it overloans:write
list_equipment_reservationsReservations by time and statusloans:read
reserve_equipmentReserve an item or category without handing it overloans:write
book_repeating_reservationBook an item, category or space every day or weekloans:write
move_reservationMove a reservation to new times or another item of its categoryloans:write
list_waitlistThe people waiting for a time that was takenloans:read
join_waitlistAdd someone to the waiting listloans:write
list_space_bookingsEach room, desk or parking space and its bookings between two timesloans:read
book_spaceBook a room or space for a person and time; it is never handed outloans:write
list_equipment_rulesSite and category checkout rulesloans:read
save_equipment_ruleCreate or replace a category ruleloans:write
list_equipment_maintenanceEquipment maintenance history and upcoming workloans:read
list_equipment_service_plansRepeating service, calibration, safety-test, inspection and cleaning schedules and which are dueloans:read
update_equipment_work_orderChange or close an equipment work orderloans:write
get_equipment_maintenance_costsService, repair and cleaning cost per itemloans:read
get_equipment_valuationThe value of the equipment on a date after depreciation (owners and managers)loans:read
list_equipment_substancesThe hazardous-substances register: substance, place, hazard classes and review dates (a record, no safety advice)loans:read
get_equipment_fundingWhat each fund, grant or cost centre bought and what work was charged to it (owners and managers)loans:read
get_equipment_plannerScheduled work and open work orders by the site's own dayloans:read
list_equipment_licencesLicences for the equipment with seats and end dates (owners and managers)loans:read
get_equipment_expiriesInsurance and licences ending soon or already ended (owners and managers)loans:read
log_equipment_maintenanceRecord service, calibration, a safety test, an inspection, cleaning, a repair or a noteloans:write
list_equipment_stocktakesRecent stock-takes and their countsloans:read
start_equipment_stocktakeStart a stock-takeloans:write
scan_equipment_stocktakeRecord one item in an open stock-takeloans:write
scan_many_equipment_stocktakeCount many codes in an open stock-take at onceloans:write
finish_equipment_stocktakeFinish a stock-take and return what is missingloans:write
list_equipment_transfersIncoming and outgoing transfers without borrower detailsloans:read
preview_equipment_importValidate an equipment CSV without saving itloans:write
find_personLook someone up on the people listpeople:read
export_peopleExport the people list as formula-safe CSVpeople:read
directory_sync_statusCheck the saved CSV connection and its latest runpeople:read
run_directory_syncRun the saved CSV connection nowpeople:write
email_my_vfoundEmail one person their signed private pagepeople:write
invite_visitorInvite a visitor, who gets a pass by emailvisitors:write
approve_visitApprove a pending visit requestvisitors:write
list_free_workplace_spacesFind free desks, meeting rooms or parking for a timevisitors:read
book_workplace_spaceBook a desk, meeting room or parking space for a personvisitors:write
request_visit_cateringAsk for catering with a visit, from the options the site listsvisitors:write
list_appointment_pagesList the site's appointment pages and whether each is open to visitorsvisitors:read
list_staff_on_siteList people on the staff list signed in now, in the office or remotevisitors:read
sign_staff_in_or_outSign a person on the staff list in or outvisitors:write
list_visitor_assets_not_returnedList things handed to visitors that are not marked back yetvisitors:read
issue_visitor_assetRecord a thing handed to an expected or signed-in visitvisitors:write
return_visitor_assetMark a thing handed to a visit as returnedvisitors:write
start_roll_callStart or return the active roll callvisitors:write
mark_visitor_safeMark one visitor safevisitors:write
create_kiosk_pairingCreate a ten-minute kiosk pairing codevisitors:write
log_parcelLog a parcel and email the recipientparcels:write
remind_parcelRemind a recipient to collect a parcelparcels:write
remind_parcelsRemind up to 200 selected parcel recipientsparcels:write
log_outgoing_parcelAdd an outgoing parcel to the courier logparcels:write
create_parcel_roundCreate a delivery round from waiting parcelsparcels:write
extend_loanGive a borrower more timeloans:write

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 site 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 site’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 site or the site 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; an app that needs the REST API connects as the next section says.

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).

Sign in with vFound for other apps

An app that is not an AI assistant, such as a stock, booking or HR system, can connect to the REST API the same way instead of with an API key: send resource=https://vfound.io/api/v1 to /oauth/authorize and /oauth/token, with scopes in the API key names, except webhooks:manage, which an app cannot be given. An owner or manager signs in, sees the app's name and what it may do in plain words, can untick anything and allows it. The connection acts as that person with the same checks as an API key: it stops working if they no longer manage the site or the site is not active, it changes nothing while the subscription is paused, and it may make 120 requests a minute, like a key. X-Acting-User works only with an API key. Its access token works only on the REST API, never on the MCP endpoint, and a consent shown for one never approves the other. It is listed in Settings, For developers as an app using the vFound API, where Disconnect stops it at once. Discovery: /.well-known/oauth-protected-resource/api/v1; the rest is the flow above.

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 site, a team member in X-Acting-User who is not an active member or whose role does not allow the scope, a site that is not active, or a change sent while the subscription is paused, 404 not found in your site, 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:

CodeWhat it means
parcel_not_waitingThe parcel is no longer waiting: it was already collected, returned or delivered.
tracking_duplicateA parcel with this tracking number is already waiting here.
no_emailThe person or visitor has no email address, so nothing can be sent.
capacity_fullEvery checkroom number is in use.
already_checked_inThe checkroom ticket is already checked in.
already_handed_backThe checkroom ticket was already handed back.
nothing_to_hand_backThe checkroom ticket has nothing to hand back.
number_in_useThat checkroom number is already in use.
ticket_closedOnly an open checkroom ticket can be emailed.
item_outThe equipment is out with someone. Take it back first.
item_in_repairThe equipment is set aside for repair.
item_retiredThe equipment is retired, so it cannot be handed out or reserved.
reservation_conflictSomeone has reserved the item, or the last free one in its category, during this time, or it is expected to still be out.
already_backThe equipment was already taken back.
not_outThe equipment is not out, so it cannot get more time, a reminder or be marked as not coming back.
borrower_overdueThe borrower has overdue equipment, and the site or the category allows nothing more until it comes back.
borrower_item_limitThis would give the borrower more items than the site or the category allows at once.
reservation_not_readyThe reservation is not approved yet, or it was already collected or cancelled.
reservation_item_mismatchThe checkout does not include the item the reservation is for.
reservation_category_mismatchThe checkout includes an item outside the reserved category.
reservation_borrower_mismatchThe reservation belongs to a different borrower.
reservation_too_longThe reservation is longer than the category can be borrowed. Only reservations made from My vFound are limited this way.
reservation_daily_limitThe borrower already made 5 reservations from My vFound in the last 24 hours.
booking_noticeThe reservation starts sooner than the category's minimum notice allows.
booking_too_far_aheadThe booking, checkout or new due time ends later than the category can be booked ahead.
desk_closedThe reservation would start on a day the equipment desk is closed.
kit_unavailablePart of a kit or cart is not available for this time, so nothing was reserved. The unavailable field lists each part and why.
borrower_not_in_groupThe site lets only people with a borrower type borrow or book, and this borrower is in none (or was typed rather than chosen from the people list).
category_not_allowedNone of the borrower's borrower types allows this category.
borrower_on_holdBorrowing is paused for this person: staff placed a hold, the site pauses borrowing after repeated late returns, or they owe at least the amount the site blocks at (kind charges). The hold field gives its kind and until when.
space_too_smallMore people than the room or space holds (its capacity).
kit_lockedThe equipment belongs to a locked kit, which goes out only as a whole: include every named item of the kit.
approval_not_yoursThe site set approvers in order and this person is not the next one (or the site lets nobody skip a step for them).
project_not_approvedThe booking belongs to a project that is not approved yet, so nothing can be collected.
not_enough_creditsThe site uses booking credits and this person has none left. Give them some first. A booking that is cancelled or never collected gives its credit back.
risk_assessment_pendingThe booking has a risk assessment that has not been approved, so nothing can be collected.
series_unavailableA repeating booking could not be made because at least one of its times is taken or against a booking rule, so nothing was reserved. The skipped field lists each time and why.
time_availableThe time someone asked to wait for is free, so book it instead of joining the waiting list.
space_not_handed_outA room or space is booked for its time and never handed out, so it cannot be checked out or collected.
stock_shortThere is not enough of this stock item in the place (and batch) named, so nothing changed. The available field gives the quantity there.
stock_issue_closedEverything from this stock hand-out is already back or written off.
order_closedA purchase order is finished or cancelled and cannot change.
order_over_receivedMore was entered than a purchase order line still expects.
order_not_placedStock cannot be received against a purchase order that is still a draft.
fees_offFees are off for this site. Turn them on in the desk and borrowing policy first.
entry_closedThat fees entry or invoice can no longer change this way: the charge is settled or waived, the payment is voided, the deposit was given back or kept, or the invoice is void.
on_invoiceThe charge is on an issued invoice. Void the invoice first, then waive the charge.
not_lateThe loan did not come back late under the site's late fine rules, or it is still out.
nothing_to_invoiceThe borrower has no open charge in that currency that is not already on an issued invoice.
charge_unavailableOne of the chosen charges is not open, is on another invoice or is for someone else.
desk_keptThe desk is kept for another person on one of the days asked for.
desk_has_bookingsKeeping the desk for this person would clash with open bookings by others on those days. Cancel those first.
booking_closedThe desk, room or parking booking was cancelled or released, so it cannot be checked in.
check_in_closedCheck-in opens 15 minutes before a booking starts and closes when it ends.
item_service_dueThe site keeps equipment that needs work from going out, and this item's service date has come or one of its schedules is due. Record the work first.
item_failed_inspectionThe site keeps equipment that needs work from going out, and the last check of this item failed. Record a pass first.
work_order_closedThis work order is already closed and cannot be changed.
already_disposedThis item has already been disposed of.
not_disposedThis item has not been disposed of, so there is nothing to undo.
item_disposedThis item was disposed of. Undo the disposal before using it again.
training_requiredA category rule or the item requires a training the borrower does not hold, or holds only past its expiry date. The training field names what is missing.
stocktake_openA stock-take is already open. Finish it first.
item_unavailableThe equipment is not available or set aside for repair, so it cannot start a transfer.
transfer_openThe equipment already has an open transfer.
transfer_not_readyOnly a prepared transfer can be sent.
transfer_not_in_transitOnly equipment in transit can be received or marked with a problem.
transfer_already_sentA sent transfer can no longer be cancelled or rejected.
already_signed_inThe visitor is already signed in.
visit_closedThe visit is closed. Sign the visitor in as a new visit.
not_signed_inThe visitor is not signed in.
not_expectedOnly an expected visit can be cancelled or sent a pass.
approval_requiredThe visit needs approval before the visitor can sign in.
visit_not_valid_todayThe pass cannot be used again today, or today is outside its dates.
plus_one_not_allowedThe pass does not allow guests, or it is no longer approved, expected or valid.
plus_one_limitThe visitor has added every guest the pass allows.
nobody_to_sign_inNobody in the visit's group is expected today.
visitor_capacity_fullSigning the visitor in would pass the site's or the visitor type's limit of visitors signed in at once.

Signing a visitor in at the desk answers 409 with a code when the visitor needs a team member's check first. The answer names only the kind of match (blocklist, building, restricted_party or answers); the entry, its name and its reason are for the site's team and are never in an API answer. Send the request again with screening_reviewed set to true only once a team member checked the match. That needs a key with the visitors:screening scope (off by default, as is any other key's access to it), and a key that names a team member in X-Acting-User needs one whose role decides on visits. The confirmation is recorded as the key's, by its name, never as the team member who created the key. Without the scope the answer is 403 with screening_scope. The same applies to approving a visit that a match holds:

CodeWhat it means
screening_matchThe visitor matches one of the site's blocklists, a team check or the screening list. A team member must confirm they checked the match before signing the visitor in.
screening_scopeThe request confirms or approves a screening match, and the key does not have the visitors:screening scope (or the team member named in X-Acting-User does not decide on visits).

Workflow checklists

A site on vFound Enterprise can set the steps its staff confirm at a key moment: logging, handing over, donating or disposing of a found item; handing over or returning a parcel; checking in or handing back at the checkroom; checking equipment out or taking it back; and signing a visitor in or out. While one applies, these requests take a checklist field: [{"key": "id_checked", "done": true}, {"key": "reason", "note": "Refused"}], or an object of key to true or note text. POST /items, PATCH /items/{id}, POST /items/{id}/disposition, POST /claims/{id}/handover, POST /claims/{id}/decision, POST /parcels/{id}/collect, POST /parcels/{id}/return, POST /parcels/bulk-return, POST /parcels/rounds/{round}/stops/{stop}/deliver, POST /checkroom/tickets, POST /checkroom/tickets/{id}/hand-back, POST /loans, POST /loans/{id}/return, POST /loans/returns, POST /loans/checkouts, POST /loans/reservations/{id}/pickup, POST /visitors, POST /visitors/{id}/sign-in and POST /visitors/{id}/sign-out accept it. Without the required steps the answer is 422 with the code checklist_incomplete and a checklist object naming the steps still to confirm, and nothing changes. When no checklist applies the field is ignored. The completed checklists, with who confirmed them and when, are in checklists on the single item, claim, parcel, ticket, loan and visit answers.

CodeWhat it means
checklist_incomplete422: a workflow checklist applies to this step and its required steps are not confirmed.

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

CodeWhat it means
idempotency_key_invalid400: the header is not 1 to 191 visible ASCII characters.
idempotency_key_reused422: this key was already used for a different request.
idempotency_in_progress409: the first request with this key is still running. Try again shortly.
offline_in_progressThe first copy of this offline action is still being saved. The device sends it again shortly.

A request that names a team member in X-Acting-User can also answer with a code:

CodeWhat it means
acting_user_refused403: the header does not name exactly one active team member of this site, or the key is a connection made by signing in.
acting_user_role403: the named team member cannot use this operation’s scope with their role at the site.
Questions or a use case we should support? Email us. We read every message.