Skip to main content

Quickstart

Five steps from zero to your first pricing recommendation. Allow about ten minutes.

1. Get your credentials​

Sarucci provisions your partner account and issues your first API key pair. There is no self-service signup — contact your Sarucci representative to be onboarded. You will receive:

{
  "partner": {
    "id": "…",
    "name": "Acme Travel",
    "email": "ops@acme.travel",
    "status": "active"
  },
  "credentials": {
    "label": "primary",
    "access_key": "ak_live_...",
    "secret_key": "sk_live_...",
    "secret_last4": "…"
  }
}

2. Save the keys​

The secret_key is shown once and cannot be retrieved later. Store both values in your secret manager before you continue. If you lose the secret or suspect it has leaked, contact Sarucci support to rotate your key — rotation issues a new pair and supersedes the old one.

3. Exchange keys for a JWT​

API keys are never sent on data endpoints. Exchange them for a short-lived JWT:

curl -X POST https://api.sarucci.com/public/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "access_key": "ak_live_...",
    "secret_key": "sk_live_..."
  }'

Response:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 900
}

The token expires after 15 minutes. Send it on every request as Authorization: Bearer <token>. See Authentication for the refresh pattern.

4. Create a company​

A "company" represents one hotel whose pricing you want to manage. One partner token can manage many companies.

curl -X POST https://api.sarucci.com/public/v1/companies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hotel Lumière",
    "country": "France",
    "currency": "EUR",
    "timezone": "Europe/Paris",
    "total_rooms": 120
  }'

The response includes the id (your company_id) you pass on every recommendation request, plus a data_pipeline_inbox_email — email your hotel data files (history & forecast, on-the-books, booking pace, cancellations, availability) to that address and Sarucci ingests them for this company.

5. Request a recommendation​

This calls the V1 (rule-based) engine. It is a pure function over the data Sarucci already holds for the company (budgets, demand, events, competitor pricing) for the requested date range — you pass the company and the window, not rates. For RL-driven recommendations, see V1 vs V2.

curl -X POST https://api.sarucci.com/public/v1/v1/recommendations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "'"$COMPANY_ID"'",
    "start_date": "2026-06-15",
    "end_date": "2026-06-17"
  }'

Response (one entry per day in the window):

{
  "run_id": "…",
  "company_id": "…",
  "business_date": "2026-05-23",
  "currency": "EUR",
  "recommendations": [
    {
      "date": "2026-06-15",
      "current_rate": 220.0,
      "market_rate": null,
      "competitor_rate": 221.67,
      "recommended_rate": 224.0,
      "justification": "Your rate is below the competitor median on a firm-demand day; raise by 1.8%."
    }
  ],
  "warnings": [],
  "computed_at": "2026-05-23T10:00:00Z"
}

warnings flags missing inputs (e.g. no competitor data ingested for some days) so you can tell a thin recommendation from a confident one.

What's next​

  • Wire the same flow into your language of choice — see the API Reference for Python and JavaScript snippets on every endpoint.
  • Read Errors for the error envelope and stable error codes before you ship.
  • Decide between the rule-based and RL engines in V1 vs V2.