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.
post
Create an item
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.
Request
Response
Request
Path Parameters
lid
required
string
The unique ID of the location 
Body Parameters
description
required
string
A brief description of the lost item. Example: iPhone X
discoveryPlace
required
string
The place where the lost item was found. 
discoveryDate
required
string
The discovery date of the lost item in YYYY-MM-DD format
brand
optional
string
The name of the item's manufacturer 
model
optional
string
The brand's model of the lost item
color
optional
string
The color of the item
storagePlace
optional
string
The place where the lost item is stored. You can use this parameter to override the location's default storage place.
notes
optional
string
Internal notes for your team members
imageUrl
optional
string
An image URL for the lost item
shipping
required
object
A JSON object containing information about the item's shipment 
shipping.weight
required
number
The weight of the lost item 
shipping.weightUnit
optional
string
Weight unit. Acceptable values are lb, kg, oz, and g. The default value is kg. 
shipping.boxType
optional
string
Type of the packaging box. Please refer to the above packaging boxes table for all available values.
shipping.isDocument
optional
boolean
A true or false value indicating whether the lost item consists of documents only
owner
optional
object
An optional JSON object  containing information about the guest 
owner.firstName
optional
string
The first name of the guest
owner.lastName
optional
string
The last name of the guest
owner.email
optional
string
The email address of the guest
owner.phone
optional
string
The phone number of the guest. It must include the country code.
Response
200: OK
The lost item is created successfully.
{
    "status": true,
    "message": "Lost item created successfully",
    "data": {
        "owner": {
            "firstName": "Amina",
            "lastName": "Mankid",
            "email": "[email protected]",
            "phone": "+49 175 78452548"
        },
        "shipping": {
            "weightUnit": "kg",
            "isDocument": false,
            "trackingNumbers": [],
            "totalPrice": 0,
            "taxes": 0,
            "fees": 0,
            "insurance": 0,
            "weight": 3.5,
            "boxType": "moving"
        },
        "ownShipment": false,
        "labelGenerated": false,
        "archived": false,
        "language": "en",
        "_id": "5f29dbaf81e97ab3a73e2c69",
        "location": "5f29a6a2af7c9568fe1437f7",
        "identifier": "etxOKQlM5sAx",
        "description": "Macbook Pro",
        "discoveryPlace": "Room #452",
        "discoveryDate": "2020-07-22T00:00:00.000Z",
        "lastEmailSent": "2020-08-04T22:05:35.361Z",
        "notes": "The item seems to be damaged.",
        "brand": "Apple",
        "model": "X Series",
        "color": "Silver",
        "status": "PENDING",
        "activity": [
            {
                "_id": "5f29dbaf81e97ab3a73e2c6a",
                "type": "EMAIL_SENT",
                "title": "An email was sent at [email protected] to inform the owner about their lost item.",
                "createdAt": "2020-08-04T22:05:35.808Z",
                "updatedAt": "2020-08-04T22:05:35.808Z"
            }
        ],
        "storagePlace": "Reception",
        "createdAt": "2020-08-04T22:05:35.381Z",
        "updatedAt": "2020-08-04T22:05:35.810Z"
    }
}
400: Bad Request
The request can not be completed due to data validation errors.
{
    "status": false,
    "message": "Item description is required"
}
404: Not Found
The location doesn't exist.
{
    "status": false,
    "message": "Location not found"
}
get
Retrieve an item
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. 
Request
Response
Request
Path Parameters
lid
required
string
The unique ID of the location
id
required
string
The unique ID of the lost item
Response
200: OK
The lost item is retrieved successfully.
{
    "status": true,
    "data": {
        "owner": {
            "firstName": "Amina",
            "lastName": "Mankid",
            "email": "[email protected]",
            "phone": "+49 175 78452548"
        },
        "shipping": {
            "weightUnit": "kg",
            "isDocument": false,
            "trackingNumbers": [],
            "totalPrice": 0,
            "taxes": 0,
            "fees": 0,
            "insurance": 0,
            "weight": 3.5,
            "boxType": "moving"
        },
        "ownShipment": false,
        "labelGenerated": false,
        "archived": false,
        "language": "en",
        "_id": "5f29dbaf81e97ab3a73e2c69",
        "location": {
            "contact": {
                "name": "David Backem",
                "email": "[email protected]",
                "email2": null,
                "phone": "+1 (455) 4567-8974"
            },
            "pickupTime": {
                "from": "08:00",
                "to": "14:00"
            },
            "storageDuration": 30,
            "active": true,
            "_id": "5f29a6a2af7c9568fe1437f7",
            "user": "5f1c11c77431601b2fff7459",
            "name": "Four Seasons Hotel Chicago",
            "permalink": "four-seasons-hotel-chicago-TIqfTF",
            "identifier": "8LiwV5xppI3s",
            "website": "https://www.fourseasons.com/chicago/",
            "type": "hotel",
            "storagePlace": "House Keeping",
            "address1": "120 E. Delaware Place",
            "city": "Chicago",
            "state": "IL",
            "zipCode": "60611",
            "country": "US",
            "createdAt": "2020-08-04T18:19:14.471Z",
            "updatedAt": "2020-08-04T20:47:28.688Z",
            "__v": 0,
            "address2": null,
            "description": "#1 hotel in Chicago",
            "latitude": null,
            "longitude": null,
            "logoUrl": "https://cdn.joinfoundhero.com/l/38acd909-e623-48e2-8c89-b01f5759afbd.png"
        },
        "identifier": "etxOKQlM5sAx",
        "description": "Macbook Pro",
        "discoveryPlace": "Room #452",
        "discoveryDate": "2020-07-22T00:00:00.000Z",
        "lastEmailSent": "2020-08-04T22:05:35.361Z",
        "notes": "The item seems to be damaged.",
        "brand": "Apple",
        "model": "X Series",
        "color": "Silver",
        "status": "PENDING",
        "activity": [
            {
                "_id": "5f29dbaf81e97ab3a73e2c6a",
                "type": "EMAIL_SENT",
                "title": "An email was sent at [email protected] to inform the owner about their lost item.",
                "createdAt": "2020-08-04T22:05:35.808Z",
                "updatedAt": "2020-08-04T22:05:35.808Z"
            }
        ],
        "storagePlace": "Reception",
        "createdAt": "2020-08-04T22:05:35.381Z",
        "updatedAt": "2020-08-04T22:05:35.810Z"
    }
}
404: Not Found
The lost item or the location doesn't exist.
{
    "status": false,
    "message": "Item not found"
}
put
Update an item
https://api.joinfoundhero.com/v1/locations/:lid/items/:id
This endpoint allows you to update the lost item information.
Request
Response
Request
Path Parameters
lid
required
string
The unique ID of the location
id
required
string
The unique ID of the item
Body Parameters
description
required
string
A brief description of the lost item. Example: iPhone X
discoveryPlace
required
string
The place where the lost item was found
discoveryDate
required
string
The discovery date of the lost item in YYYY-MM-DD format
brand
optional
string
The name of the item's manufacturer
model
optional
string
The brand's model of the lost item
color
optional
string
The color of the item
storagePlace
optional
string
The place where the lost item is stored. You can use this parameter to override the location's default storage place.
notes
optional
string
Internal notes for your team
imageUrl
optional
string
An optional image URL for the lost item
shipping
required
object
A JSON object containing information about the item's shipment
shipping.weight
required
number
The weight of the lost item
shipping.weightUnit
optional
string
Weight unit. Acceptable values are lb, kg, oz, and g. The default value is kg. 
shipping.boxType
optional
string
Type of the packaging box. Please refer to the above packaging boxes table for all available values.
shipping.isDocument
optional
boolean
 A true or false value indicating whether the lost item consists of documents only
