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:

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"
  }'

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())

Response

You’ll receive a response with the batch ID:

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

Save the batch_id - you’ll need it to retrieve the balance results.

Step 2: Retrieve Balance Results

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

curl -X GET "https://api.rightfoot.com/v1/balances?batchId=5d3c6bbb-fc1a-46a4-93da-1ce4a54b0d83" \
  -H "Authorization: Bearer YOUR_API_KEY"

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())

Response

{
  "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

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

Using Webhooks (Optional)

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

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

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

Next Steps

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

Submit Balance Check

Learn about all parameters and options for balance checks

Retrieve Balance Results

Retrieve and paginate through balance results

Getting Started

On Demand Balance Checks

Monitoring

Webhooks

Quickstart

Quickstart Guide

Prerequisites

Step 1: Submit a Balance Check Request

Response

Step 2: Retrieve Balance Results

Response

Understanding Status Codes

Important Notes

Using Webhooks (Optional)

Next Steps

Submit Balance Check

Retrieve Balance Results

​Quickstart Guide

​Prerequisites

​Step 1: Submit a Balance Check Request

​Response

​Step 2: Retrieve Balance Results

​Response

​Understanding Status Codes

​Important Notes

​Using Webhooks (Optional)

​Next Steps

Submit Balance Check

Retrieve Balance Results

Quickstart Guide

Prerequisites

Step 1: Submit a Balance Check Request

Response

Step 2: Retrieve Balance Results

Response

Understanding Status Codes

Important Notes

Using Webhooks (Optional)

Next Steps