Skip to content

For Personal Users

You are a personal user if you already have a Beyond account with your own listings and you want to automate tasks on it — scripts, cron jobs, CLIs, or agents acting on your own listings. You do not run a multi-tenant backend and you are not managing other people's Beyond accounts. If you are a company integrating many Beyond users on a secure backend, use the For Partners path instead.

Your Beyond account and listings already exist, so — unlike partners — you do not create users or add channel accounts through the API. This page is the end-to-end path: how authentication works, how to set it up from the dashboard, your first authenticated call, and what you can automate afterward.

Migrating from the legacy API?

If you previously used the legacy API at api.beyondpricing.com/api with a Token header, see Migrating from the legacy API for a side-by-side endpoint mapping.

When To Use This Path

Choose this profile if your client:

  • Represents one Beyond user automating their own account.
  • Runs non-interactively (scripts, cron jobs, agents) and can store a single secret securely.
  • Does not need to act on behalf of other Beyond users.

Authentication Method

Personal users authenticate with a personal access token (PAT): a long-lived secret you create yourself from the Beyond Settings, bound to your single Beyond credential. There is no client secret to manage and no browser step at runtime — you create the PAT once in the dashboard, then send it on every API request.

The PAT inherits the permissions of the credential it is bound to. What the token can read and write is controlled by that credential's configuration on the Settings / Team page — the same view and per-listing access you have in the dashboard. Changes to those permissions take effect immediately for the token.

See Authentication for the full PAT rules and credential scoping reference.

End-to-End Flow

  1. Sign in to the Beyond dashboard
  2. Create a personal access token (PAT) from your dashboard user settings
  3. Make your first authenticated API call and confirm it returns your listings
  4. Read and write data for your listings (pricing, calendar, customizations, recommendations)
  5. Optionally, set up a webhook so Beyond pushes changes to you
sequenceDiagram
    participant User as PersonalUser
    participant Dashboard as BeyondDashboard
    participant BP as BeyondPricing

    User->>Dashboard: Sign in
    User->>Dashboard: Create PAT
    Dashboard-->>User: Show bpat_ secret once
    User->>BP: GET /api/v1/listings/ with Authorization Bearer bpat_…
    BP-->>User: Your listings
    User->>BP: Read/write pricing, calendar, customizations
    BP-->>User: Updated data

Step 1: Sign In to the Beyond Dashboard

Sign in at https://v2.beyondpricing.com with your Beyond credentials.

Step 2: Create a Personal Access Token

Create a PAT from your dashboard user settings (Personal Access Tokens). Beyond shows the cleartext secret exactly once at creation time — copy and store it immediately, like any other high-value credential.

The PAT does not have its own permission settings — it acts with the permissions of the credential it is bound to. To control which listings the token can read or modify, manage that credential on the Settings / Team page. Permission changes there apply to the token immediately.

Step 3: Make Your First API Call

Send the PAT in the Authorization header. A PAT is already bound to your user, so the response is limited to your own listings — you do not need a filter[owner] parameter.

curl -X GET "$BASE_URL/api/v1/listings/?page[size]=5" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/vnd.api+json"

If the response lists your properties, authentication is working.

Step 4: Automate Your Tasks

Call the endpoints your automation needs:

For API-wide error semantics, see Error Handling, and review Rate Limiting before scheduling frequent jobs.

Step 5: Receive Webhooks (optional)

Instead of polling, let Beyond push events to your backend: a new listing, a base price change, a finished account sync. Webhooks are configured on the same dashboard page as your personal access tokens, by an administrator of the account:

  1. Generate a signing secret and add it to your receiver.
  2. Save a public https endpoint URL. Beyond verifies it with a signed webhook.ping before saving.
  3. Pick the events you want, or keep the default of every event.

Every delivery is a signed JSON:API document; see Webhooks for the verification recipe, retries, and the event catalog. Your PAT carries the webhooks:read scope, so you can read back deliveries through the Webhook Events endpoints.

Rotate or Revoke

Revoke a PAT from the same dashboard settings at any time; a revoked token immediately stops working. The secret cannot be recovered after creation — if you lose it, revoke it and create a new one.

Beyond Pro also controls your tokens. A PAT needs an active Beyond Pro trial or subscription. When your trial or subscription ends, Beyond revokes your tokens and every request answers 401. Renew Beyond Pro, then create a new token.

Example Use Cases

These are common automations a personal user can build with basic-to-intermediate development skills. Each one only needs your PAT and a scheduled script (for example, a daily cron job).

Building a client with AI

If you are scaffolding the client with an AI coding tool, give it both the schema-level and narrative context so it generates correct requests:

  • OpenAPI specification — /api/v1/schema/ for precise endpoint contracts, field types, and request/response structures.
  • Full documentation (Markdown) — /full-documentation.md for authentication, behavior details, and usage examples in one file.

This is the fastest way to turn the use cases below into working code.

1. Pricing recommendation digest

Get notified about Beyond's latest base-price suggestions and, optionally, apply the ones you trust automatically — instead of logging into the dashboard to check.

How to build it: list your listings with Listings, then for each listing read pending suggestions from Recommendations. Summarize them into an email or chat message. To act on a suggestion, push the value with the base-price Listing Customization. Run it on a daily schedule.

2. Occupancy and revenue report

Export a forward-looking view of bookings and nightly prices across all your listings into a spreadsheet or BI dashboard, so you can track occupancy and projected revenue without manual data entry.

How to build it: enumerate your listings with Listings, then for each one pull the daily Calendar for your reporting window (using filter[start-date] and filter[end-date]). The calendar returns availability status and price per night — aggregate those into occupancy and revenue figures and write them to a CSV or sheet on a daily or weekly cadence.

This is one request per listing, so pace it: past a few hundred listings an unthrottled loop will hit a per-minute rate limit partway through and leave your report silently incomplete. Spread the sweep out, and retry any 429 rather than skipping the listing. A year of calendar comes back in a single response, so there is no need to page each listing's dates.

3. Seasonal rules automation

Apply consistent pricing and stay rules across your whole portfolio ahead of a high or low season — for example, raising price floors and requiring longer minimum stays for summer — without editing each listing by hand.

How to build it: list your listings with Listings, then apply the rules per listing through Listing Customizations: use min-max-prices for seasonal price floors and ceilings and min-stays for seasonal minimum-night rules. Run the script once when a season is approaching, or keep the desired rules in a config file and reconcile on a schedule.

Security Notes

  • The PAT secret is shown only once at creation. Store it like any other high-value credential.
  • The token acts with its credential's permissions. Keep that credential's access on the Settings / Team page scoped to what your automation needs.
  • Revoke immediately if a token is exposed, then create a replacement.

Common Pitfalls

  • Losing the PAT secret. Beyond shows it only once at creation. If you lose it, revoke it and create a new one — it cannot be retrieved later.
  • Expecting more access than the credential allows. The token cannot do more than its credential permits. If a call is denied, check that credential's permissions on the Settings / Team page.
  • Forgetting that field names are dasherized in API payloads. See JSON:API Format.

Next Steps