Locations

You can use the Faundit API v2 to manage locations.

A Location is a hotel, venue, or property that is part of the account holder's group. Your organisation can consist of multiple Locations where different individuals can be designated as Users to access one or more Locations.

A manager might need access to multiple Locations while an employee only needs access to a specific Location.

In our API, a Location is uniquely identified by the `locationID`. It will be displayed when retrieving Items, customer Requests, and Users associated with a Location.

A precise "Location address" and "package collection instructions" are crucial information for arranging package pickups with our shipping providers.

Create a new Location

POST https://{environment}.faundit.com/api/v2/locations

IMPORTANT: When a new Location is created, no User is automatically attached to it. You must explicitly assign Users to the Location as part of your setup process.

Request body

Name	Type	Description
name*	string	Name of the Location
address*	object	A JSON object containing data about the Location's address.
address.address*	string	Address of the Location. Example: "Graham St."
address.addressNumber*	string	House number of the Location. Example: "36"
address.city*	string	City of the Location. Example: "London"
address.countryID*	string	Alpha-2 country code of the Location. Example: "GB" *You’ll find the values in the section “Country Reference”. Use the abbreviation (value) of the key, e.g. “GB” for the United Kingdom.
address.state	string	State of the Location (Australia, Canada & USA only). Example: "NY" Use abbreviations accordingly to our State Reference page.
address.zipCode*	string	Zip code of the Location. Example: "N1 8GJ"
contactDetails*	object	A JSON object containing data about the Location's contact details.
contactDetails.contactPerson*	string	Name of the contact person in charge of Faundit at the Location.
contactDetails.contactEmail*	string	Contact e-mail address of the contact person in charge of Faundit at the Location.
contactDetails.contactEmailCC	string	CC'ed mail addresses, separate multiple recipients with a comma (,).
contactDetails.phoneNumber*	string	Contact phone number of the contact person in charge of Faundit at the Location.
itemStorageDays	number	Default number of days the Location stores items. Defaults to 90.
daysBeforeRequestExpires	number	This field indicates the number of days after creation that a Request will expire. Defaults to 90.
storageAfterItemStorageDays	number	If a guest selects to pick up an item within your regular storage time, this is the amount of days they will have a timespan to collect it in. Example: Storange time: 1 day Extra storage time: 7 days Guests can only respond to the found item within the first day. If they do, they can choose to pick it up within the following 7 days. It expires after the first day if no action is made. Defaults to 0.
pickupDetails*	object	A JSON object containing data about the Location's pickup details.
pickupDetails.pickupLocation	string	The pickup location for packages at the Location. Max. 12 characters. Defaults to "Reception"
pickupDetails.pickupIntructions	string	Special pickup instructions for packages at the Location. Max. 57 characters. Example: "Use the front door"
reference	string	A reference to the Location. Example: "Branch 1"
options	object	A JSON object with information on the Location's Faundit options.
options.weightUnit	string	Weight unit used in the Faundit platform. Possible values: "kg" or "lb" Defaults to "kg"
options.dimensionUnit	string	Dimension unit used in the Faundit platform. Possible values: "cm" or "in" Defaults to "cm"

Response

200: OK

{
    "locationID": "14dbb67jc32e9f37b9136852bc36a389:ebcbd6a13",
    "address": {
        "address": "Graham St.",
        "addressNumber": "36",
        "city": "London",
        "zipCode": "N1 8GJ",
        "state": null,
        "countryID": "GB"
    },
    "itemStorageDays": 55,
    "storageAfterItemStorageDays": 10,
    "daysBeforeRequestExpires": 90,
    "contactDetails": {
        "contactEmail": "[e-mail]",
        "contactEmailCC": null,
        "contactPerson": "Jose Jonason",
        "phoneNumber": "[phone]"
    },
    "pickupDetails": {
        "pickupIntructions": "Use the front door",
        "pickupLocation": "Reception"
    },
    "options": {
        "weightUnit": "lb",
        "dimensionUnit": "in"
    },
    "createdAt": "2020-09-02 07:33:16.292",
    "updatedAt": null,
    "reference": "Branch 1",
}

Return all Locations

GET https://{environment}.faundit.com/api/v2/locations

200: OK

