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:
| 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:
