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

# Quickstart

> Create an API key and make your first Finowl request in under 5 minutes.

<Steps>
  <Step title="Create an account">
    Sign up at [app.finowl.co](https://app.finowl.co/signup). Every account includes free monthly credits, so you can start testing straight away.
  </Step>

  <Step title="Create an API key">
    Open [API Keys](https://app.finowl.co/api-keys) in the dashboard and select **Create key**. Give it a label you will recognize later, such as `production-backend`.

    <Warning>
      The full key is shown **only once**. Copy it into your secret manager or `.env` file before closing the dialog.
    </Warning>
  </Step>

  <Step title="Store the key as an environment variable">
    ```bash theme={null}
    export FINOWL_API_KEY="finowl_..."
    ```

    Keep the key on your server. Never put it in frontend code, a mobile app or a public repository.
  </Step>

  <Step title="Make your first request">
    Check whether a common password has been breached:

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.finowl.co/v1/breaches/password \
        -H "Authorization: Bearer $FINOWL_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"password": "P@ssw0rd"}'
      ```

      ```javascript Node.js theme={null}
      const response = await fetch("https://api.finowl.co/v1/breaches/password", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.FINOWL_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ password: "P@ssw0rd" }),
      });

      console.log(await response.json());
      ```

      ```python Python theme={null}
      import os
      import requests

      response = requests.post(
          "https://api.finowl.co/v1/breaches/password",
          headers={"Authorization": f"Bearer {os.environ['FINOWL_API_KEY']}"},
          json={"password": "P@ssw0rd"},
          timeout=40,
      )
      print(response.json())
      ```

      ```go Go theme={null}
      package main

      import (
          "fmt"
          "io"
          "net/http"
          "os"
          "strings"
          "time"
      )

      func main() {
          body := strings.NewReader(`{"password": "P@ssw0rd"}`)
          request, _ := http.NewRequest("POST", "https://api.finowl.co/v1/breaches/password", body)
          request.Header.Set("Authorization", "Bearer "+os.Getenv("FINOWL_API_KEY"))
          request.Header.Set("Content-Type", "application/json")

          client := &http.Client{Timeout: 40 * time.Second}
          response, err := client.Do(request)
          if err != nil {
              panic(err)
          }
          defer response.Body.Close()
          result, _ := io.ReadAll(response.Body)
          fmt.Println(string(result))
      }
      ```

      ```php PHP theme={null}
      <?php
      $request = curl_init('https://api.finowl.co/v1/breaches/password');
      curl_setopt_array($request, [
          CURLOPT_POST => true,
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_TIMEOUT => 40,
          CURLOPT_HTTPHEADER => [
              'Authorization: Bearer ' . getenv('FINOWL_API_KEY'),
              'Content-Type: application/json',
          ],
          CURLOPT_POSTFIELDS => json_encode(['password' => 'P@ssw0rd']),
      ]);
      echo curl_exec($request);
      ```

      ```ruby Ruby theme={null}
      require "net/http"
      require "json"

      uri = URI("https://api.finowl.co/v1/breaches/password")
      request = Net::HTTP::Post.new(uri)
      request["Authorization"] = "Bearer #{ENV.fetch('FINOWL_API_KEY')}"
      request["Content-Type"] = "application/json"
      request.body = { password: "P@ssw0rd" }.to_json

      response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 40) do |http|
        http.request(request)
      end
      puts response.body
      ```
    </CodeGroup>

    You should see:

    ```json theme={null}
    { "breached": true, "count": 133211 }
    ```

    The exact count changes as new breaches are added.
  </Step>

  <Step title="Try a gender prediction">
    ```bash theme={null}
    curl https://api.finowl.co/v1/gender/name \
      -H "Authorization: Bearer $FINOWL_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"name": "James Smith", "country": "US"}'
    ```

    ```json theme={null}
    {
      "data": {
        "result_status": "identified",
        "gender": "male",
        "confidence": 0.99,
        "country": "US"
      }
    }
    ```
  </Step>

  <Step title="Check your usage">
    Open the [dashboard overview](https://app.finowl.co) to see both requests, the credits they used and your remaining balance.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Handle errors" icon="triangle-exclamation" href="/concepts/errors">
    Learn which errors to fix, which to wait out and which never to retry.
  </Card>

  <Card title="Understand credits" icon="coins" href="/concepts/credits">
    How credits are counted, when you are charged and how to top up.
  </Card>

  <Card title="Block breached passwords" icon="lock" href="/guides/password-checks-at-signup">
    A production-ready sign-up integration.
  </Card>

  <Card title="Enrich contacts in batch" icon="users" href="/guides/batch-gender-enrichment">
    Process thousands of records safely.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.