[
    {
        "locationID": "14dbb67jc32e9f37b9136852bc36a389:ebcbd6a13",
        "address": {
            "address": "Graham St.",
            "addressNumber": "36",
            "city": "London",
            "zipCode": "N1 8GJ",
            "state": null,
            "countryID": "GB"
        },
        "itemStorageDays": 55,
        "storageAfterItemStorageDays": 10,
        "daysBeforeRequestExpires": 90,
        "contactDetails": {
            "contactEmail": "[e-mail]",
            "contactEmailCC": null,
            "contactPerson": "Jose Jonason",
            "phoneNumber": "[phone]"
        },
        "pickupDetails": {
            "pickupIntructions": "Use the front door",
            "pickupLocation": "Reception"
        },
        "options": {
            "weightUnit": "lb",
            "dimensionUnit": "in"
        },
        "createdAt": "2020-09-02 07:33:16.292",
        "updatedAt": "2023-12-11 13:17:38.566", 
        "reference": "Branch 1",
        
    },
    {
        "locationID": "56ac29bd30b73c88c36142d5068e53e6:cccfad1f07",
        "address": {
            "address": "Graham St.",
            "addressNumber": "36",
            "city": "London",
            "zipCode": "N1 8GJ",
            "state": null,
            "countryID": "GB"
        },
        "itemStorageDays": 55,
        "storageAfterItemStorageDays": 10,
        "daysBeforeRequestExpires": 90,
        "contactDetails": {
            "contactEmail": "[e-mail]",
            "contactEmailCC": null,
            "contactPerson": "Jose Jonason",
            "phoneNumber": "[phone]"
        },
        "pickupDetails": {
            "pickupIntructions": "Use the front door",
            "pickupLocation": "Reception"
        },
        "options": {
            "weightUnit": "lb",
            "dimensionUnit": "in"
        },
        "createdAt": "2020-09-02 07:33:16.292",
        "updatedAt": "2023-12-11 13:17:38.566",
        
        "reference": "Branch 2",
    }
]

Return a single Location

GET https://{environment}.faundit.com/api/v2/locations/:locationID

Query Parameters

Name	Type	Description
locationID*	string	Location unique identifier. Example: 14dbb67jc32e9f37b9136852bc36a389:ebcbd6a13

200: OK

{
    "locationID": "14dbb67jc32e9f37b9136852bc36a389:ebcbd6a13",
    "address": {
        "address": "Graham St.",
        "addressNumber": "36",
        "city": "London",
        "zipCode": "N1 8GJ",
        "state": null,
        "countryID": "GB"
    },
    "itemStorageDays": 55,
    "storageAfterItemStorageDays": 10,
    "daysBeforeRequestExpires": 90,
    "contactDetails": {
        "contactEmail": "[e-mail]",
        "contactEmailCC": null,
        "contactPerson": "Jose Jonason",
        "phoneNumber": "[phone]"
    },
    "pickupDetails": {
        "pickupIntructions": "Use the front door",
        "pickupLocation": "Reception"
    },
    "options": {
        "weightUnit": "lb",
        "dimensionUnit": "in"
    },
    "createdAt": "2020-09-02 07:33:16.292",
    "updatedAt": "2023-12-11 13:17:38.566",
        
    "reference": "Branch 1",
}

Update a Location

PUT https://{environment}.faundit.com/api/v2/locations/:locationID

This endpoint allows you to update details of a specific location.

Path Parameters

Name	Type	Description
locationID*	string	Location unique identifier. Example: 14dbb67jc32e9f37b9136852bc36a389:ebcbd6a13

Request Body

Name	Type	Description
address.address	string	Address of the Location. Example: "Graham St."
address	object	A JSON object containing data about the Location's address.
address.countryID	string	Alpha-2 country code of the Location. Example: "GB" *You’ll find the values in the section “Country Reference”. Use the abbreviation (value) of the key, e.g. “GB” for the United Kingdom.
address.city	string	City of the Location. Example: "London"
address.state	string	State of the Location (Australia, Canada & USA only). Example: "NY" Use abbreviations accordingly to our State Reference page.
address.zipCode	string	Zip code of the Location. Example: "N1 8GJ"
address.addressNumber	string	House number of the Location. Example: "36"
contactDetails.contactEmailCC	string	CC'ed mail addresses, separate multiple recipients with a comma (,).
contactDetails.contactEmail	string	Contact e-mail address of the contact person in charge of Faundit at the Location.
contactDetails.contactPerson	string	Name of the contact person in charge of Faundit at the Location.
contactDetails	object	A JSON object containing data about the Location's contact details.
itemStorageDays	number	Default number of days the Location stores items. Defaults to 90.
storageAfterItemStorageDays	number	If a guest selects to pick up an item within your regular storage time, this is the amount of days they will have a timespan to collect it in. Example: Storange time: 1 day Extra storage time: 7 days Guests can only respond to the found item within the first day. If they do, they can choose to pick it up within the following 7 days. It expires after the first day if no action is made. Leave this at 0 if you aren't sure what it's for.
contactDetails.phoneNumber	string	Contact phone number of the contact person in charge of Faundit at the Location.
pickupDetails	object	A JSON object containing data about the Location's pickup details.
pickupDetails.pickupLocation	string	The pickup location for packages at the Location. Max. 12 characters. Example: "Reception"
pickupDetails.pickupIntructions	string	Special pickup instructions for packages at the Location. Max. 57 characters. Example: "Use the front door"
reference	string	A reference to the Location. Example: "Branch 1"

