> 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/locations.md). # Locations The Found Hero API allows you to programmatically manage your locations. A location can be a hotel, airport, airline, amusement park, shopping mall, zoo, event, etc. ### Available location types Found Hero currently supports the following location types: | Value | Description | | ----------------- | ------------------------ | | `airline` | Airline | | `airport` | Airport | | `amusement-park` | Amusement Park | | `event` | Event/Festival | | `city-government` | City & Government | | `golf-course` | Golf Course | | `hospital` | Hospital | | `hotel` | Hotel/Resort (Default) | | `transportation` | Public Transportation | | `restaurant` | Restaurant | | `shopping-mall` | Shopping Mall | | `zoo` | Zoo/Animal Park/Aquarium | | `other` | None of the above | ## Create a location `POST` `https://api.joinfoundhero.com/v1/locations` This endpoint allows you to create a new location. #### Request Body | Name | Type | Description | | --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | The name of the location | | website | string | The website URL of the location | | logoUrl | string | The logo URL of the location | | description | string | A brief description of the location | | type | string |

The type of location. e.g. hotel, airline, airport, etc. Refer to the above table to see all available location types.
Default value is hotel

| | storageDuration | integer | The number of days the location stores a lost item | | storagePlace | string | The place where lost items are stored | | address1 | string | Address line 1 | | address2 | string | Address line 2 for additional information | | city | string | The name of the city | | state | string | The name of the state | | zipCode | string | Zipcode/postal code for this location | | country | string | A 2-letter country code e.g. `US` | | contact | object | A JSON object containing the contact information | | contact.name | string | Full name of the person in charge of lost and found | | contact.email | string | The primary email address of the person in charge of lost and found | | contact.email2 | string | The secondary email address for receiving shipping labels | | contact.phone | string | The phone number with country code for the contact person | | pickupTime | object | A JSON object containing from and to times during which the lost items can be picked up by the guests | | pickupTime.from | string | From pick-up time (HH:mm format) e.g. `10:00` | | pickupTime.to | string | To pick-up time e.g. `14:00` | {% tabs %} {% tab title="200 Location is created successfully." %} ```javascript { "status": true, "message": "Location is created", "data": { "pickupTime": { "from": "10:00", "to": "14:00" }, "storageDuration": 45, "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", "contact": { "name": "David Backem", "email": "david.backem@gmail.com", "phone": "+1 (455) 4567-8974" }, "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-04T18:19:14.471Z" } } ``` {% endtab %} {% tab title="400 Missing required fields." %} ```javascript { "status": false, "message": "Location name is required" } ``` {% endtab %} {% endtabs %} ## Retrieve a location `GET` `https://api.joinfoundhero.com/v1/locations/:id` Retrieves the details of a location that has previously been created. Supply the unique location ID that was returned from your previous request, and Found Hero will return the corresponding location information. #### Path Parameters | Name | Type | Description | | ---- | ------ | ---------------------- | | id | string | The unique location ID | {% tabs %} {% tab title="200 The location is retrieved successfully." %} ```javascript { "status": true, "data": { "contact": { "name": "David Backem", "email": "david.backem@gmail.com", "phone": "+1 (455) 4567-8974" }, "pickupTime": { "from": "10:00", "to": "14:00" }, "storageDuration": 45, "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-04T18:19:14.471Z" } } ``` {% endtab %} {% tab title="404 The location doesn't exist." %} ```javascript { "status": false, "message": "Location not found" } ``` {% endtab %} {% endtabs %} ## Update a location `PUT` `https://api.joinfoundhero.com/v1/locations/:id` Updates the specified location by setting the values of the parameters passed. #### Path Parameters | Name | Type | Description | | ---- | ------ | ---------------------- | | id | string | The unique location ID | #### Request Body | Name | Type | Description | | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- | | name | string | The name of the location | | website | string | The website URL of the location | | logoUrl | string | The logo URL of the location | | description | string | A brief description of the location | | type | string | The type of location. e.g. hotel, airline, airport, etc. Refer to the above table to see all available location types. | | storageDuration | integer | The number of days the location stores a lost item | | storagePlace | string | The place where lost items are stored | | address1 | string | Address line 1 | | address2 | string | Address line 2 for additional information | | city | string | The name of the city | | state | string | The name of the state | | zipCode | string | Zipcode/postal code for this location | | country | string | A 2-letter country code .e.g. `US` | | contact | object | A JSON object containing the contact information | | contact.name | string | The name of the person in charge of lost and found | | contact.email | string | The primary email address of the person in charge of lost and found | | contact.email2 | string | The secondary email address for receiving shipping labels | | contact.phone | string | The phone number with country code for the contact person | | pickupTime | object | A JSON object containing from and to times during which the lost items can be picked up by the guests | | pickupTime.from | string | From pick-up time (HH:mm format) e.g. `10:00` | | pickupTime.to | string | To pick-up time .e.g. `14:00` | {% tabs %} {% tab title="200 The location is updated successfully." %} ```javascript { "status": true, "message": "Location is updated", "data": { "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-04T18:42:13.114Z", "__v": 0, "address2": null, "description": "#1 hotel in Chicago", "latitude": null, "longitude": null } } ``` {% endtab %} {% tab title="404 The location doesn't exist." %} ```javascript { "status": false, "message": "Location not found" } ``` {% endtab %} {% endtabs %} ## Retrieve all locations `GET` `https://api.joinfoundhero.com/v1/locations?term=four&limit=10&page=1` Retrieve all locations created by the user. By default, this method returns a set of top 10 locations sorted by their names.\ \ You can also supply an optional query parameter called `term` to search locations by their names, descriptions, contact emails, and contact names.\ \ This method also supports pagination. You can use `limit` and `page`\ query parameters to control pagination. #### Query Parameters | Name | Type | Description | | ----- | ------- | --------------------------------------------------------------------------------------------------- | | term | string | Search term to filter-out locations | | 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": { "locations": [ { "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-04T18:42:13.114Z", "__v": 0, "address2": null, "description": "#1 hotel in Chicago", "latitude": null, "longitude": null } ], "page": 1, "limit": 10, "count": 1, "totalPages": 1, "hasMore": false } } ``` {% endtab %} {% endtabs %} ## Delete a location `DELETE` `https://api.joinfoundhero.com/v1/locations/:id` Permanently deletes a location. It cannot be undone. Also immediately delete all lost items associated with this location. #### Path Parameters | Name | Type | Description | | ---- | ------ | ---------------------- | | id | string | The unique location ID | {% tabs %} {% tab title="200 The location is deleted successfully." %} ```javascript { "status": true, "message": "Location deleted successfully" } ``` {% endtab %} {% tab title="404 The location doesn't exist." %} ```javascript { "status": false, "message": "Location not found" } ``` {% endtab %} {% endtabs %} {% hint style="danger" %} Be careful while deleting a location. It will also immediately delete all active and shipped lost items associated with this location. {% endhint %} ## Upload a logo `POST` `https://api.joinfoundhero.com/v1/locations/:id/upload-logo` This endpoint allows you to upload a logo for a location. For this particular request, you must set the request `Content-Type` header to `multipart/form-data`. #### Path Parameters | Name | Type | Description | | ---- | ------ | ---------------------- | | id | string | The unique location ID | #### Request Body | Name | Type | Description | | ---- | ------ | -------------------------------------------------- | | logo | string | The file to upload. File size must not exceed 2MB. | {% tabs %} {% tab title="200 The logo is upload successfully." %} ```javascript { "status": true, "message": "Logo is uploaded successfully", "data": "https://cdn.joinfoundhero.com/l/0d5c6820-4402-d1dc-4392-a6751fd8dcd1.png" } ``` {% endtab %} {% tab title="400 There was no file uploaded or the file size exceeds 2MB." %} ```javascript { "status": false, "message": "File size must not exceed 2MB" } ``` {% 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/locations.md?ask= ``` 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.