owner
optional
object
An optional JSON object containing information about the guest
owner.firstName
optional
string
The first name of the guest
owner.lastName
optional
string
The last name of the guest
owner.email
optional
string
The email address of the guest
owner.phone
optional
string
The phone number of the guest. It must include the country code.
Response
200: OK
The lost item is updated successfully.
{
    "status": true,
    "message": "Lost item is updated",
    "data": {
        "owner": {
            "firstName": "Amina",
            "lastName": "Mankid",
            "email": "[email protected]",
            "phone": "+49 175 78452548"
        },
        "shipping": {
            "weightUnit": "kg",
            "isDocument": false,
            "trackingNumbers": [],
            "totalPrice": 0,
            "taxes": 0,
            "fees": 0,
            "insurance": 0,
            "weight": 3.5,
            "boxType": "flat"
        },
        "ownShipment": false,
        "labelGenerated": false,
        "archived": false,
        "language": "en",
        "_id": "5f29dbaf81e97ab3a73e2c69",
        "location": {
            "contact": {
                "name": "David Backem",
                "email": "[email protected]",
                "email2": null,
                "phone": "+1 (455) 4567-8974"
            },
            "pickupTime": {
                "from": "08:00",
                "to": "14:00"
            },
            "storageDuration": 30,
            "active": true,
            "_id": "5f29a6a2af7c9568fe1437f7",
            "user": "5f1c11c77431601b2fff7459",
            "name": "Four Seasons Hotel Chicago",
            "permalink": "four-seasons-hotel-chicago-TIqfTF",
            "identifier": "8LiwV5xppI3s",
            "website": "https://www.fourseasons.com/chicago/",
            "type": "hotel",
            "storagePlace": "House Keeping",
            "address1": "120 E. Delaware Place",
            "city": "Chicago",
            "state": "IL",
            "zipCode": "60611",
            "country": "US",
            "createdAt": "2020-08-04T18:19:14.471Z",
            "updatedAt": "2020-08-04T20:47:28.688Z",
            "__v": 0,
            "address2": null,
            "description": "#1 hotel in Chicago",
            "latitude": null,
            "longitude": null,
            "logoUrl": "https://cdn.joinfoundhero.com/l/38acd909-e623-48e2-8c89-b01f5759afbd.png"
        },
        "identifier": "etxOKQlM5sAx",
        "description": "Macbook Pro 2020",
        "discoveryPlace": "Room #452",
        "discoveryDate": "2020-08-02T00:00:00.000Z",
        "lastEmailSent": "2020-08-04T22:05:35.361Z",
        "notes": "The item seems to be damaged.",
        "brand": "Apple",
        "model": "X Series",
        "color": "Silver",
        "status": "PENDING",
        "activity": [
            {
                "_id": "5f29dbaf81e97ab3a73e2c6a",
                "type": "EMAIL_SENT",
                "title": "An email was sent at [email protected] to inform the owner about their lost item.",
                "createdAt": "2020-08-04T22:05:35.808Z",
                "updatedAt": "2020-08-04T22:05:35.808Z"
            }
        ],
        "storagePlace": "Reception",
        "createdAt": "2020-08-04T22:05:35.381Z",
        "updatedAt": "2020-08-04T23:23:29.390Z",
        "__v": 1
    }
}
400: Bad Request
The request can not be completed due to data validation errors.
{
    "status": false,
    "message": "Item description is required"
}
404: Not Found
The lost item or the location doesn't exist.
{
    "status": false,
    "message": "Item not found"
}
get
Retrieve all items by location
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.

