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

Name	Type	Description
lid	string	The unique ID of the location

Request Body

Name	Type	Description
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.

200 The lost item is created successfully.

{
    "status": true,
    "message": "Lost item created successfully",
    "data": {
        "owner": {
            "firstName": "Amina",
            "lastName": "Mankid",
            "email": "[e-mail]",
            "phone": "[phone]"
        },
        "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 [e-mail] 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 The request can not be completed due to data validation errors.

{
    "status": false,
    "message": "Item description is required"
}

404 The location doesn't exist.

{
    "status": false,
    "message": "Location not found"
}

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

Name	Type	Description
lid	string	The unique ID of the location
id	string	The unique ID of the lost item

200 The lost item is retrieved successfully.

{
    "status": true,
    "data": {
        "owner": {
            "firstName": "Amina",
            "lastName": "Mankid",
            "email": "[e-mail]",
            "phone": "[phone]"
        },
        "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": "[e-mail]",
                "email2": null,
                "phone": "[phone]"
            },
            "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 [e-mail] 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 The lost item or the location doesn't exist.

{
    "status": false,
    "message": "Item not found"
}

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

Name	Type	Description
lid	string	The unique ID of the location
id	string	The unique ID of the item

Request Body

Name	Type	Description
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.

200 The lost item is updated successfully.

{
    "status": true,
    "message": "Lost item is updated",
    "data": {
        "owner": {
            "firstName": "Amina",
            "lastName": "Mankid",
            "email": "[e-mail]",
            "phone": "[phone]"
        },
        "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": "[e-mail]",
                "email2": null,
                "phone": "[phone]"
            },
            "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 [e-mail] 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 The request can not be completed due to data validation errors.

{
    "status": false,
    "message": "Item description is required"
}

404 The lost item or the location doesn't exist.

{
    "status": false,
    "message": "Item not found"
}

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

Name	Type	Description
lid	string	The unique ID of the location

Query Parameters

Name	Type	Description
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.

200 The operation is completed successfully.

{
    "status": true,
    "data": {
        "items": [
            {
                "owner": {
                    "firstName": "Amina",
                    "lastName": "Mankid",
                    "email": "[e-mail]",
                    "phone": "[phone]"
                },
                "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 [e-mail] 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 The location doesn't exist.

{
    "status": false,
    "message": "Location not found"
}

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

Name	Type	Description
lid	string	The unique ID of the location
id	string	The unique ID of the lost item

200 The item is deleted successfully.

{
    "status": true,
    "message": "Item deleted successfully"
}

404 The lost item or the location doesn't exist.

{
    "status": false,
    "message": "Item not found"
}

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

Name	Type	Description
lid	string	The unique lD of the location
id	string	The unique ID of the lost item

Request Body

Name	Type	Description
image	string	The file to upload. The file size must not exceed 10MB.

200 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 There was no file uploaded or the file size exceeds 10MB.

{
    "status": false,
    "message": "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

Name	Type	Description
id	string	The unique ID of the lost item
lid	string	The unique ID of the location

Request Body

Name	Type	Description
status	string	The new status you want to affect to the item

200

{
    "status": true,
    "message": "Lost item status is updated",
    "data": {
        "owner": {
            "firstName": "test",
            "lastName": "test",
            "email": "[e-mail]",
            "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 [e-mail] 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"
    }
}