Scans API
Public endpoints for scanning QrioTags, contacting tag owners anonymously, managing finder threads, and accessing emergency information.
The Scans API powers the core QrioTag experience — what happens when someone finds a tagged item and scans the QR code. Most of these endpoints are public and do not require authentication.
Scan a Tag
GET /api/v1/scan/:encryptedId — Public
Contact Owner
POST /api/v1/scan/:encryptedId/contact — Public
Thread Messages
GET /api/v1/scan/thread/:token — Token-based
Reply to Thread
POST /api/v1/scan/thread/:token/reply — Token-based
Thread Reward
GET /api/v1/scan/thread/:token/reward — Token-based
Emergency Info
GET /api/v1/scan/:encryptedId/emergency — Public
Scan a Tag
Retrieve the public profile of a tag by its encrypted ID. This is the endpoint called when someone scans a QR code.
GET /api/v1/scan/:encryptedId — Auth: None (public)
Rate limited to 30 requests per minute per IP address.
curl https://api.qriotag.global/api/v1/scan/aGVsbG8td29ybGQResponse
{
"success": true,
"data": {
"tagId": "tag_abc123",
"itemName": "House Keys",
"description": "Set of 3 keys on a blue lanyard",
"ownerName": "Jane",
"status": "LOST",
"lostMessage": "Please help me find my keys!",
"reward": 25.00,
"tagType": "GENERAL",
"photos": [
{
"url": "https://cdn.qriotag.com/photos/pht_001.jpg",
"isPrimary": true
}
],
"contactEnabled": true,
"emergencyAvailable": false
}
}Privacy
The scan response never reveals the owner's email, phone number, or personal details. Finders can only contact owners through the anonymous messaging system.
Contact Tag Owner
Send an anonymous message to the tag owner. Creates a new finder thread.
POST /api/v1/scan/:encryptedId/contact — Auth: None (public)
Request body
| Field | Type | Required | Description |
|---|---|---|---|
finderName | string | No | Name of the person who found the item |
message | string | Yes | Message to the tag owner |
curl -X POST https://api.qriotag.global/api/v1/scan/aGVsbG8td29ybGQ/contact \
-H "Content-Type: application/json" \
-d '{
"finderName": "Alex",
"message": "I found your keys at the coffee shop on Main Street. Happy to arrange a return!"
}'Response
{
"success": true,
"data": {
"threadToken": "thr_tok_abc123def456",
"message": "Message sent to the tag owner. Use the thread token to check for replies."
}
}Thread token
The finder receives a threadToken that they use to check for replies. This token is the only way to access the conversation — no account is needed.
Get Thread Messages
Retrieve all messages in a finder thread using the thread token.
GET /api/v1/scan/thread/:token — Auth: None (token-based)
curl https://api.qriotag.global/api/v1/scan/thread/thr_tok_abc123def456Response
{
"success": true,
"data": {
"threadId": "thr_abc123",
"tagName": "House Keys",
"status": "ACTIVE",
"messages": [
{
"id": "msg_001",
"sender": "FINDER",
"content": "I found your keys at the coffee shop on Main Street.",
"createdAt": "2025-06-01T15:35:00.000Z"
},
{
"id": "msg_002",
"sender": "OWNER",
"content": "Thank you so much! Can we meet there at 5pm?",
"createdAt": "2025-06-01T15:50:00.000Z"
}
]
}
}Reply to Thread
Send a reply in a finder thread.
POST /api/v1/scan/thread/:token/reply — Auth: None (token-based)
Request body
| Field | Type | Required | Description |
|---|---|---|---|
message | string | Yes | Reply message content |
curl -X POST https://api.qriotag.global/api/v1/scan/thread/thr_tok_abc123def456/reply \
-H "Content-Type: application/json" \
-d '{ "message": "Yes, 5pm works! I will be wearing a red jacket." }'Response
{
"success": true,
"data": {
"id": "msg_003",
"sender": "FINDER",
"content": "Yes, 5pm works! I will be wearing a red jacket.",
"createdAt": "2025-06-01T16:00:00.000Z"
}
}Get Thread Reward Info
Check if a reward is offered for returning the tagged item.
GET /api/v1/scan/thread/:token/reward — Auth: None (token-based)
curl https://api.qriotag.global/api/v1/scan/thread/thr_tok_abc123def456/rewardResponse
{
"success": true,
"data": {
"offered": true,
"amount": 25.00,
"currency": "USD",
"description": "Reward for safe return of my keys"
}
}Get Emergency Info
Retrieve emergency medical information for a tag (e.g., a medical ID wristband).
GET /api/v1/scan/:encryptedId/emergency — Auth: None (public)
Rate limited
This endpoint is limited to 5 requests per minute per IP address to prevent abuse.
Public access
Emergency information is always accessible without authentication, even if the tag profile is set to private. This is by design for first responder access.
curl https://api.qriotag.global/api/v1/scan/aGVsbG8td29ybGQ/emergencyResponse
{
"success": true,
"data": {
"bloodType": "O+",
"conditions": ["Diabetes Type 2", "Hypertension"],
"allergies": ["Penicillin", "Peanuts"],
"medications": ["Metformin 500mg", "Lisinopril 10mg"],
"physician": "Dr. Sarah Johnson",
"physicianPhone": "(555) 987-6543",
"specialInstructions": "Carries insulin pen in bag",
"organDonor": true,
"emergencyContacts": [
{
"name": "John Doe",
"relationship": "Spouse",
"phone": "(555) 123-4567"
}
]
}
}Was this page helpful?