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.

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)
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.

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.

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.

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