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