Found Hero API
Found Hero API
Home
Login
Overview
Authentication
Errors
Webhooks
Endpoints
Locations
Lost Items
Powered by GitBook

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

post
Create a location

https://api.joinfoundhero.com/v1/locations
This endpoint allows you to create a new location.
Request
Response
Request
Body Parameters
name
required
string
The name of the location
website
optional
string
The website URL of the location
logoUrl
optional
string
The logo URL of the location
description
optional
string
A brief description of the location
type
optional
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
required
integer
The number of days the location stores a lost item
storagePlace
required
string
The place where lost items are stored
address1
required
string
Address line 1
address2
optional
string
Address line 2 for additional information
city
required
string
The name of the city
state
optional
string
The name of the state
zipCode
required
string
Zipcode/postal code for this location
country
required
string
A 2-letter country code e.g. US
contact
required
object
A JSON object containing the contact information
contact.name
required
string
Full name of the person in charge of lost and found
contact.email
required
string
The primary email address of the person in charge of lost and found
contact.email2
optional
string
The secondary email address for receiving shipping labels
contact.phone
required
string
The phone number with country code for the contact person
pickupTime
optional
object
A JSON object containing from and to times during which the lost items can be picked up by the guests
pickupTime.from
optional
string
From pick-up time (HH:mm format) e.g. 10:00
pickupTime.to
optional
string
To pick-up time e.g. 14:00
Response
200: OK
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": "[email protected]",
            "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"
    }
}
400: Bad Request
Missing required fields.
{
    "status": false,
    "message": "Location name is required"
}

get
Retrieve a location

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.
Request
Response
Request
Path Parameters
id
required
string
The unique location ID
Response
200: OK
The location is retrieved successfully.
{
    "status": true,
    "data": {
        "contact": {
            "name": "David Backem",
            "email": "[email protected]",
            "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"
    }
}
404: Not Found
The location doesn't exist.
{
    "status": false,
    "message": "Location not found"
}

put
Update a location

https://api.joinfoundhero.com/v1/locations/:id
Updates the specified location by setting the values of the parameters passed.
Request
Response
Request
Path Parameters
id
required
string
The unique location ID
Body Parameters
name
required
string
The name of the location
website
optional
string
The website URL of the location
logoUrl
optional
string
The logo URL of the location
description
optional
string
A brief description of the location
type
optional
string
The type of location. e.g. hotel, airline, airport, etc. Refer to the above table to see all available location types.
storageDuration
required
integer
The number of days the location stores a lost item
storagePlace
required
string
The place where lost items are stored
address1
required
string
Address line 1
address2
optional
string
Address line 2 for additional information
city
required
string
The name of the city
state
optional
string
The name of the state
zipCode
required
string
Zipcode/postal code for this location
country
required
string
A 2-letter country code .e.g. US
contact
required
object
A JSON object containing the contact information
contact.name
required
string
The name of the person in charge of lost and found
contact.email
required
string
The primary email address of the person in charge of lost and found
contact.email2
optional
string
The secondary email address for receiving shipping labels
contact.phone
required
string
The phone number with country code for the contact person
pickupTime
optional
object
A JSON object containing from and to times during which the lost items can be picked up by the guests
pickupTime.from
optional
string
From pick-up time (HH:mm format) e.g. 10:00
pickupTime.to
optional
string
To pick-up time .e.g. 14:00
Response
200: OK
The location is updated successfully.
{
    "status": true,
    "message": "Location is updated",
    "data": {
        "contact": {
            "name": "David Backem",
            "email": "[email protected]",
            "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
    }
}
404: Not Found
The location doesn't exist.
{
    "status": false,
    "message": "Location not found"
}

get
Retrieve all locations

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.
Request
Response
Request
Query Parameters
term
optional
string
Search term to filter-out locations
limit
optional
integer
The number of results per page. The value must be between 10 and 100. The default value is 10
page
optional
integer
The current page number. The default value is 1
Response
200: OK
The operation is completed successfully.
{
    "status": true,
    "data": {
        "locations": [
            {
                "contact": {
                    "name": "David Backem",
                    "email": "[email protected]",
                    "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
    }
}

delete
Delete a location

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.
Request
Response
Request
Path Parameters
id
required
string
The unique location ID
Response
200: OK
The location is deleted successfully.
{
    "status": true,
    "message": "Location deleted successfully"
}
404: Not Found
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.

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.
Request
Response
Request
Path Parameters
id
required
string
The unique location ID
Form Data Parameters
logo
required
string
The file to upload. File size must not exceed 2MB.
Response
200: OK
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: Bad Request
There was no file uploaded or the file size exceeds 2MB.
{
    "status": false,
    "message": "File size must not exceed 2MB"
}
Previous
Webhooks
Next - Endpoints
Lost Items
Last updated 8 months ago
Contents
Available location types
post
Create a location
get
Retrieve a location
put
Update a location
get
Retrieve all locations
delete
Delete a location
post
Upload a logo