Get Started
Document metadata
Category
Get Started
Version
1
Stability
stable
Deprecated
No
Last updated
2026-05-03

Get Started

Use this guide to make your first Valora API request and understand the conventions used across the documentation.

Valora exposes REST APIs for finance, account, invoice, request, and integration workflows. The API is designed for server-side integrations, internal tools, automation platforms, and AI agents that need predictable HTTP contracts.

Base URLs

Environment Base URL Use for
Production https://valora.spotahome.com Live data and production workflows.
Staging / testing https://valora-testing.laravel.cloud Testing integrations before using production.
Sandbox API paths /api/sandbox/v1/... Sandbox-compatible customer and employee data paths where documented.

Always use the full endpoint URL shown on each endpoint page. Some resources use production paths under /api/v1/...; sandbox-compatible resources may use /api/sandbox/v1/....

Choose an authentication method

Most integrations should use a long-lived API token unless the endpoint explicitly requires JWT authentication.

Method Best for Token lifetime
Long-lived API token Server integrations, scheduled syncs, automation tools, and customer portal clients. Valid until rotated or revoked.
JWT Short-lived sessions, SPAs, and mobile clients. 30 minutes by default; refreshable.

Read Authentication Overview before integrating, then follow Long-Lived API Token Authentication or JWT Authentication.

Make your first request

  1. Generate or obtain the token required by the endpoint.
  2. Send Accept: application/json on every request.
  3. Send the token in the Authorization header.
  4. Start with a documented connection test when the endpoint supports ?test=connection.
  5. Handle pagination, validation errors, rate limits, and empty result sets as normal response paths.
GET https://valora.spotahome.com/api/v1/c/transactions?test=connection
Authorization: Bearer {token}
Accept: application/json

Example success response:

{
  "message": "You are connected!",
  "accepted_params": {
    "test": "Set to \"connection\" to test API connection"
  }
}

Common headers

Header Required Description
Accept: application/json Yes Ensures validation, auth, and application errors are returned as JSON.
Authorization: Bearer {token} Yes for protected endpoints Sends either a long-lived API token or a JWT, depending on the endpoint.
Content-Type: application/json Yes for JSON request bodies Required when sending POST, PUT, PATCH, or other JSON payloads.

Common data conventions

Convention Details
Dates Use YYYY-MM-DD unless an endpoint documents a datetime format.
Datetimes Use ISO 8601 when datetimes are accepted or returned.
Currency Currency codes use ISO 4217 values such as EUR.
Amounts Response amounts are commonly returned in minor units, such as cents. Endpoint pages document any filters that accept major units.
Pagination List endpoints commonly use page and per_page. Defaults and maximums are documented per endpoint.
Empty results Some list endpoints return 404 Not Found with an empty data array and pagination metadata. Treat this as a handled no-results state where documented.

Documentation formats

Every public documentation page is available for both humans and tools:

Format URL pattern
Web page /developers/{page}
Raw Markdown /developers/{page}.md
Per-page OpenAPI /developers/{page}.openapi.json when the page describes an endpoint
Aggregated OpenAPI /developers/openapi.json
AI discovery index /llms.txt
Full AI context bundle /llms-full.txt

Recommended integration order

  1. Read Authentication Overview.
  2. Generate a sandbox token if the resource supports sandbox paths.
  3. Call a connection test endpoint.
  4. Implement normal success and pagination handling.
  5. Add handling for validation errors, unauthorized responses, forbidden responses, and rate limits.
  6. Move to production only after confirming request headers, token class, and response parsing.