Credit balance

GET /v1/credits returns the credits you can spend now, any debt, credits that are still being applied, and your credit lots with their expiry dates. It is free and needs a key with the account:read scope.

Request

curl https://api.email-validation.org/v1/credits -H "Authorization: Bearer $EV_API_KEY"

const res = await fetch('https://api.email-validation.org/v1/credits', {
  headers: { Authorization: `Bearer ${process.env.EV_API_KEY}` },
});
const credits = await res.json();
if (!res.ok) throw new Error(`${credits.error.code}: ${credits.error.message}`);
console.log(`Balance: ${credits.balance}`);

import os

import requests

resp = requests.get(
    "https://api.email-validation.org/v1/credits",
    headers={"Authorization": f"Bearer {os.environ['EV_API_KEY']}"},
    timeout=10,
)
resp.raise_for_status()
credits = resp.json()
print("Balance:", credits["balance"])
for lot in credits["lots"]:
    print(lot["remaining"], "credits expire on", lot["expires_at"][:10])

Response

{
  "balance": 24350,
  "debt": 0,
  "pending": 0,
  "lots": [
    {
      "remaining": 850,
      "expires_at": "2027-03-14T12:00:00.000Z"
    },
    {
      "remaining": 23500,
      "expires_at": "2028-09-30T08:15:00.000Z"
    }
  ]
}

Each lot is one grant of credits (your sign-up credits, a purchase with its bonus, or an adjustment). Lots appear soonest-expiring first, which is also the order we spend them in, so credits that are about to expire are used before newer ones.

Debt and pending credits

• debt is above 0 only after credits had to be taken back, for example after a payment was reversed. New credits pay off debt first.
• pending counts credits granted a moment ago, for example right after a purchase, that are still being applied. They become part of balance within seconds.

Related

• Credits and billing: what costs a credit, the bonus and expiry rules.
• Usage: credits used per day or per key.
• Webhooks: credits.low and credits.expiring events.