Lost Items
You can use the Found Hero API to create, update, list, and remove lost items.
Packaging Boxes
Found Hero currently supports the following packaging boxes. You should pass the value of the selected box while creating the lost item.
Value
Description
Dimension (cm)
letter
Letter
33 x 23 x 3
flat
Flat Box
33 x 23 x 6
shoe
Shoe Box
40 x 20 x 20
moving
Moving Box
60 x 40 x 40
long
Long Box
100 x 20 x 20
We are working on adding support for custom packaging boxes. It will allow users to input the width, height, and depth of the package box.
Create an item
POST
https://api.joinfoundhero.com/v1/locations/:lid/items
This endpoint allows you to create a new lost item. Found Hero will automatically notify the owner when the guest details are provided.
Path Parameters
lid
string
The unique ID of the location
Request Body
description
string
A brief description of the lost item. Example: iPhone X
discoveryPlace
string
The place where the lost item was found.
discoveryDate
string
The discovery date of the lost item in YYYY-MM-DD format
brand
string
The name of the item's manufacturer
model
string
The brand
's model of the lost item
color
string
The color of the item
storagePlace
string
The place where the lost item is stored. You can use this parameter to override the location's default storage place.
notes
string
Internal notes for your team members
imageUrl
string
An image URL for the lost item
shipping
object
A JSON object containing information about the item's shipment
shipping.weight
number
The weight of the lost item
shipping.weightUnit
string
Weight unit. Acceptable values are lb
, kg
, oz
, and g
. The default value is kg
.
shipping.boxType
string
Type of the packaging box. Please refer to the above packaging boxes table for all available values.
shipping.isDocument
boolean
A true
or false
value indicating whether the lost item consists of documents only
owner
object
An optional JSON object containing information about the guest
owner.firstName
string
The first name of the guest
owner.lastName
string
The last name of the guest
owner.email
string
The email address of the guest
owner.phone
string
The phone number of the guest. It must include the country code.
Retrieve an item
GET
https://api.joinfoundhero.com/v1/locations/:lid/items/:id
This endpoint allows you to retrieve the details of a lost item that has previously been created. Just pass the unique location and item IDs, and Found Hero will return the corresponding lost item information.
Path Parameters
lid
string
The unique ID of the location
id
string
The unique ID of the lost item
Update an item
PUT
https://api.joinfoundhero.com/v1/locations/:lid/items/:id
This endpoint allows you to update the lost item information.
Path Parameters
lid
string
The unique ID of the location
id
string
The unique ID of the item
Request Body
description
string
A brief description of the lost item. Example: iPhone X
discoveryPlace
string
The place where the lost item was found
discoveryDate
string
The discovery date of the lost item in YYYY-MM-DD format
brand
string
The name of the item's manufacturer
model
string
The brand
's model of the lost item
color
string
The color of the item
storagePlace
string
The place where the lost item is stored. You can use this parameter to override the location's default storage place.
notes
string
Internal notes for your team
imageUrl
string
An optional image URL for the lost item
shipping
object
A JSON object containing information about the item's shipment
shipping.weight
number
The weight of the lost item
shipping.weightUnit
string
Weight unit. Acceptable values are lb
, kg
, oz
, and g
. The default value is kg
.
shipping.boxType
string
Type of the packaging box. Please refer to the above packaging boxes table for all available values.
shipping.isDocument
boolean
A true
or false
value indicating whether the lost item consists of documents only
owner
object
An optional JSON object containing information about the guest
owner.firstName
string
The first name of the guest
owner.lastName
string
The last name of the guest
owner.email
string
The email address of the guest
owner.phone
string
The phone number of the guest. It must include the country code.
Retrieve all items by location
GET
https://api.joinfoundhero.com/v1/locations/:lid/items
Retrieve all lost items associated with a specific location. By default, this method returns a set of 10 most recent lost items.
You can also supply an optional query parameter called term
to search lost items by their descriptions and guest information.
This method also supports pagination. You can use limit
and page
query parameters to control pagination.
Path Parameters
lid
string
The unique ID of the location
Query Parameters
term
string
Search term to filter-out lost items
limit
integer
The number of results per page. The value must be between 10
and 100
. The default value is 10
.
page
integer
The current page number. The default value is 1
.
Delete an item
DELETE
https://api.joinfoundhero.com/v1/locations/:lid/items/:id
This endpoint allows you to permanently delete a lost item. It cannot be undone.
Path Parameters
lid
string
The unique ID of the location
id
string
The unique ID of the lost item
Upload an image
POST
https://api.joinfoundhero.com/v1/locations/:lid/items/:id/upload-image
This endpoint allows you to upload an image for the lost item. For this particular request, you must set the request Content-Type
header to multipart/form-data
.
Path Parameters
lid
string
The unique lD of the location
id
string
The unique ID of the lost item
Request Body
image
string
The file to upload. The file size must not exceed 10MB.
Update Item Status
PUT
https://api.joinfoundhero.com/v1/locations/:lid/items/:id/update-status
This endpoint allows you to update item status. The different item status are : case 'PENDING' : return 'Waiting for response' case 'INFO COMPLETED : 'Recipient details filled' case 'FEE PAID' : return 'Shipping fee paid' case 'SHIPPED' : return 'In route' case 'DELIVERED' : return 'Safely Delivered' case 'DISCARD' : return 'Left behind' case 'PICKUP' : return 'Pick up by guest' case 'DONATE' : return 'Donate to chartiy'
Path Parameters
id
string
The unique ID of the lost item
lid
string
The unique ID of the location
Request Body
status
string
The new status you want to affect to the item
Last updated