> ## Knowledge Base Index > Fetch the complete knowledge base index at: https://support.uplisting.io/sitemap.xml > Use this file to discover available pages before exploring further. > Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash). # Uplisting V3 OAuth API FAQ # Uplisting V3 OAuth API FAQ # 1. Access and setup ## Who is V3 OAuth intended for? V3 OAuth is the current OAuth-based API access model for integrations that need scoped access to an Uplisting account. It uses OAuth 2.0 bearer tokens rather than the legacy API-key Basic authentication model. ## Is a partner agreement required? Not for a private integration used only with the customer’s own Uplisting account. A partner or marketplace agreement may be required for official partner integrations, marketplace listings, co-marketing, or integrations offered to other Uplisting customers. ## Is there an API fee? API access is free for Uplisting customers with an active subscription. Any custom development, external website build, middleware, or ongoing maintenance remains outside Uplisting unless agreed separately. ## What information is needed to create a V3 OAuth client? Please provide: * Partner/company or account name * Technical contact email * Relevant Uplisting account/customer email * Exact HTTPS redirect URI or URIs * Requested OAuth scopes * Custom booking-attribute prefix. ## What redirect URI requirements apply? The redirect URI must be an exact, direct HTTPS callback endpoint controlled by the integration. Homepage URLs, plain HTTP URLs, localhost, 127.0.0.1, and wildcard redirects are not accepted. The authorize request must use the same redirect URI exactly as registered. ## Can hosted automation tools such as n8n be used as the OAuth callback? Yes, provided the tool gives a direct HTTPS OAuth callback URL and the exact URL is registered on the OAuth client. Opening the callback URL directly may show a generic bad request; that does not by itself mean the callback is invalid. # 2. Authentication and scopes ## How does V3 authentication work? V3 uses OAuth Authorization Code with PKCE. The integration sends the user through the browser authorize step, receives an authorization code at the registered redirect URI, exchanges the code server-side for tokens, and then calls V3 endpoints with Authorization: Bearer . ## How does refresh-token access work? Request offline\_access in the initial browser authorize request to receive a refresh token. Adding offline\_access only at the token exchange step is not sufficient. Token lifetime is one hour. ## What scopes are available? The available V3 scopes are: offline\_access, properties:read, properties:write, bookings:read, bookings:create, bookings:update, calendar:read, calendar:write, reviews:read, custom\_booking\_attributes:read, custom\_booking\_attributes:write, messaging:read, and messaging:write. ## How can an integration verify that a bearer token works? Call GET /ping using the V3 API base URL and the bearer token. ## What are common scope bundles? | **ScopeUse** | | | ---- | | Read properties, availability, and bookings | properties:read, calendar:read, bookings:read, offline\_access | | Create/update bookings | properties:read, calendar:read, bookings:read, bookings:create, bookings:update, offline\_access | | Custom booking attributes | custom\_booking\_attributes:read, custom\_booking\_attributes:write, plus bookings:read/bookings:update as needed | | Messaging | messaging:read and/or messaging:write, plus bookings:read if the integration needs booking context | # 3. Staging and sandbox ## Is staging/sandbox OAuth separate from production? Yes. Sandbox OAuth credentials are separate from production OAuth credentials. ## How do I request sandbox OAuth access? Create a staging Uplisting account using the staging link in the API Partner Integration guide, then send the staging account email to Uplisting. Uplisting can then provision sandbox OAuth credentials using the same configuration details as production: company name, technical contact, redirect URI, requested scopes, and custom booking-attribute prefix. ## Can manually created test properties be used in staging? Yes, manually created staging properties can be used for API testing. If owner/admin verification blocks the setup, contact Uplisting so the staging account can be reviewed. # 4. Supported V3 areas ## What V3 API areas are documented? The current V3 API documentation includes endpoints for: * Properties and availability * Calendar * Bookings, including create, update, cancel, quote, and booking request approval/decline * Custom booking attributes * Reviews read access * Messaging * Utility endpoints such as token/API checks ## Can the API read reviews and post review replies? The V3 API supports reading reviews where the reviews:read scope is granted. There is no V3 endpoint for posting review replies. # 5. Quotes and pricing ## Does V3 have a quote endpoint? Yes. The current V3 collection includes a Get Quote endpoint under Bookings. ## Is the quote endpoint the same as Uplisting hosted checkout? No. The quote endpoint is an API pricing/quote endpoint. It does not create a hosted checkout session, collect payment, run guest verification, issue a payment link, or complete the Uplisting direct-booking checkout flow. # 6. Direct bookings, checkout, and payments ## Can Uplisting hosted checkout be embedded or recreated on my own domain through the public API? No. There is no supported public API flow for running Uplisting hosted checkout, payment collection, guest verification, rental agreement, and Uplisting Protect entirely on a customer-owned domain. ## Can I build against api.uplisting.io/direct\_booking endpoints? No. Those endpoints should not be treated as a supported public API contract. Use documented public API endpoints only. ## Can Stripe payment links be created or sent automatically through the API? No. Stripe payment links cannot currently be automated through the API. The supported option is to send the guest to the Uplisting booking/direct-booking page, which includes the payment step. ## Can I add my own middleware link to Uplisting automated messages? Yes. A customer can include a link to their own middleware or external guest flow in automated messages. ## What if I want checkout to happen fully on my own domain? Then the external site or middleware owns the checkout/payment flow. Uplisting can remain the source of truth for inventory and reservation records through the supported public API, but the API does not provide Uplisting hosted checkout on the external domain. ## What if I want Uplisting to handle payment, guest verification, rental agreement, and the normal direct-booking workflow? Send the guest through the Uplisting booking/direct-booking page or Website Builder flow. Do not try to reproduce that flow with undocumented internal endpoints. # 7. Booking safety and idempotency ## Can custom booking attributes be used for external reference IDs? Yes. Custom booking attributes can store external reference IDs or other booking-level metadata after a booking exists. They are useful for reconciliation, but they are not an atomic idempotency mechanism for creating bookings. # 8. Custom booking attributes ## What is a custom booking-attribute prefix? It is a required namespace that must start each custom field name created by an integration. This avoids conflicts with other integrations or partners. ## What naming rules apply? Attribute names must be namespaced and use snake\_case, for example partnername\_attribute\_name. The custom booking-attribute prefix must be configured before attributes are created. ## What can custom booking attributes store? They can store string values such as external IDs, status values, or codes associated with a booking. They should be treated as booking-level metadata. # 9. Webhooks ## Are webhooks registered through OAuth bearer authentication? No. Webhook registration is separate from V3 OAuth and uses the V2 API-key webhook flow. ## Which webhook events are documented? Documented events include booking\_created, booking\_updated, booking\_removed, booking\_cancelled, booking\_request\_approved, booking\_request\_declined, property\_created, property\_updated, property\_removed, prices\_changed, restrictions\_changed, availability\_changed, message\_created, payment\_status\_changed, payment\_refunded, and review\_created. ## How are webhook signatures verified? Webhook deliveries include X-Uplisting-Timestamp and X-Uplisting-Signature. The signature is an HMAC-SHA256 hex digest calculated over the timestamp and raw request body: *HMAC\_SHA256(secret, timestamp + "." + raw\_body)* ## How should duplicate webhook deliveries be handled? Each webhook payload includes event\_id. Store and deduplicate by event\_id. Webhook delivery should be treated as at-least-once delivery, so receiving the same event\_id more than once should not trigger duplicate processing. ## How quickly should a webhook endpoint respond? Respond with a 2xx status within five seconds after accepting the event for processing. # 10. Rate limits ## What API rate limits apply? The published API limits are 5 requests per second per IP address, 100 requests per minute per IP address, and 15 requests per minute per property. Treat these as general API limits unless Uplisting confirms a more specific limit for a particular endpoint.