> For the complete documentation index, see [llms.txt](https://docs.joinfoundhero.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.joinfoundhero.com/endpoints/items.md).

# 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  |

{% hint style="info" %}
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.
{% endhint %}

## Create an item

<mark style="color:green;">`POST`</mark> `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.                                                      |

{% tabs %}
{% tab title="200 The lost item is created successfully." %}

```javascript
{
    "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"
    }
}
```

{% endtab %}

{% tab title="400 The request can not be completed due to data validation errors." %}

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

{% endtab %}

{% tab title="404 The location doesn't exist." %}

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

{% endtab %}
{% endtabs %}

## Retrieve an item

<mark style="color:blue;">`GET`</mark> `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.&#x20;

#### Path Parameters

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

{% tabs %}
{% tab title="200 The lost item is retrieved successfully." %}

```javascript
{
    "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"
    }
}
```

{% endtab %}

{% tab title="404 The lost item or the location doesn't exist." %}

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

{% endtab %}
{% endtabs %}

## Update an item

<mark style="color:orange;">`PUT`</mark> `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.                                                      |

{% tabs %}
{% tab title="200 The lost item is updated successfully." %}

```javascript
{
    "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
    }
}
```

{% endtab %}

{% tab title="400 The request can not be completed due to data validation errors." %}

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

{% endtab %}

{% tab title="404 The lost item or the location doesn't exist." %}

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

{% endtab %}
{% endtabs %}

## Retrieve all items by location

<mark style="color:blue;">`GET`</mark> `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.<br>

#### 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`.                                                   |

{% tabs %}
{% tab title="200 The operation is completed successfully." %}

```javascript
{
    "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
    }
}
```

{% endtab %}

{% tab title="404 The location doesn't exist." %}

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

{% endtab %}
{% endtabs %}

## Delete an item

<mark style="color:red;">`DELETE`</mark> `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 |

{% tabs %}
{% tab title="200 The item is deleted successfully." %}

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

{% endtab %}

{% tab title="404 The lost item or the location doesn't exist." %}

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

{% endtab %}
{% endtabs %}

## Upload an image

<mark style="color:green;">`POST`</mark> `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. |

{% tabs %}
{% tab title="200 The image is uploaded successfully." %}

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

{% endtab %}

{% tab title="400 There was no file uploaded or the file size exceeds 10MB." %}

```javascript
{
    "status": false,
    "message": "File size must not exceed 10MB"
}
```

{% endtab %}
{% endtabs %}

## Update Item Status

<mark style="color:orange;">`PUT`</mark> `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 |

{% tabs %}
{% tab title="200 " %}

```
{
    "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"
    }
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.joinfoundhero.com/endpoints/items.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.