200: OK Location updated successfully.

{
    "locationID": "14dbb67jc32e9f37b9136852bc36a389:ebcbd6a13",
    "address": {
        "address": "Graham St.",
        "addressNumber": "36",
        "city": "London",
        "zipCode": "N1 8GJ",
        "state": null,
        "countryID": "GB"
    },
    "itemStorageDays": 55,
    "storageAfterItemStorageDays": 10,
    "daysBeforeRequestExpires": 90,
    "contactDetails": {
        "contactEmail": "[e-mail]",
        "contactEmailCC": null,
        "contactPerson": "Jose Jonason",
        "phoneNumber": "[phone]"
    },
    "pickupDetails": {
        "pickupIntructions": "Use the front door",
        "pickupLocation": "Reception"
    },
    "options": {
        "weightUnit": "lb",
        "dimensionUnit": "in"
    },
    "createdAt": "2020-09-02 07:33:16.292",
    "updatedAt": "2023-12-11 13:17:38.566"
    
    "reference": "Branch 1"
}

Return all Users for a specific Location

GET https://{environment}.faundit.com/api/v2/locations/:locationID/users

This endpoint retrieves a list of all Users granted access to a particular Location within your account. This empowers you to manage User permissions and access control effectively, ensuring individuals can only interact with relevant Locations.

Path Parameters

Name	Type	Description
locationID*	string	Location unique identifier. Example: 14dbb67jc32e9f37b9136852bc36a389:ebcbd6a13

200: OK

[
    {
        "ID": 113,
        "username": "jose_faundit",
        "locationAccess": {
            "locationIDs": [
                "14dbb67jc32e9f37b9136852bc36a389:ebcbd6a13"
            ],
            "regionIDs": [],
            "countryIDs": [
                "DK"
            ],
            "accessAllLocations": false
        },
        "email": null,
        "email_validated": true,
        "userRole": "group_admin",
        "createdAt": "2020-09-02 07:33:16.844",
        "updatedAt": "2023-12-20 08:37:09.231",
        "lastLoginAt": "2024-01-24 11:22:40.371"
    },
    {
        "ID": 114,
        "username": "jonas_faundit",
         "locationAccess": {
            "locationIDs": [
                "14dbb67jc32e9f37b9136852bc36a389:ebcbd6a13"
            ],
            "regionIDs": [],
            "countryIDs": [],
            "accessAllLocations": false
        },
        "email": null,
        "email_validated": true,
        "userRole": "property_subuser",
        "createdAt": "2020-09-02 07:33:16.844",
        "updatedAt": "2023-12-20 08:37:09.231",
        "lastLoginAt": "2024-01-24 11:22:40.371"
    }
]

Return all Customer Requests for a specific Location

GET https://{environment}.faundit.com/api/v2/locations/:locationID/requests

This endpoint retrieves a list of all Customer Requests associated with a particular Location within your account. This empowers you to efficiently manage customer interactions and resolve issues related to a specific Location.

Path Parameters

Name	Type	Description
locationID*	string	Location unique identifier. Example: 14dbb67jc32e9f37b9136852bc36a389:ebcbd6a13

Query Parameters

Name	Type	Description
limit	number
page	number

200: OK

