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.

{
    "status": true,
    "message": "Lost item created successfully",
    "data": {
        "owner": {
            "firstName": "Amina",
            "lastName": "Mankid",
            "email": "amina.mankid@hotmail.com",
            "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 amina.mankid@hotmail.com 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"
    }
}

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

{
    "status": true,
    "data": {
        "owner": {
            "firstName": "Amina",
            "lastName": "Mankid",
            "email": "amina.mankid@hotmail.com",
            "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": "david.backem@gmail.com",
                "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 amina.mankid@hotmail.com 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"
    }
}

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.

{
    "status": true,
    "message": "Lost item is updated",
    "data": {
        "owner": {
            "firstName": "Amina",
            "lastName": "Mankid",
            "email": "amina.mankid@hotmail.com",
            "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": "david.backem@gmail.com",
                "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 amina.mankid@hotmail.com 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
    }
}

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.

{
    "status": true,
    "data": {
        "items": [
            {
                "owner": {
                    "firstName": "Amina",
                    "lastName": "Mankid",
                    "email": "amina.mankid@hotmail.com",
                    "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 amina.mankid@hotmail.com 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
    }
}

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

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

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.

{
    "status": true,
    "message": "Image is uploaded successfully",
    "data": "https://cdn.joinfoundhero.com/i/b4ea1133-af0c-4559-300a-120fe08f421b.png"
}

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

{
    "status": true,
    "message": "Lost item status is updated",
    "data": {
        "owner": {
            "firstName": "test",
            "lastName": "test",
            "email": "test@test.com",
            "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 test@test.com 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"
    }
}

Last updated