# 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 `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. | {% 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 `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 | {% 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 `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. | {% 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 `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`. | {% 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 `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 | {% 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 `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. | {% 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 `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 | {% 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 %}