Users

Users are the property managers your application manages. Listings and accounts always belong to a user.

Endpoint	Method	Scope	Token Tier	Description
/api/v1/users/	GET	user:read	Both	List all users (paginated)
/api/v1/users/	POST	user:write	App-level only	Create a new user
/api/v1/users/<id>/	GET	user:read	Both	Retrieve a user
/api/v1/users/<id>/credentials/	GET	user:read	Both	List credentials for a user
/api/v1/users/<id>/	DELETE	user:write	App-level only	Delete a user

Try it out

Explore parameters, schemas, and live requests in the Swagger UI.

User Status

Every user resource includes a read-only status attribute describing its lifecycle state. It is derived from enabled-listing state and updates automatically as listings are enabled or disabled.

Value	Meaning
new	Created, but no listings enabled yet.
active	Has at least one enabled listing.
inactive	Was active before; no listings currently enabled.

List Users

Returns a paginated list of all users owned by the authenticated application.

Request

GET /api/v1/users/?filter[email]=john@example.com

Parameter	Description
filter[email]	Exact, case-insensitive match on the user's email. Email is unique, so this returns at most one user — use it to recover a user's id from an email. A non-owned email yields an empty list.
sort	created-at or -created-at (default: newest first).
page[number], page[size]	Standard pagination. Default page size 25, maximum 100.

User-scoped tokens

When using a user-scoped token, this endpoint returns only the user the token is bound to.

Response

{
  "data": [
    {
      "type": "users",
      "id": "456",
      "attributes": {
        "first-name": "John",
        "last-name": "Doe",
        "email": "john@example.com",
        "locale": "en-GB",
        "created-at": "2026-05-20T18:03:11Z",
        "status": "active"
      }
    }
  ],
  "meta": {
    "pagination": {"page": 1, "pages": 1, "count": 1}
  }
}

Field	Description
first-name, last-name	The user's name.
email	The user's email. Unique across Beyond.
locale	The user's locale as a BCP 47 language tag.
created-at	When the user was created.
status	Lifecycle state — see User Status.

Retrieve a User

GET /api/v1/users/<id>/ returns a single user, with the same attributes as the list entries above. 404 when the user is not owned by your application.

Create User

Create a new user managed by your application. Users created via this endpoint are managed by the OAuth2 application and cannot log in directly (password is randomly generated).

App-level token required

This endpoint requires an app-level token. Requests with a user-scoped token will receive 403 Forbidden.

Request

{
  "data": {
    "type": "users",
    "attributes": {
      "first-name": "John",
      "last-name": "Doe",
      "email": "john@example.com",
      "locale": "en-GB"
    }
  }
}

Field	Description
first-name, last-name	Required.
email	Required. Must be unique — an existing email is a 409 Conflict.
locale	Optional, defaults to en. A supported BCP 47 tag: en, en-GB, en-AU, en-CA, ja, fr, pt, de, es, or it. Used in messages that explain the reason for price changes.

Returns 201 Created with the created user resource, including its id — store it, every other user-scoped call needs it.

List User Credentials

Returns the login credentials that are visible for the requested user.

• App-level tokens can list all credentials for the user.
• User-scoped tokens default to the bound credential. Admin credentials can list all credentials for that user; non-admin credentials only see themselves.
• Each credential object has its own id. Use that credential_id when requesting a user-scoped token that must enforce one credential's visibility and grants.

Response

{
  "data": [
    {
      "type": "credentials",
      "id": "789",
      "attributes": {
        "created-at": "2026-05-20T18:03:11Z",
        "last-login": "2026-08-01T07:40:02Z",
        "credential-type": "email",
        "global-permissions": "Admin",
        "email": "john@example.com"
      }
    }
  ],
  "meta": {
    "pagination": {"page": 1, "pages": 1, "count": 1}
  }
}

Field	Description
created-at	When the credential was created.
last-login	Last login with this credential; null if never used.
credential-type	How the credential authenticates (e.g. email).
global-permissions	The credential's permission level on the account.
email	The credential's login email; null for credential types without one.

Delete User

Soft-delete a user managed by your application. This anonymizes the user's email, disables all enabled listings, removes managed accounts, and marks the user as deleted.

Returns 204 No Content on success.

App-level token required

This endpoint requires an app-level token. Requests with a user-scoped token will receive 403 Forbidden.

Use cases

1. Onboarding. Create the user first, then add an account for them — the account sync imports their listings.
2. Id recovery. Look up a user's id with filter[email] instead of storing a separate mapping.
3. Offboarding. Delete the user when the property manager leaves your platform; their listings stop syncing and their accounts are removed.

Errors

Status	Cause
400	Malformed request body or missing required attribute on create.
401	Missing or invalid bearer token.
403	Token lacks the required scope, or a user-scoped token calling an app-level-only operation (create, delete).
404	No user with that id is owned by your application.
409	Create with an email that already exists.
429	Rate limit exceeded. See Rate Limiting.