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

200 Location is created successfully.

{
    "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": "[e-mail]",
            "phone": "[phone]"
        },
        "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"
    }
}

400 Missing required fields.

{
    "status": false,
    "message": "Location name is required"
}

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

200 The location is retrieved successfully.

{
    "status": true,
    "data": {
        "contact": {
            "name": "David Backem",
            "email": "[e-mail]",
            "phone": "[phone]"
        },
        "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"
    }
}

404 The location doesn't exist.

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

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

200 The location is updated successfully.

{
    "status": true,
    "message": "Location is updated",
    "data": {
        "contact": {
            "name": "David Backem",
            "email": "[e-mail]",
            "email2": null,
            "phone": "[phone]"
        },
        "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
    }
}

404 The location doesn't exist.

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

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

200 The operation is completed successfully.

{
    "status": true,
    "data": {
        "locations": [
            {
                "contact": {
                    "name": "David Backem",
                    "email": "[e-mail]",
                    "email2": null,
                    "phone": "[phone]"
                },
                "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
    }
}

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

200 The location is deleted successfully.

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

404 The location doesn't exist.

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

Be careful while deleting a location. It will also immediately delete all active and shipped lost items associated with this location.

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.

200 The logo is upload successfully.

{
    "status": true,
    "message": "Logo is uploaded successfully",
    "data": "https://cdn.joinfoundhero.com/l/0d5c6820-4402-d1dc-4392-a6751fd8dcd1.png"
}

400 There was no file uploaded or the file size exceeds 2MB.

{
    "status": false,
    "message": "File size must not exceed 2MB"
}