> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avatcado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get up and running with Avatcado in under 2 minutes

# Quickstart

<Steps>
  <Step title="Get your API key">
    Sign up at [avatcado.com](https://avatcado.com) to get your API key. Keys use the format `avat_live_xxx`.

    Want to test your integration first? Use a `avat_test_` key for [test mode](/test-mode) - no upstream calls, no quota usage, predictable results.

    Store your key securely - it will only be shown once. Avatcado stores a SHA-256 hash, never the raw key.
  </Step>

  <Step title="Make your first request">
    Install the SDK for your language:

    ```bash theme={null}
    npm install @avatcado/node   # Node.js
    pip install avatcado          # Python
    ```

    <CodeGroup>
      ```bash curl theme={null}
      curl -H "Authorization: Bearer avat_live_your_api_key" \
        "https://api.avatcado.com/v1/validate?vat_number=NL123456789B01"
      ```

      ```typescript @avatcado/node theme={null}
      import Avatcado from "@avatcado/node";

      const avatcado = new Avatcado("avat_live_your_api_key");
      const { data, error } = await avatcado.vat.validate({ vatNumber: "NL123456789B01" });
      ```

      ```python Python theme={null}
      from avatcado import Avatcado

      avatcado = Avatcado("avat_live_your_api_key")
      result = avatcado.vat.validate("NL123456789B01")
      ```
    </CodeGroup>
  </Step>

  <Step title="Handle the response">
    Every response has the same shape: `data` or `error`, plus `meta`.

    ```json theme={null}
    {
      "data": {
        "valid": true,
        "vat_number": "NL123456789B01",
        "country_code": "NL",
        "company": {
          "name": "Acme B.V.",
          "address": "Keizersgracht 123, Amsterdam"
        },
        "requested_at": "2026-03-06T12:00:00Z"
      },
      "meta": {
        "request_id": "550e8400-e29b-41d4-a716-446655440000",
        "request_duration_ms": 120,
        "cached": false
      }
    }
    ```

    * **`data.valid`**: `true` if the VAT number is active and registered
    * **`data.company`**: Company name and address (when available and valid)
    * **`meta.request_id`**: Unique ID for debugging, also in the `X-Request-Id` header
    * **`meta.request_duration_ms`**: How long the request took in milliseconds
    * **`meta.cached`**: Whether this result came from cache
  </Step>

  <Step title="Handle errors">
    Every error response has the same shape. Check `response.error` to handle failures:

    <CodeGroup>
      ```bash curl theme={null}
      curl -s -H "Authorization: Bearer avat_live_your_api_key" \
        "https://api.avatcado.com/v1/validate?vat_number=INVALID" | jq .
      # Check for .error in the JSON response
      ```

      ```typescript @avatcado/node theme={null}
      import Avatcado from "@avatcado/node";

      const avatcado = new Avatcado("avat_live_your_api_key");
      const { data, error } = await avatcado.vat.validate({ vatNumber: "NL123456789B01" });

      if (error) {
        console.error(`${error.code}: ${error.message}`);
        // See docsUrl for details on this specific error
        console.error(error.docsUrl);
      } else {
        console.log(`Valid: ${data.data.valid}`);
      }
      ```

      ```python Python theme={null}
      from avatcado import Avatcado, AvatcadoError

      avatcado = Avatcado("avat_live_your_api_key")

      try:
          result = avatcado.vat.validate("NL123456789B01")
          print(f"Valid: {result.data.valid}")
      except AvatcadoError as e:
          print(f"{e.code}: {e.message}")
          # See docs_url for details on this specific error
          print(e.docs_url)
      ```
    </CodeGroup>
  </Step>
</Steps>

<Note>
  **Input normalization**: You can pass messy input like `"nl 123.456.789 b01"` and the API will normalize it to `NL123456789B01` automatically. No need to clean up VAT numbers before sending them.
</Note>