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_…"
| Scope | Allows | Endpoints |
|---|---|---|
items:read | Read found items, categories and moves between sites | GET /items, /items/{id}, /categories, /item-transfers |
items:write | Add and update found items, and send or receive them between sites | POST /items, PATCH /items/{id}, POST /item-transfers and its cancel and receive |
claims:write | Record human ownership reviews, decisions, release approval and pickup | POST /claims/{id}/verification, /claims/{id}/decision, /claims/{id}/release-approval, /claims/{id}/handover |
lost_reports:write | Create guest reports for a contact centre | POST /lost-reports |
claims:read | Read claims, with the claimant’s contact details | GET /claims, /claims/{id} |
lost_reports:read | Read guests’ lost reports | GET /lost-reports |
analytics:read | Read the analytics summary | GET /analytics |
parcels:read | Read parcels, with each recipient’s name and email | GET /parcels, /parcels/{id} |
parcels:write | Log, hand over, return and remind | POST /parcels and its actions |
checkroom:read | Read tickets, stations, events, the exit queue and reports | GET under /checkroom |
checkroom:write | Check in, hand back, mark ready and manage stations or events | POST and PUT under /checkroom |
loans:read | Read equipment and who has it | GET /loans, /loans/items and one of each |
loans:write | Add equipment, hand it out, extend and take back | POST and PATCH under /loans |
visitors:read | Read visits | GET /visitors, /visitors/{id} |
visitors:write | Invite, sign in and out, cancel, send a pass | POST /visitors and its actions |
visitors:screening | Confirm 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 name | POST /visitors, /visitors/{id}/sign-in, /visitors/{id}/approve |
people:read | Read the people list | GET /people, /people/{id} |
people:write | Add, update, sync and remove people | POST, PATCH and DELETE under /people |
stays:read | Read private hotel stay context and its correction history | GET /stays, /stays/{stay} |
stays:write | Idempotently add or update stay context from a hotel system | POST /stays |
school:read | Read pupils’ late arrivals and early leaves from the school office | GET /school/movements |
school:write | Add or update pupils from the school information system | PUT /school/pupils |
queue:read | Read queue lines, tickets, booked times, messages, survey figures and the queue report | GET under /queue |
queue:write | Add people to a line, call them, finish their tickets, book and cancel times and write to people in line | POST under /queue |
webhooks:manage | Subscribe and unsubscribe the key’s own webhook addresses, for events whose data the key can read | GET, 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.
| System | What vFound reads | vFound areas |
|---|---|---|
| Cloudbeds | Minimal 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 Flex | Member 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 ID | User 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.
Items
| Request | What it does | Scope |
|---|---|---|
| GET/items | Items, 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/categories | The category names an item can use. | items:read |
| POST/items | Add 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-transfers | Found 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-transfers | Send 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}/cancel | The sending site takes the item back before it is received. | items:write |
| POST/item-transfers/{id}/receive | The 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 path | What it does | Scope |
|---|---|---|
| GET /lost-found/context-schema | Read versioned private context field definitions, without record values. Either listed read scope is sufficient. | items:read or lost_reports:read |
| GET /lost-found/desk-settings | Read optional desk settings. | lost_reports:read |
| PUT /lost-found/desk-settings | Replace desk settings; owner or manager only. New mail settings default off. | lost_reports:write |
| GET /checkroom/desk-settings | Read optional desk settings. | checkroom:read |
| PUT /checkroom/desk-settings | Replace desk settings; owner or manager only. New mail settings default off. | checkroom:write |
| GET /lost-found/counts | List the latest 30 scan-count sessions. | items:read |
| POST /lost-found/counts | Snapshot 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}/scan | Record a QR or short item-label scan; duplicate known items count once. | items:write |
| POST /lost-found/counts/{id}/finish | Finish a count without changing items. | items:write |
| GET /lost-found/queues | List 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/queues | Save 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-review | Return deterministic completeness and privacy prompts; no AI or mutations. | items:read |
| GET /checkroom/templates | List 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/templates | Save an event’s station configuration without guests or tickets; manager only. | checkroom:write |
| POST /checkroom/templates/{id}/apply | Create 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 path | What it does | Scope |
|---|---|---|
| POST /lost-reports | Contact-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}/matches | Up 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}/matches | Matching 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}/verification | Record 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}/decision | status: 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-approval | A different manager approves an accepted high-value release, under the same checks as the workspace. | claims:write |
| GET /claims/{id}/custody | Review 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}/handover | Record 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}/disposition | kind 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
| Request | What it does | Scope |
|---|---|---|
| GET/claims | Claims, 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.
| Request | What it does | Scope |
|---|---|---|
| GET/stays | List 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/stays | Create 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
| Request | What it does | Scope |
|---|---|---|
| GET/parcels | Parcels, 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/parcels | Log 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}/collect | Hand it over: collected_by (required) and an optional signature (a PNG data URL). | parcels:write |
| POST/parcels/{id}/return | Return it to the sender, with an optional note. | parcels:write |
| POST/parcels/{id}/remind | Email the recipient a reminder to collect it. | parcels:write |
| POST/parcels/tracking | Normalise 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-queue | People who said they are at the desk, with their parcel count and shelves. | parcels:read |
| POST/parcels/pickup-queue/{id}/serve | Mark one desk arrival as served. | parcels:write |
| POST/parcels/bulk-remind | Email reminders for up to 200 selected waiting parcels. | parcels:write |
| POST/parcels/bulk-return | Return up to 200 selected waiting parcels to sender. | parcels:write |
| GET/parcels/shelves | Parcel shelf capacities and current occupancy. | parcels:read |
| POST/parcels/shelves | Create a shelf or change its capacity. | parcels:write |
| GET/parcels/analytics | Volume, carrier mix, collection time, uncollected rate and busiest shelves. | parcels:read |
| GET/parcels/outgoing | Outgoing parcels ready for a courier or handed over. | parcels:read |
| POST/parcels/outgoing | Log an outgoing parcel. | parcels:write |
| POST/parcels/outgoing/{id}/handoff | Record the courier and signature at handoff. | parcels:write |
| GET/parcels/rounds | Delivery rounds and their stops. | parcels:read |
| POST/parcels/rounds | Create a campus or office round from waiting parcels. | parcels:write |
| POST/parcels/rounds/{round}/stops/{stop}/deliver | Complete a stop with the recipient name and signature. | parcels:write |
| GET/parcels/couriers | Couriers 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
| Request | What it does | Scope |
|---|---|---|
| GET/checkroom/tickets | Tickets, 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/tickets | Check 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-back | Hand 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/stations | List the site's checkroom stations, number ranges and storage locations. | checkroom:read |
| POST/checkroom/stations | Create 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/events | List recent and upcoming checkroom events. | checkroom:read |
| POST/checkroom/events | Create 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-queue | Tickets whose guests asked the desk to get their things ready. | checkroom:read |
| POST/checkroom/tickets/{id}/ready | Mark a waiting ticket ready and notify the guest. | checkroom:write |
| GET/checkroom/report | Ticket volume, peak hours, return time and fees by method and staff. | checkroom:read |
| GET/checkroom/export | Download 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.
| Request | What it does | Scope |
|---|---|---|
| GET/queue/lines | Lines 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/tickets | Tickets 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/report | Tickets, people served, no-shows, people who left, and median wait and service minutes for the last days. | queue:read |
| POST/queue/tickets | Add a person to a line, as the desk does. | queue:write |
| POST/queue/call-next | Call 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}/call | Call a chosen person to a counter. | queue:write |
| POST/queue/tickets/{id}/served | Mark the person at a counter served. | queue:write |
| POST/queue/tickets/{id}/no-show | Mark a called person who did not come as a no-show. | queue:write |
| POST/queue/tickets/{id}/remove | Take a person out of the line. | queue:write |
| GET/queue/bookings | Booked times, earliest first, with from, to, line, status and paging. Never the person's email. | queue:read |
| POST/queue/bookings | Book 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}/cancel | Cancel a booked time; the person is emailed that the team cancelled it. | queue:write |
| POST/queue/bookings/{id}/arrived | Check a booked person in; their ticket is placed by the booked time. | queue:write |
| POST/queue/tickets/{id}/arrived | Mark a person who joined before arriving as here. | queue:write |
| GET/queue/tickets/{id}/messages | The 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}/messages | Write to a person in line (body, 1 to 500 characters), as the key's team member. | queue:write |
| GET/queue/survey | Survey 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/performance | Plain figures for each team member over the same days as the report. No score and no ranking. | queue:read |
| GET/queue/lines/{id}/slots | The open booked times of a line, as its booking page offers them. | queue:read |
| POST/queue/join | Take 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/lookup | Find tickets by the number the guest holds. | queue:read |
| GET/queue/tickets/{id}/status | What the guest's own ticket page shows: place, estimate and sentence. | queue:read |
| GET/queue/tickets/{id}/history | The 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/history | Visits 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/insights | Counts 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-data | The 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
| Request | What it does | Scope |
|---|---|---|
| GET/loans | Equipment 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/loans | Hand 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}/extend | Give more time: a new due_at. The borrower is emailed the new time. | loans:write |
| POST/loans/{id}/return | Take 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/returns | Take 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/items | Everything 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}/tickets | Tickets sent to the site’s own Jira, Zendesk or ServiceNow for this item (beta), with the status last read back. | loans:read |
| POST/loans/items | Add 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}/tag | Whether an NFC or RFID tag is linked, and the last four hex digits of its serial number. | loans:read |
| PUT/loans/items/{id}/tag | Link 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}/tag | Remove the item’s tag. | loans:write |
| POST/loans/checkouts | Hand 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/kits | Saved groups of equipment that are usually handed out together. | loans:read |
| POST/loans/kits | Save 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/trainings | The trainings a category or item can require before someone borrows it (set up in Equipment, Policies, Training). | loans:read |
| GET/loans/trainings/{id}/holders | Who holds a training, from when and until when, and whether it has expired. | loans:read |
| POST/loans/trainings/{id}/holders | Give 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-types | The 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}/members | Who has a borrower type. | loans:read |
| POST/loans/borrower-types/{id}/members | Give 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/credits | Booking credits given recently, and one person's balance. Credits are a count that bookings spend, never money. | loans:read |
| POST/loans/credits | Give a person booking credits, or take some back with a negative number (owners and managers). | loans:write |
| GET/loans/holds | Active holds on borrowing: while one lasts, nothing goes out to the person and they cannot book. | loans:read |
| POST/loans/holds | Put 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}/lift | Lift a hold. | loans:write |
| GET/loans/spaces | Rooms, 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/spaces | Add 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/availability | Each 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}/book | Book 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}/parts | Add 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-part | Take one part out of a kit or cart booking; the last part is cancelled with the booking. | loans:write |
| GET/loans/places | The 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-tree | The equipment categories grouped into a tree, parents first. Rules and bookings still apply to an item's own category. | loans:read |
| GET/loans/asset-models | Models 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}/links | The links of an item to other items of the same site: works with, an alternative, replaces. | loans:read |
| POST/loans/items/{id}/links | Link 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}/move | Move 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-readings | Meter readings typed in for an item, newest first. | loans:read |
| POST/loans/items/{id}/meter-readings | Record 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/contracts | Supplier contracts linked to the items they cover (owners and managers). | loans:read |
| GET/loans/resale | Items 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/points | Pickup and drop-off points a booking can name. | loans:read |
| POST/loans/points | Add 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/projects | Projects a booking can belong to. Nothing is collected for a project until it is approved. | loans:read |
| POST/loans/projects | Add a project (waiting for approval). | loans:write |
| POST/loans/projects/{id}/decision | Approve or reject a project (owners and managers). | loans:write |
| GET/loans/risk-assessments | Risk assessments waiting for a review (or by status), with the borrower's answers. | loans:read |
| POST/loans/risk-assessments/{id}/review | Approve or reject a risk assessment (owners and managers). A rejection cancels the booking. | loans:write |
| POST/loans/reservation-series | Book 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}/move | Move 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/waitlist | People waiting for a time that was taken, by status (waiting by default). | loans:read |
| POST/loans/waitlist | Add 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}/cancel | Remove someone from the waiting list. | loans:write |
| GET/loans/fees | The 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/party | One borrower (person_id or party_key): what they owe per currency, deposits held, entries and invoices. | loans:read |
| GET/loans/fees/billing-codes | Charged, waived, settled and still owed per billing code and currency for a period; format=csv for a CSV. | loans:read |
| POST/loans/fees/charges | Record 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/payments | Record money the site took itself (cash, its own card terminal, a transfer). It settles open charges oldest first. | loans:write |
| POST/loans/fees/deposits | Record a deposit the site took; held until given back or kept. | loans:write |
| POST/loans/fees/deposits/{id}/return | Give a held deposit back. | loans:write |
| POST/loans/fees/deposits/{id}/keep | Keep 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}/waive | Waive what a charge still needs (owners and managers, with a reason). | loans:write |
| POST/loans/fees/{id}/void | Void 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}/fees | What 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-fine | Add the late fine for a loan that came back late, counted from when it came back. Once per loan. | loans:write |
| GET/loans/invoices | Invoices, newest number first. | loans:read |
| POST/loans/invoices | Issue a numbered invoice for a borrower's open charges in one currency. | loans:write |
| POST/loans/invoices/{id}/void | Void an invoice (owners and managers, with a reason); reissue puts its open charges on a new one that replaces it. | loans:write |
| GET/loans/reservations | Reservations by start time, optionally filtered by status or from. | loans:read |
| POST/loans/reservations | Reserve 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}/approve | Approve 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}/cancel | Cancel a pending, approved or ready reservation. | loans:write |
| POST/loans/reservations/{id}/pickup | Atomically hand over the reserved item and close the reservation as collected. | loans:write |
| POST/loans/reservation-groups | Reserve 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/downtimes | Dated 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/downtimes | Add 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/closures | Days the equipment desk is closed that have not ended yet. | loans:read |
| POST/loans/closures | Add 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/rules | Site 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/rules | Create or replace one category rule. Booking rule fields left out keep their saved values. | loans:write |
| GET/loans/timeline | Whole-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/warranties | Recorded 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/utilization | Per-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/maintenance | Service, 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/maintenance | Record 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-plans | Repeating 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-plans | Add 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/costs | Service, repair and cleaning cost per item, from finished entries and done work orders. | loans:read |
| GET/loans/items/{id}/lifecycle | An item's purchase, depreciation, insurance and disposal record, with its value today (owners and managers). | loans:read |
| PUT/loans/items/{id}/lifecycle | Save 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}/dispose | Record 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}/dispose | Undo a disposal made by mistake; the item is available again. | loans:write |
| GET/loans/valuation | The 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/import | Check 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/import | Check or add open work orders from a CSV in the documented columns (owners and managers). | loans:write |
| GET/loans/maintenance/planner | Scheduled work and open work orders by the site's own day for up to 62 days, optionally for one technician. | loans:read |
| GET/loans/funding | What 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/substances | The 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/substances | Add 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/licences | Licences 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/licences | Add 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/expiries | Insurance and licences ending soon or already ended (owners and managers). | loans:read |
| GET/loans/stocktakes | Recent equipment stock-takes with scanned and missing counts. | loans:read |
| POST/loans/stocktakes | Start 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}/scan | Scan an equipment label, asset tag or serial number into the open stock-take. | loans:write |
| POST/loans/stocktakes/{id}/scan-many | Count 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}/assign | Give the open stock-take to one team member to count (assigned_to), or to nobody (null). | loans:write |
| POST/loans/stocktakes/{id}/finish | Finish the stock-take and return the missing-item list. | loans:write |
| GET/loans/stocktake-schedules | Stock-takes that open by themselves, once or repeating. | loans:read |
| POST/loans/stocktake-schedules | Schedule 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-seen | Where each item was last scanned, when the site saves scan positions (team members who agreed only; never from a key). | loans:read |
| GET/loans/transfers | Incoming and outgoing equipment transfers for this site. | loans:read |
| POST/loans/transfers | Prepare equipment for another authorised site in the same customer group. | loans:write |
| POST/loans/transfers/{id}/send | Record that prepared equipment left the source site. | loans:write |
| POST/loans/transfers/{id}/receive | Receive equipment at the destination with its location and arrival state. | loans:write |
| POST/loans/transfers/{id}/cancel | Cancel a prepared transfer before dispatch. | loans:write |
| POST/loans/transfers/{id}/reject | Reject a prepared transfer at the destination before dispatch. | loans:write |
| POST/loans/transfers/{id}/exception | Record a problem while equipment is in transit. | loans:write |
| POST/loans/import | Preview or import up to 5,000 CSV rows using vFound, Snipe-IT, Sortly or Cheqroom headings. | loans:write |
Visitors
| Request | What it does | Scope |
|---|---|---|
| GET/visitors | Visits, 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/visitors | Invite 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-in | Sign 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-in | Sign 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-out | Sign them out. | visitors:write |
| POST/visitors/{id}/cancel | Cancel an invitation. | visitors:write |
| POST/visitors/{id}/send-pass | Email the pass again. | visitors:write |
| POST/visitors/{id}/approve | Approve a pending visit and send the pass. | visitors:write |
| POST/visitors/{id}/deny | Deny a pending visit. | visitors:write |
| GET/visitors/{id}/badge | Download the browser-printable badge. Choose size 4x3, brother or dymo. | visitors:read |
| GET/visitors/{id}/card | Whether 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}/card | Give 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}/card | Take the card back. | visitors:write |
| GET/visitors/{id}/assets | The things handed to the visit, typed by hand. | visitors:read |
| POST/visitors/{id}/assets | Record a thing handed to the visit, with an optional tag. | visitors:write |
| POST/visitors/{id}/assets/{asset}/return | Mark a thing as returned. | visitors:write |
| GET/visitor-assets/not-returned | Things handed to visitors and not yet returned, newest first. | visitors:read |
| GET/visitors/{id}/fast-track | Whether 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-track | Give a returning visitor a fast-track code that lasts days (1 to 365). | visitors:write |
| DELETE/visitors/{id}/fast-track | Take the code back. | visitors:write |
| GET/visitor-types | List 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-types | Create 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-call | Get 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-call | Start 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}/finish | Finish the active roll call and keep its report. | visitors:write |
| GET/staff-attendance | List 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-attendance | Sign 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-presence | Send 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}/catering | Make, 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/spaces | List the desks, meeting rooms and parking spaces people may book at the site. | visitors:read |
| GET/workplace/free | Find spaces free for a whole time (at most 7 days), leaving out a desk kept for another person. | visitors:read |
| GET/workplace/bookings | List desk, room and parking bookings in a time range of at most 31 days. Never includes the person's email. | visitors:read |
| POST/workplace/bookings | Book 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}/cancel | Cancel a booking, or with scope following or series its later times. | visitors:write |
| POST/workplace/bookings/{id}/check-in | Check a booking in, from 15 minutes before it starts until it ends. | visitors:write |
| POST/visitors/{id}/room | Book a meeting room for a visit, from the visit's time; the room follows the visit. | visitors:write |
| GET/appointment-pages | List the site's appointment pages, their hours and whether each is open to visitors now. | visitors:read |
| GET/visitor-roll-call/archive | List 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}/people | Add a person (an employee, other or contractor) to the running roll call. | visitors:write |
| POST/visitor-roll-call/{id}/scan | Mark a visitor safe from their pass link or code, at a muster point. | visitors:write |
| POST/visitor-roll-call/{id}/sweeps | Record a zone as swept clear or as having people in it. | visitors:write |
| POST/visitor-roll-call/{id}/messages | Send 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}/messages | The 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-alerts | A 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-alerts | Ask for help quietly: the team members chosen for it are told; no visitor sees anything. | visitors:write |
| GET/visitor-kiosks | List paired, pending and revoked kiosk devices. | visitors:read |
| POST/visitor-kiosks/pairing | Create 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}/settings | Change 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-analytics | Totals by day, hour, type and host, plus average stay for the last year. | visitors:read |
| GET/visitor-registration | Get the site's self-registration link and whether it is enabled. | visitors:read |
| GET/school/movements | Pupils’ 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/pupils | Add 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.
| Request | What it does | Scope |
|---|---|---|
| GET/people | The list, by name. Filters: search (name, email, unit or reference), updated_since. | people:read |
| GET/people/{id} | One person. | people:read |
| POST/people | Add someone: name (required), email, unit, reference and language for their emails. | people:write |
| POST/people/upsert | Add 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/export | Download the complete people list as a formula-safe CSV. | people:read |
| POST/people/{id}/send-my-vfound | Email one active person the signed page for their linked parcels, visitors and equipment. | people:write |
| GET/people/sync-source | Show the saved CSV directory and the latest sync result. | people:read |
| PUT/people/sync-source | Save a public HTTPS CSV url and mode (upsert or mirror). | people:write |
| DELETE/people/sync-source | Remove the connection and keep the people already imported. | people:write |
| POST/people/sync-source/run | Run 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.
| Event | When | Data |
|---|---|---|
item.created | A found item is added | Item |
item.updated | Its status, title, location, category, keep until date or photo visibility changes | Item |
item.transfer_sent | A found item is sent to another site of the group (both sites receive it) | Item transfer |
item.transfer_cancelled | The sending site takes it back before it arrives | Item transfer |
item.transfer_received | The receiving site confirms it arrived | Item transfer |
claim.created | A guest submits a claim | Claim |
item.disposition_recorded | An item is donated or disposed of | Item |
item.match_updated | A stored AI match verdict changes; report_id, item_id, label and reason | Match pair |
lost_report.match_updated | A stored AI match verdict changes; report_id, item_id, label and reason | Match pair |
claim.ownership_reviewed | A manager records an ownership review; fetch custody for the review history | Claim |
claim.decision_recorded | A claim is accepted or rejected | Claim |
claim.release_approved | A different manager approves release | Claim |
claim.handover_recorded | Physical pickup closes a ready-for-pickup claim | Claim |
claim.status_changed | A claim moves to a new status | Claim |
lost_report.updated, lost_report.closed, lost_report.contact_updated, lost_report.created | A guest reports a loss | Lost report |
parcel.logged | A parcel is logged at the desk or through the API | Parcel |
parcel.updated | Any of its details change at the desk, such as its recipient, tracking number or shelf | Parcel |
parcel.reminded | The recipient is sent a reminder, by the desk or automatically | Parcel |
parcel.collected | A parcel is handed over | Parcel |
parcel.returned | A parcel is returned to the sender | Parcel |
parcel.recipient_arrived | A recipient says they are at the desk | Pickup queue entry |
parcel.reminders_snoozed | A recipient pauses their reminders | Person and parcel count |
parcel.held | A recipient sets a hold date | Person, date and parcel count |
parcel.proxy_created | A recipient emails a delegate a collection code | Person, delegate and expiry |
parcel.pickup_served | The desk marks an arrival served | Pickup queue entry |
parcel.escalated | A waiting parcel reaches the site's escalation age | Parcel |
parcel.outgoing_logged | An outgoing parcel is logged | Outgoing parcel |
parcel.outgoing_handed_over | An outgoing parcel is handed to a courier | Outgoing handoff |
parcel.round_created | A delivery round is created | Round summary |
parcel.round_delivered | A delivery round stop is completed | Round, stop and parcel ids |
checkroom.checked_in | Something is checked in and given a number | Ticket |
checkroom.handed_back | It is handed back | Ticket |
checkroom.left | The night is closed with it still at the checkroom | Ticket |
checkroom.self_checkin_started | A guest starts a ticket from a paired kiosk | Ticket |
checkroom.ready_requested | A guest asks the desk to get their things ready | Ticket |
checkroom.ready | The desk marks a guest's things ready | Ticket |
checkroom.station_created | A checkroom station is created | Station |
checkroom.station_updated | A checkroom station changes | Station |
checkroom.event_created | A checkroom event is created | Event |
checkroom.event_updated | A checkroom event changes | Event |
loan.checked_out | An item is handed out | Loan |
loan.due_soon | Its due time is less than two hours away, once per due time | Loan |
loan.overdue | Its due time passes and it is not back, once per due time | Loan |
loan.extended | Its due time changes | Loan |
loan.returned | It comes back to the desk | Loan |
loan.lost | It is recorded as not coming back | Loan |
loan.checkout_created | One atomic multi-item checkout is created | Checkout, with any stock on the same receipt in stock |
loan.self_checkout | A borrower completes kiosk checkout | Checkout |
loan.kit_created | A saved equipment kit is created | Kit |
loan.kit_updated | A saved equipment kit changes | Kit |
loan.reservation_requested | A reservation waits for approval | Reservation |
loan.reservation_created | A reservation is confirmed immediately | Reservation |
loan.reservation_approved | A pending reservation is approved | Reservation |
loan.reservation_ready | Reserved equipment is ready for collection | Reservation |
loan.reservation_cancelled | A reservation is cancelled | Reservation |
loan.reservation_collected | Reserved equipment is handed over | Checkout |
loan.extension_requested | A borrower asks for more time | Loan |
loan.problem_reported | A borrower reports an equipment problem | Loan |
loan.rule_updated | A category checkout rule changes | Rule |
loan.maintenance_logged | Maintenance is recorded | Maintenance |
loan.maintenance_due | Scheduled maintenance becomes due | Maintenance |
loan.service_due | A repeating service schedule becomes due (by date, hours checked out or number of checkouts), once per round | Maintenance |
loan.work_order_opened | A work order is opened, by staff or by a return the site asks to open one for | Maintenance |
loan.work_order_closed | A work order is done or cancelled | Maintenance |
loan.item_disposed | An item is disposed of (sold, scrapped, donated, recycled, lost or stolen) | Equipment |
loan.stocktake_started | An equipment stock-take starts | Stock-take |
loan.stocktake_completed | An equipment stock-take finishes | Stock-take |
loan.transfer_prepared | An authorised site prepares equipment to move | Transfer |
loan.transfer_sent | Prepared equipment leaves its source site | Transfer |
loan.transfer_received | The destination receives the equipment | Transfer |
loan.transfer_rejected | The destination rejects a prepared transfer | Transfer |
loan.transfer_cancelled | The source cancels a prepared transfer | Transfer |
loan.transfer_exception | An in-transit transfer needs attention | Transfer |
loan.transfer_lost | The source closes a transfer that never arrived | Transfer |
loan.charge_recorded | A fine, damage, replacement, usage or other charge is recorded | Fees entry |
loan.charge_waived | A manager waives what a charge still needs, with a reason | Fees entry |
loan.payment_recorded | Staff record money the site took itself (vFound never processes a payment) | Fees entry |
loan.payment_voided | A manager voids a payment recorded by mistake | Fees entry |
loan.deposit_recorded | Staff record a deposit the site took | Fees entry |
loan.deposit_resolved | A held deposit is given back or kept | Fees entry |
loan.invoice_issued | An invoice is issued for a borrower's charges | Invoice |
loan.invoice_voided | A manager voids an invoice, with a reason | Invoice |
loan.quote_accepted | The team accepts a quote and its bookings are made | Quote |
loan.payment_request_created | The team records a payment request (nothing is sent to the person) | Payment request |
loan.payment_request_paid | Payments recorded against a request cover it in full | Payment request |
loan.delivery_done | A delivery or a collection is marked done | Delivery |
loan.items_imported | An equipment CSV import completes | Counts |
visit.expected | A visitor is invited | Visit |
visit.signed_in | A visitor signs in, at the desk or from your QR sign | Visit |
visit.host_confirmed | The desk confirms who a self signed in visitor came to see | Visit |
visit.signed_out | They sign out, at the desk, from their pass or automatically after the day ends | Visit |
visit.cancelled | An invitation is cancelled | Visit |
visit.approval_requested | A visit waits for staff approval | Visit |
visit.approved | A pending visit is approved | Visit |
visit.denied | A pending visit is denied | Visit |
visit.host_replied | A host replies from their private link | Visit |
visit.roll_call_started | A live roll call (an emergency, a drill or a notice) starts | Roll call summary |
visit.roll_call_completed | A live roll call finishes | Roll call summary |
visitor_type.created | A visitor type is created | Visitor type |
visitor_type.updated | A visitor type changes | Visitor type |
visitor_type.deactivated | A visitor type is deactivated | Visitor type |
visitor_agreement.signed | A visitor signed an agreement document, with a link to the signed copy that works for seven days | Agreement signature |
kiosk.paired | A visitor kiosk is paired | Kiosk |
kiosk.revoked | A visitor kiosk is revoked | Kiosk |
courier.signed_in | A delivery visitor is logged in Parcels | Courier |
courier.signed_out | A delivery visitor leaves | Courier |
staff.signed_in | A person on the staff list signs in, in the office or remote | Staff attendance |
staff.signed_out | A person on the staff list signs out, or is signed out automatically | Staff attendance |
person.created | A person is added | Person |
person.updated | A person is changed | Person |
person.deactivated | Directory provisioning deactivates a person | Person |
person.deleted | A person is removed | Person |
people.sync.completed | A connected CSV sync completes | Counts |
people.sync.failed | A connected CSV sync fails safely | Error |
report.delivered | A 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_joined | A person joins a line, from their phone, a kiosk, the desk or the API | Queue ticket |
queue.ticket_called | A person is called to a counter, or called again | Queue ticket |
queue.ticket_served | A person is marked served | Queue ticket |
queue.ticket_no_show | A called person is marked a no-show, by the team or after the line's minutes | Queue ticket |
queue.ticket_left | A person leaves the line from their ticket, or the team takes them out | Queue ticket |
queue.ticket_transferred | A person is moved to another line or counter | Queue ticket |
queue.ticket_closed | A ticket still open at the end of the site's day, or in an archived line, is closed | Queue ticket |
queue.booking_created | A person books a time on a line's booked-times page, or the API books one | Queue booking |
queue.booking_cancelled | A booked time is cancelled by the person, the team or the API | Queue booking |
queue.ticket_arrived | A person who joined before arriving says they are here, or the team marks them arrived | Queue ticket |
queue.message_received | A person in line writes to the team from their ticket page; the event carries no words | Queue message |
queue.message_sent | The team writes to a person in line; the event carries no words | Queue message |
queue.survey_answered | A served person answers the survey; the event carries the rating and never the comment | Queue 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.
| Request | What it does | Scope |
|---|---|---|
| GET/webhooks | The addresses this key created, and their events. | webhooks:manage |
| POST/webhooks | Add 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_…"}}}}
| Tool | What it does | Scope |
|---|---|---|
search_found_items | Search found items by words such as “black iPhone” | items:read |
list_expected_visitors | Visitors invited and not here yet | visitors:read |
list_visitors_on_site | Visitors signed in now | visitors:read |
list_visitor_types | Visitor types and their rules | visitors:read |
visitor_analytics | Visitor totals, patterns and average stay | visitors:read |
visitor_registration_link | The site's self-registration link | visitors:read |
list_couriers_on_site | Couriers signed in through Visitors | parcels:read |
list_waiting_parcels | Parcels waiting to be collected | parcels:read |
detect_parcel_tracking | Normalise a tracking number and detect its carrier | parcels:read |
parcel_pickup_queue | People waiting at the parcel desk | parcels:read |
parcel_shelves | Parcel shelf capacity and occupancy | parcels:read |
parcel_analytics | Parcel volume, carriers and collection performance | parcels:read |
list_outgoing_parcels | Outgoing parcels and their handoff state | parcels:read |
list_parcel_rounds | Parcel delivery rounds and stops | parcels:read |
list_checkroom_exit_queue | Tickets whose guests are waiting at the exit | checkroom:read |
mark_checkroom_ready | Mark a waiting ticket ready and notify the guest | checkroom:write |
list_checkroom_stations | Checkroom stations and number ranges | checkroom:read |
list_checkroom_events | Recent and upcoming checkroom events | checkroom:read |
checkroom_report | Checkroom volume, return time and fee totals | checkroom:read |
list_queue_lines | Lines, people waiting and the estimated wait now | queue:read |
list_queue_waiting | People waiting today, in calling order | queue:read |
queue_report | Queue totals and median wait and service minutes | queue:read |
call_next_in_queue | Call the next person to a counter | queue:write |
mark_queue_ticket_served | Mark the person at a counter served | queue:write |
list_overdue_equipment | Equipment past its due time, and who has it | loans:read |
list_equipment_kits | Saved groups of equipment | loans:read |
create_equipment_kit | Save a reusable equipment kit without handing it over | loans:write |
list_equipment_reservations | Reservations by time and status | loans:read |
reserve_equipment | Reserve an item or category without handing it over | loans:write |
book_repeating_reservation | Book an item, category or space every day or week | loans:write |
move_reservation | Move a reservation to new times or another item of its category | loans:write |
list_waitlist | The people waiting for a time that was taken | loans:read |
join_waitlist | Add someone to the waiting list | loans:write |
list_space_bookings | Each room, desk or parking space and its bookings between two times | loans:read |
book_space | Book a room or space for a person and time; it is never handed out | loans:write |
list_equipment_rules | Site and category checkout rules | loans:read |
save_equipment_rule | Create or replace a category rule | loans:write |
list_equipment_maintenance | Equipment maintenance history and upcoming work | loans:read |
list_equipment_service_plans | Repeating service, calibration, safety-test, inspection and cleaning schedules and which are due | loans:read |
update_equipment_work_order | Change or close an equipment work order | loans:write |
get_equipment_maintenance_costs | Service, repair and cleaning cost per item | loans:read |
get_equipment_valuation | The value of the equipment on a date after depreciation (owners and managers) | loans:read |
list_equipment_substances | The hazardous-substances register: substance, place, hazard classes and review dates (a record, no safety advice) | loans:read |
get_equipment_funding | What each fund, grant or cost centre bought and what work was charged to it (owners and managers) | loans:read |
get_equipment_planner | Scheduled work and open work orders by the site's own day | loans:read |
list_equipment_licences | Licences for the equipment with seats and end dates (owners and managers) | loans:read |
get_equipment_expiries | Insurance and licences ending soon or already ended (owners and managers) | loans:read |
log_equipment_maintenance | Record service, calibration, a safety test, an inspection, cleaning, a repair or a note | loans:write |
list_equipment_stocktakes | Recent stock-takes and their counts | loans:read |
start_equipment_stocktake | Start a stock-take | loans:write |
scan_equipment_stocktake | Record one item in an open stock-take | loans:write |
scan_many_equipment_stocktake | Count many codes in an open stock-take at once | loans:write |
finish_equipment_stocktake | Finish a stock-take and return what is missing | loans:write |
list_equipment_transfers | Incoming and outgoing transfers without borrower details | loans:read |
preview_equipment_import | Validate an equipment CSV without saving it | loans:write |
find_person | Look someone up on the people list | people:read |
export_people | Export the people list as formula-safe CSV | people:read |
directory_sync_status | Check the saved CSV connection and its latest run | people:read |
run_directory_sync | Run the saved CSV connection now | people:write |
email_my_vfound | Email one person their signed private page | people:write |
invite_visitor | Invite a visitor, who gets a pass by email | visitors:write |
approve_visit | Approve a pending visit request | visitors:write |
list_free_workplace_spaces | Find free desks, meeting rooms or parking for a time | visitors:read |
book_workplace_space | Book a desk, meeting room or parking space for a person | visitors:write |
request_visit_catering | Ask for catering with a visit, from the options the site lists | visitors:write |
list_appointment_pages | List the site's appointment pages and whether each is open to visitors | visitors:read |
list_staff_on_site | List people on the staff list signed in now, in the office or remote | visitors:read |
sign_staff_in_or_out | Sign a person on the staff list in or out | visitors:write |
list_visitor_assets_not_returned | List things handed to visitors that are not marked back yet | visitors:read |
issue_visitor_asset | Record a thing handed to an expected or signed-in visit | visitors:write |
return_visitor_asset | Mark a thing handed to a visit as returned | visitors:write |
start_roll_call | Start or return the active roll call | visitors:write |
mark_visitor_safe | Mark one visitor safe | visitors:write |
create_kiosk_pairing | Create a ten-minute kiosk pairing code | visitors:write |
log_parcel | Log a parcel and email the recipient | parcels:write |
remind_parcel | Remind a recipient to collect a parcel | parcels:write |
remind_parcels | Remind up to 200 selected parcel recipients | parcels:write |
log_outgoing_parcel | Add an outgoing parcel to the courier log | parcels:write |
create_parcel_round | Create a delivery round from waiting parcels | parcels:write |
extend_loan | Give a borrower more time | loans: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:
| Code | What it means |
|---|---|
parcel_not_waiting | The parcel is no longer waiting: it was already collected, returned or delivered. |
tracking_duplicate | A parcel with this tracking number is already waiting here. |
no_email | The person or visitor has no email address, so nothing can be sent. |
capacity_full | Every checkroom number is in use. |
already_checked_in | The checkroom ticket is already checked in. |
already_handed_back | The checkroom ticket was already handed back. |
nothing_to_hand_back | The checkroom ticket has nothing to hand back. |
number_in_use | That checkroom number is already in use. |
ticket_closed | Only an open checkroom ticket can be emailed. |
item_out | The equipment is out with someone. Take it back first. |
item_in_repair | The equipment is set aside for repair. |
item_retired | The equipment is retired, so it cannot be handed out or reserved. |
reservation_conflict | Someone has reserved the item, or the last free one in its category, during this time, or it is expected to still be out. |
already_back | The equipment was already taken back. |
not_out | The equipment is not out, so it cannot get more time, a reminder or be marked as not coming back. |
borrower_overdue | The borrower has overdue equipment, and the site or the category allows nothing more until it comes back. |
borrower_item_limit | This would give the borrower more items than the site or the category allows at once. |
reservation_not_ready | The reservation is not approved yet, or it was already collected or cancelled. |
reservation_item_mismatch | The checkout does not include the item the reservation is for. |
reservation_category_mismatch | The checkout includes an item outside the reserved category. |
reservation_borrower_mismatch | The reservation belongs to a different borrower. |
reservation_too_long | The reservation is longer than the category can be borrowed. Only reservations made from My vFound are limited this way. |
reservation_daily_limit | The borrower already made 5 reservations from My vFound in the last 24 hours. |
booking_notice | The reservation starts sooner than the category's minimum notice allows. |
booking_too_far_ahead | The booking, checkout or new due time ends later than the category can be booked ahead. |
desk_closed | The reservation would start on a day the equipment desk is closed. |
kit_unavailable | Part 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_group | The 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_allowed | None of the borrower's borrower types allows this category. |
borrower_on_hold | Borrowing 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_small | More people than the room or space holds (its capacity). |
kit_locked | The equipment belongs to a locked kit, which goes out only as a whole: include every named item of the kit. |
approval_not_yours | The 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_approved | The booking belongs to a project that is not approved yet, so nothing can be collected. |
not_enough_credits | The 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_pending | The booking has a risk assessment that has not been approved, so nothing can be collected. |
series_unavailable | A 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_available | The time someone asked to wait for is free, so book it instead of joining the waiting list. |
space_not_handed_out | A room or space is booked for its time and never handed out, so it cannot be checked out or collected. |
stock_short | There 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_closed | Everything from this stock hand-out is already back or written off. |
order_closed | A purchase order is finished or cancelled and cannot change. |
order_over_received | More was entered than a purchase order line still expects. |
order_not_placed | Stock cannot be received against a purchase order that is still a draft. |
fees_off | Fees are off for this site. Turn them on in the desk and borrowing policy first. |
entry_closed | That 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_invoice | The charge is on an issued invoice. Void the invoice first, then waive the charge. |
not_late | The loan did not come back late under the site's late fine rules, or it is still out. |
nothing_to_invoice | The borrower has no open charge in that currency that is not already on an issued invoice. |
charge_unavailable | One of the chosen charges is not open, is on another invoice or is for someone else. |
desk_kept | The desk is kept for another person on one of the days asked for. |
desk_has_bookings | Keeping the desk for this person would clash with open bookings by others on those days. Cancel those first. |
booking_closed | The desk, room or parking booking was cancelled or released, so it cannot be checked in. |
check_in_closed | Check-in opens 15 minutes before a booking starts and closes when it ends. |
item_service_due | The 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_inspection | The site keeps equipment that needs work from going out, and the last check of this item failed. Record a pass first. |
work_order_closed | This work order is already closed and cannot be changed. |
already_disposed | This item has already been disposed of. |
not_disposed | This item has not been disposed of, so there is nothing to undo. |
item_disposed | This item was disposed of. Undo the disposal before using it again. |
training_required | A 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_open | A stock-take is already open. Finish it first. |
item_unavailable | The equipment is not available or set aside for repair, so it cannot start a transfer. |
transfer_open | The equipment already has an open transfer. |
transfer_not_ready | Only a prepared transfer can be sent. |
transfer_not_in_transit | Only equipment in transit can be received or marked with a problem. |
transfer_already_sent | A sent transfer can no longer be cancelled or rejected. |
already_signed_in | The visitor is already signed in. |
visit_closed | The visit is closed. Sign the visitor in as a new visit. |
not_signed_in | The visitor is not signed in. |
not_expected | Only an expected visit can be cancelled or sent a pass. |
approval_required | The visit needs approval before the visitor can sign in. |
visit_not_valid_today | The pass cannot be used again today, or today is outside its dates. |
plus_one_not_allowed | The pass does not allow guests, or it is no longer approved, expected or valid. |
plus_one_limit | The visitor has added every guest the pass allows. |
nobody_to_sign_in | Nobody in the visit's group is expected today. |
visitor_capacity_full | Signing 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:
| Code | What it means |
|---|---|
screening_match | The 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_scope | The 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.
| Code | What it means |
|---|---|
checklist_incomplete | 422: 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:
| Code | What it means |
|---|---|
idempotency_key_invalid | 400: the header is not 1 to 191 visible ASCII characters. |
idempotency_key_reused | 422: this key was already used for a different request. |
idempotency_in_progress | 409: the first request with this key is still running. Try again shortly. |
offline_in_progress | The 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:
| Code | What it means |
|---|---|
acting_user_refused | 403: 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_role | 403: the named team member cannot use this operation’s scope with their role at the site. |