API reference / Credits

Credits

Read your credit balance, usage history, and available packages. Verifications and finds draw down the same balance.

◈

Billing model. You are charged 1 credit for a decisive verification (ok, invalid, catch_all, disposable). unknown and error are free. A finder call costs 10 credits, and only when a usable address is returned, a miss is free.

A team shares one balance: members spend the owner's credits. Use these endpoints to read the balance and usage; top-ups happen in the dashboard.

GET/v1/credits/balanceGet current credit balance for the authenticated user. Balance is cached in Redis for 30 seconds GET/v1/credits/ordersGet paginated order history for the authenticated user GET/v1/credits/packagesList all active credit packages and current promotions. No API key required GET/v1/credits/transactionsGet paginated credit transaction history. Optionally filter by transaction type (`Added`, `Used`, `Adjusted`)

GET/v1/credits/balance

Get current credit balance for the authenticated user. Balance is cached in Redis for 30 seconds

Returns 401 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X GET "https://api.primeverifier.com/v1/credits/balance" \
  -H "X-API-KEY: pk_live_your_api_key"

const res = await fetch("https://api.primeverifier.com/v1/credits/balance", {
  method: "GET",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://api.primeverifier.com/v1/credits/balance",
    headers={"X-API-KEY": "pk_live_your_api_key"},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Get, "https://api.primeverifier.com/v1/credits/balance");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/credits/balance"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/credits/balance");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key"],
]);
$response = curl_exec($ch);
echo $response;

req, _ := http.NewRequest("GET", "https://api.primeverifier.com/v1/credits/balance", nil)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/credits/balance")
req = Net::HTTP::Get.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {},
  "error": null
}

Try itGET /v1/credits/balance

API key *

GET/v1/credits/orders

Get paginated order history for the authenticated user

Parameters

Name	In	Type	Required	Description
page	query	integer · int32	optional
limit	query	integer · int32	optional

Response 200 · inside data

Field	Type	Description	Example
items	Order[]
page	integer · int32
limit	integer · int32
total	integer · int32
totalPages	integer · int32

Returns 401 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X GET "https://api.primeverifier.com/v1/credits/orders?page=string&limit=string" \
  -H "X-API-KEY: pk_live_your_api_key"

const res = await fetch("https://api.primeverifier.com/v1/credits/orders?page=string&limit=string", {
  method: "GET",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://api.primeverifier.com/v1/credits/orders?page=string&limit=string",
    headers={"X-API-KEY": "pk_live_your_api_key"},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Get, "https://api.primeverifier.com/v1/credits/orders?page=string&limit=string");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/credits/orders?page=string&limit=string"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/credits/orders?page=string&limit=string");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key"],
]);
$response = curl_exec($ch);
echo $response;

req, _ := http.NewRequest("GET", "https://api.primeverifier.com/v1/credits/orders?page=string&limit=string", nil)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/credits/orders?page=string&limit=string")
req = Net::HTTP::Get.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": 0,
        "userId": 0,
        "packageId": 0,
        "creditsPurchased": 0,
        "bonusCredits": 0,
        "totalCreditsAdded": 0,
        "amountUsd": 0,
        "discountUsd": 0,
        "finalAmountUsd": 0,
        "unitPriceUsd": 0,
        "promotionId": 0,
        "stripePaymentIntentId": "string",
        "stripeChargeId": "string",
        "status": 1,
        "failureReason": "string",
        "invoiceNumber": "string",
        "isAutoTopup": false,
        "createdAt": "2026-01-01T12:00:00Z",
        "completedAt": "2026-01-01T12:00:00Z"
      }
    ],
    "page": 0,
    "limit": 0,
    "total": 0,
    "totalPages": 0
  },
  "error": null
}

Try itGET /v1/credits/orders

API key *

page (query)

limit (query)

GET/v1/credits/packages

List all active credit packages and current promotions. No API key required

Request

curl -X GET "https://api.primeverifier.com/v1/credits/packages" \
  -H "X-API-KEY: pk_live_your_api_key"

const res = await fetch("https://api.primeverifier.com/v1/credits/packages", {
  method: "GET",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://api.primeverifier.com/v1/credits/packages",
    headers={"X-API-KEY": "pk_live_your_api_key"},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Get, "https://api.primeverifier.com/v1/credits/packages");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/credits/packages"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/credits/packages");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key"],
]);
$response = curl_exec($ch);
echo $response;

req, _ := http.NewRequest("GET", "https://api.primeverifier.com/v1/credits/packages", nil)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/credits/packages")
req = Net::HTTP::Get.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {},
  "error": null
}

Try itGET /v1/credits/packages

API key *

GET/v1/credits/transactions

Get paginated credit transaction history. Optionally filter by transaction type (`Added`, `Used`, `Adjusted`)

Parameters

Name	In	Type	Required
page	query	integer · int32	optional
pageSize	query	integer · int32	optional
type	query	CreditTransactionType	optional

Returns 401 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X GET "https://api.primeverifier.com/v1/credits/transactions?page=string&pageSize=string&type=string" \
  -H "X-API-KEY: pk_live_your_api_key"

const res = await fetch("https://api.primeverifier.com/v1/credits/transactions?page=string&pageSize=string&type=string", {
  method: "GET",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://api.primeverifier.com/v1/credits/transactions?page=string&pageSize=string&type=string",
    headers={"X-API-KEY": "pk_live_your_api_key"},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Get, "https://api.primeverifier.com/v1/credits/transactions?page=string&pageSize=string&type=string");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/credits/transactions?page=string&pageSize=string&type=string"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/credits/transactions?page=string&pageSize=string&type=string");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key"],
]);
$response = curl_exec($ch);
echo $response;

req, _ := http.NewRequest("GET", "https://api.primeverifier.com/v1/credits/transactions?page=string&pageSize=string&type=string", nil)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/credits/transactions?page=string&pageSize=string&type=string")
req = Net::HTTP::Get.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {},
  "error": null
}

Try itGET /v1/credits/transactions

API key *

page (query)

pageSize (query)

type (query)