App Registration
How an external app (partner, POS, CRM) registers and gets access to the Hostme API — appId, keys and authorization.
This page describes how an external app (partner, POS, CRM) gets access to the Hostme API:
how to issue a partner token, find your list of restaurants and partnerId, how vendor app
registration works and what appId is.
General authentication rules are in Authentication. This page covers what is specific to partner/vendor access.
Some request and response schemas in this part of the spec are not captured (the body is empty or the response is not described). Such places are marked explicitly — the exact format is agreed with the Hostme team during onboarding.
Partner token
Partner token
POST /api/core/admin/account/partners/token
Issues a token for partner access. Request body — PartnerTokenRequest.
Note. In the spec the
PartnerTokenRequestbody is empty — the actual fields (partner identifier, secret, etc.) are not described in the export. The request format and the set of credentials are agreed during onboarding with the Hostme team.
curl -X POST https://api.hostmeapp.com/api/core/admin/account/partners/token \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ }'The resulting token is used as Authorization: Bearer $TOKEN in all other requests.
Endpoint behavior may depend on the token type (Hostme / Partner / Vendor) —
for example, when creating a reservation the booking is made on behalf of the partner
or the external app.
Who am I and my restaurants
GET /api/core/admin/account/me
Returns UserInfoContract — the current account’s data, its partnerId and the list of restaurants
it has access to. This is the first request after obtaining a token: from it you take the restaurantId
for all other calls and the partnerId for partner scenarios.
Key response fields (UserInfoContract)
| Field | Type | Description |
|---|---|---|
id | string | User identifier |
userName | string | Login |
email | string | |
fullName | string | Name |
language | string | Language |
partnerId | string | Partner identifier (if the account is a partner account) |
roles | array | Roles per restaurant (RoleInfoContract: restaurantId, restaurantName, name, type) |
restaurants | array | Accessible restaurants (RestaurantSummaryContract, see below) |
Restaurant in the list (RestaurantSummaryContract)
| Field | Type | Description |
|---|---|---|
id | integer | restaurantId for API calls |
name | string | Name |
address, city, country, countryShort | string | Address |
timeZone | string | Time zone |
isVerified | boolean | Verified |
isSuspended | boolean | Suspended |
isOnline | boolean | Online |
role | string | Your role in this restaurant |
curl https://api.hostmeapp.com/api/core/admin/account/me \ -H "Authorization: Bearer $TOKEN"Vendor app registration (VendorSignup)
The VendorSignup flow is for when an external service (POS/CRM) connects to Hostme through an OAuth-like
scenario: the user authorizes on the vendor’s side, Hostme receives a callback and issues a token.
The responses of these endpoints are not described in the spec (
RESPONSE 200 — OKwithout a schema). Use them in agreement with Hostme; the exact formats are clarified during onboarding.
| Endpoint | Purpose |
|---|---|
GET /api/vendor/signup/vendors | List of available vendors |
GET /api/vendor/signup/vendors/{vendorId} | Vendor information |
GET /api/vendor/signup/auth/callback/{vendorId} | OAuth callback (parameters: code, state, account, merchant_id, employee_id, referer) |
GET /api/vendor/signup/auth/token | Token issuance (parameters: vendorId, username, password, restaurantId) |
GET /api/vendor/signup/token/hostme | Hostme token by connectionId |
GET /api/vendor/signup/accounts | Vendor accounts by connectionId |
GET /api/vendor/signup/locations | Locations (connectionId, accountId) |
POST /api/vendor/signup/submit | Create a restaurant from a vendor account (body CreateRestaurantContract) |
Vendor connection request
POST /api/vendor/signup/submit
Creates a venue from the data of a vendor account. Body — CreateRestaurantContract (address,
name, contacts, services, operating hours, connectionId, companyId, siteId and more). It is a large
object; the key fields are name, phone, email, addressObj, openingHours, services,
connectionId.
The full
CreateRestaurantContractschema is in Swagger UI.
Vendor app (VendorApp) and vendorId
After registration the app operates in the /api/pos/apps/{vendorId}/… namespace. Here vendorId is
your app’s identifier. Events and integrations (telephony, printing,
WhatsApp, device statuses) go through these endpoints.
Most
VendorAppendpoints are inbound webhooks of specific providers (telephony, AmoCRM, etc.) and service operations. Responses are not described in the spec. Connection — in agreement with Hostme.
| Endpoint | Purpose |
|---|---|
GET /api/pos/apps/{vendorId}/auth2 | App authorization (parameter token) |
GET /api/pos/apps/{vendorId}/mappings/{entity} | Entity mapping |
POST /api/pos/apps/{vendorId}/events | Event intake (parameter appId) |
GET /api/pos/apps/{vendorId}/dashboard | App dashboard |
POST /api/pos/apps/{vendorId}/whatsapp/{restaurantId}/connect | Connect WhatsApp |
The appId concept
appId is the identifier of a partner/vendor app. It is used as a filter and a source
marker in a number of endpoints. In particular, the path to partner reservations is built from it:
/api/rsv/partner/{appId}/reservationsMore on working with reservations on behalf of an app — in
Partner Bookings. When listing reservations, appId (as VendorAppId)
may be set automatically for requests from external apps — see
Create & Manage.
Possible errors — ProblemDetails, codes 400/401/403/404. For the general rules see
Conventions and Errors.