Skip to main content

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

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

​
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:
CodeDescription
0Success - Balance retrieved
2560Invalid phone number
3000No tax ID match
3100No date of birth match
3200Account closed
3300Institution not supported
3400No match with provided information
9000Other 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