Request
Response
Request
Path Parameters
lid
required
string
The unique ID of the location 
Query Parameters
term
optional
string
Search term to filter-out lost items
limit
optional
integer
The number of results per page. The value must be between 10 and 100. The default value is 10.
page
optional
integer
The current page number. The default value is 1.
Response
200: OK
The operation is completed successfully.
{
    "status": true,
    "data": {
        "items": [
            {
                "owner": {
                    "firstName": "Amina",
                    "lastName": "Mankid",
                    "email": "[email protected]",
                    "phone": "+49 175 78452548"
                },
                "shipping": {
                    "weightUnit": "kg",
                    "isDocument": false,
                    "trackingNumbers": [],
                    "totalPrice": 0,
                    "taxes": 0,
                    "fees": 0,
                    "insurance": 0,
                    "weight": 3.5,
                    "boxType": "flat"
                },
                "ownShipment": false,
                "labelGenerated": false,
                "archived": false,
                "language": "en",
                "_id": "5f29dbaf81e97ab3a73e2c69",
                "location": "5f29a6a2af7c9568fe1437f7",
                "identifier": "etxOKQlM5sAx",
                "description": "Macbook Pro 2020",
                "discoveryPlace": "Room #452",
                "discoveryDate": "2020-08-02T00:00:00.000Z",
                "lastEmailSent": "2020-08-04T22:05:35.361Z",
                "notes": "The item seems to be damaged.",
                "brand": "Apple",
                "model": "X Series",
                "color": "Silver",
                "status": "PENDING",
                "activity": [
                    {
                        "_id": "5f29dbaf81e97ab3a73e2c6a",
                        "type": "EMAIL_SENT",
                        "title": "An email was sent at [email protected] to inform the owner about their lost item.",
                        "createdAt": "2020-08-04T22:05:35.808Z",
                        "updatedAt": "2020-08-04T22:05:35.808Z"
                    }
                ],
                "storagePlace": "Reception",
                "createdAt": "2020-08-04T22:05:35.381Z",
                "updatedAt": "2020-08-04T23:23:29.390Z"
            }
        ],
        "page": 1,
        "limit": 10,
        "count": 1,
        "totalPages": 1,
        "hasMore": false
    }
}
404: Not Found
The location doesn't exist.
{
    "status": false,
    "message": "Location not found"
}
delete
Delete an item
https://api.joinfoundhero.com/v1/locations/:lid/items/:id
This endpoint allows you to permanently delete a lost item. It cannot be undone.
Request
Response
Request
Path Parameters
lid
required
string
The unique ID of the location
id
required
string
The unique ID of the lost item
Response
200: OK
The item is deleted successfully.
{
    "status": true,
    "message": "Item deleted successfully"
}
404: Not Found
The lost item or the location doesn't exist.
{
    "status": false,
    "message": "Item not found"
}
post
Upload an image
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.
Request
Response
Request
Path Parameters
lid
required
string
The unique lD of the location
id
required
string
The unique ID of the lost item
Form Data Parameters
image
required
string
The file to upload. The file size must not exceed 10MB.
Response
200: OK
The image is uploaded successfully.
{
    "status": true,
    "message": "Image is uploaded successfully",
    "data": "https://cdn.joinfoundhero.com/i/b4ea1133-af0c-4559-300a-120fe08f421b.png"
}
400: Bad Request
There was no file uploaded or the file size exceeds 10MB.
{
    "status": false,
    "message": "File size must not exceed 10MB"
}
put
Update Item Status
https://api.joinfoundhero.com/v1/locations/:lid/items/:id/update-status
This endpoint allows you to update item status. The different item status are : INCOMPLETE PENDING INFO_COMPLETED FEE_PAID SHIPPED DELIVERED PICKUP DISCARD DONATE
Request
Response
Request
Path Parameters
id
required
string
The unique ID of the lost item
lid
required
string
The unique ID of the location
Body Parameters
status
required
string
The new status you want to affect to the item
Response
200: OK
{
    "status": true,
    "message": "Lost item status is updated",
    "data": {
        "owner": {
            "firstName": "test",
            "lastName": "test",
            "email": "[email protected]",
            "phone": "3333333333"
        },
        "shipping": {
            "weightUnit": "lb",
            "isDocument": false,
            "trackingNumbers": [],
            "totalPrice": 0,
            "taxes": 0,
            "fees": 0,
            "insurance": 0,
            "weight": 1,
            "boxType": "flat"
        },
        "ownShipment": false,
        "labelGenerated": false,
        "archived": false,
        "language": "en",
        "_id": "60ed6e0ecb90adfe2658a431",
        "location": "5ff8a9d374334bcad6a44140",
        "request": "60e99edfcb90adfe2658a42d",
        "identifier": "sgH7zHmBwTPP",
        "description": "test",
        "discoveryPlace": "test",
        "discoveryDate": "2021-07-06T00:00:00.000Z",
        "status": "PENDING",
        "activity": [
            {
                "_id": "60ed6e0ecb90adfe2658a432",
                "type": "EMAIL_SENT",
                "title": "An email was sent at [email protected] to inform the owner about their lost item.",
                "createdAt": "2021-07-13T10:42:22.293Z",
                "updatedAt": "2021-07-13T10:42:22.293Z"
            },
            {
                "_id": "60f81fe6fffb56842a569a7c",
                "type": "STATUS_CHANGED",
                "title": "Item status was changed to PENDING.",
                "createdAt": "2021-07-21T13:23:50.663Z",
                "updatedAt": "2021-07-21T13:23:50.663Z"
            }
        ],
        "createdAt": "2021-07-13T10:42:22.273Z",
        "updatedAt": "2021-07-21T13:23:50.664Z",
        "__v": 2,
        "lastEmailSent": "2021-07-13T10:42:22.288Z"
    }
}
Endpoints - Previous
Locations
Next - Endpoints
Requests
Last updated 2 weeks ago
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
Lost Items

Packaging Boxes

postCreate an item

getRetrieve an item

putUpdate an item

getRetrieve all items by location

deleteDelete an item

postUpload an image

putUpdate Item Status

post
Create an item

get
Retrieve an item

put
Update an item

get
Retrieve all items by location

delete
Delete an item

post
Upload an image

put
Update Item Status