{
    "requests": [
        {
            "ID": 33719,
            "departuredDate": "2023-12-01 00:00:00.000",
            "location": "Room 311",
            "request": "iPhone charger",
            "requestNumber": 33,
            "owner": {
                "name": "Jose Jonason",
                "email": "[e-mail]",
                "phoneNumber": "[phone]"
            },
            "matchedItemID": null,
            "locationID": "23a10jw221197jc:abc12345",
            "imageUrl": null,
            "resolved": false,
            "status": "waiting-guest-response",
            "askForDetails": {
                "question": "What color is it?",
                "answer": "It's a white charger."
            },
            "createdAt": "2023-11-30 10:44:39.188",
            "updatedAt": "2023-12-06 10:54:11.217"
        }
    ],
    "hasMore": true,
    "limit": 1,
    "page": 1
}

Return all Lost Items for a specific Location

GET https://{environment}.faundit.com/api/v2/locations/:locationID/items

This endpoint retrieves a list of all Lost Items registered at a particular Location within your account.

Path Parameters

Name	Type	Description
locationID*	string	Location unique identifier. Example: 14dbb67jc32e9f37b9136852bc36a389:ebcbd6a13

Query Parameters

Name	Type	Description
limit	number
page	number

200: OK

{
    "items": [
        {
            "ID": 438395,
            "item": "Sunglasses",
            "location": "213",
            "departuredDate": "2023-12-07 10:35:06.999",
            "itemNumber": 1181,
            "owner": {
                "firstName": null,
                "lastName": null,
                "contactEmail": "[e-mail]",
                "phoneNumber": null,
                "address": {
                    "address": null,
                    "address2": null,
                    "city": null,
                    "countryID": null,
                    "state": null,
                    "companyName": null
                }
            },
            "shipping": {
                "weight": {
                    "ID": 1,
                    "title": "Less than 2 kg."
                },
                "dimensions": {
                    "fitsInFaunditPackaging": true,
                    "width": null,
                    "lenght": null,
                    "height": null
                },
                "shippingLabel": null,
                "trackingUrl": null,
                "proformaUrl": null,
                "receiptUrl": null
            },
            "internalNotes": null,
            "itemStorage": "First drawer storage room.",
            "imageUrl": null,
            "ownShipment": false,
            "status": "waiting-response",
            "locationID": "23a10jw221197jc:abc12345",
            "ownerPickupComment": null,
            "createdAt": "2023-12-07 10:36:17.263",
            "updatedAt": null,
            "itemPaidAt": null,
            "ownerPickupDate": null,
            "pickupBookedAt": null,
            "customStorageDays": null
        }
    ],
    "hasMore": true,
    "limit": 1,
    "page": 1
}

Return all communication languages for a specific Location

GET https://{environment}.faundit.com/api/v2/locations/:locationID/languages

Languages are used in communication (email/SMS) with customers through the API.

This endpoint returns a list of languages available for your Location to communicate with Item owners through email and SMS.

Languages are differentiated by scope to indicate at what level the Language has been created. Read more about Languages here.

The Language with default being true will be the Language used in customer communication if no locationID is set on an Item.

To set a Language as default, please do so in the Faundit Platform.

Path Parameters

Name	Type	Description
locationID*	string	Location unique identifier. Example: 14dbb67jc32e9f37b9136852bc36a389:ebcbd6a13

200: OK

[
    {
        "ID": 230,
        "language": "English",
        "createdAt": "2021-10-06 11:11:33.564",
        "updatedAt": "2023-03-16 14:00:02.391",
        "default": true,
        "scope": "all"
    },
    {
        "ID": 231,
        "language": "Catalan",
        "createdAt": "2021-11-18 15:25:36.909",
        "updatedAt": null,
        "default": false,
        "scope": "location"
    },
    {
        "ID": 232,
        "language": "Danish",
        "createdAt": "2021-11-24 12:36:00.312",
        "updatedAt": null,
        "default": false,
        "scope": "location"
    }
]

Deactivate a Location

PUT https://{environment}.faundit.com/api/v2/locations/:locationID/deactivate

Deactivate an existing Location.

This removes access to a Location for all Users.

Path Parameters

Name	Type	Description
locationID*	string	Location unique identifier. Example: 14dbb67jc32e9f37b9136852bc36a389:ebcbd6a13

200: OK

"Location deactivated successfully."

Reactivate a Location

PUT https://{environment}.faundit.com/api/v2/locations/:locationID/reactivate

Reactivate an existing Location.

This reactivates access to the Location for all Users who previously had access to the Location.

Path Parameters

Name	Type	Description
locationID*	string	Location unique identifier. Example: 14dbb67jc32e9f37b9136852bc36a389:ebcbd6a13

200: OK

"Location reactivated successfully."