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

# Quickstart

> Get started with the Rightfoot API in minutes

# Quickstart Guide

This guide will walk you through submitting your first balance check request and retrieving the results.

## Prerequisites

Before you begin, make sure you have:

* A Rightfoot API key
* A tool to make HTTP requests (cURL, Postman, or your preferred programming language)

## Step 1: Submit a Balance Check Request

Submit a batch of authorizers for balance checking:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.rightfoot.com/v1/balance_requests \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "authorizers": [
        {
          "authorizer_unique_id": "1a2b3c4d",
          "first_name": "John",
          "last_name": "Doe",
          "address": {
            "street_address_line1": "123 Main St",
            "city": "Anytown",
            "state": "CA",
            "zip_code": "12345"
          },
          "phone_number": "5551234567",
          "date_of_birth": {
            "day": 1,
            "month": 1,
            "year": 1980
          },
          "ssn": "123456789",
          "account_number": "1234567890",
          "routing_number": "021000021"
        }
      ],
      "webhook_url": "https://your-api.com/webhook"
    }'
  ```

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

  url = "https://api.rightfoot.com/v1/balance_requests"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  data = {
      "authorizers": [
          {
              "authorizer_unique_id": "1a2b3c4d",
              "first_name": "John",
              "last_name": "Doe",
              "address": {
                  "street_address_line1": "123 Main St",
                  "city": "Anytown",
                  "state": "CA",
                  "zip_code": "12345"
              },
              "phone_number": "5551234567",
              "date_of_birth": {
                  "day": 1,
                  "month": 1,
                  "year": 1980
              },
              "ssn": "123456789",
              "account_number": "1234567890",
              "routing_number": "021000021"
          }
      ],
      "webhook_url": "https://your-api.com/webhook"
  }

  response = requests.post(url, headers=headers, json=data)
  print(response.json())
  ```
</CodeGroup>

### Response

You'll receive a response with the batch ID:

```json theme={null}
{
  "batch_id": "5d3c6bbb-fc1a-46a4-93da-1ce4a54b0d83",
  "submitted_at": "2024-09-17T10:00:00Z",
  "message": "Batch has been successfully submitted and is pending processing."
}
```

<Note>
  Save the `batch_id` - you'll need it to retrieve the balance results.
</Note>

## Step 2: Retrieve Balance Results

After processing (typically within 1 hour), retrieve the balance results using the batch ID:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.rightfoot.com/v1/balances?batchId=5d3c6bbb-fc1a-46a4-93da-1ce4a54b0d83" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

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

  batch_id = "5d3c6bbb-fc1a-46a4-93da-1ce4a54b0d83"
  url = f"https://api.rightfoot.com/v1/balances?batchId={batch_id}"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "batch_id": "5d3c6bbb-fc1a-46a4-93da-1ce4a54b0d83",
  "total_processed": 1,
  "balances": [
    {
      "authorizer_unique_id": "1a2b3c4d",
      "balance": 3851.09,
      "timestamp": "2024-08-09T17:51:34Z",
      "balance_status_code": 0
    }
  ],
  "has_more": false,
  "next_page_token": null
}
```

## Understanding Status Codes

The `balance_status_code` indicates the outcome:

| Code | Description                        |
| ---- | ---------------------------------- |
| 0    | Success - Balance retrieved        |
| 2560 | Invalid phone number               |
| 3000 | No tax ID match                    |
| 3100 | No date of birth match             |
| 3200 | Account closed                     |
| 3300 | Institution not supported          |
| 3400 | No match with provided information |
| 9000 | Other error                        |

## Important Notes

<Warning>
  * **Batch Size Limit**: Maximum 1,000 authorizers per request
  * **Idempotency**: Identical requests within 24 hours return cached results
</Warning>

## Using Webhooks (Optional)

If you provided a `webhook_url`, you'll receive a notification when processing completes:

```json theme={null}
{
  "event_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "BALANCE_BATCH_COMPLETED",
  "batch_id": "5d3c6bbb-fc1a-46a4-93da-1ce4a54b0d83"
}
```

<Note>
  Webhook delivery is attempted for up to 30 minutes with exponential backoff. Always implement polling as a fallback.
</Note>

## Next Steps

Now that you've successfully submitted your first balance check, explore our API endpoints:

<CardGroup cols={2}>
  <Card title="Submit Balance Check" icon="upload" href="/api-reference/stable/submit-balance-request">
    Learn about all parameters and options for balance checks
  </Card>

  <Card title="Retrieve Balance Results" icon="download" href="/api-reference/stable/get-balances">
    Retrieve and paginate through balance results
  </Card>
</CardGroup>