Giggal.ai API Reference
Verify single emails, run bulk batches, and deep-check catch-all and SEG-protected addresses. All endpoints use JSON, are authenticated with an API key, and are billed per successful verification.
Introduction
The Giggal.ai API lets you verify single email addresses, run bulk batches of up to 50,000 emails per job, and deep-check catch-all and SEG-protected addresses via a simple JSON REST API. Every successful verification costs credits from your account.
https://api.giggal.ai/v1Create an API key from your Giggal.ai dashboard: open the Developer API tab in the sidebar and click Create API Key. Each key is scoped to your account, tracks its own usage, and can be revoked at any time.
Open the Developer API tabEvery response follows a consistent JSON envelope:
// Success
{ "success": true, "data": { ... }, "meta": { ... } }
// Error
{ "success": false, "error": "Human-readable error message" }curl -X POST https://api.giggal.ai/v1/verify \
-H "Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]"}'Authentication
Pass your API key with every request via one of two headers. Either works.
Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxxX-API-Key: tp_live_xxxxxxxxxxxxxxxxxxxxxxxxxMissing, invalid, or revoked keys return HTTP 401. Never expose API keys in client-side code — proxy calls through your backend instead.
For POST /v1/verify-batch and POST /v1/catchall, pass an Idempotency-Key header. Retries with the same key return the original response without creating a duplicate job or double-charging credits.
Idempotency-Key: 2026-07-24-list-batch-42Single verification
1 endpoint in this group.
/v1/verifyVerify a single email
Verify one email address synchronously. Costs 1 credit. When the domain is catch-all, deep verification runs in-line and the response includes catch_all_score plus catch_all_verdict.
Bulk verification
3 endpoints in this group.
/v1/verify-batchSubmit a bulk verification job
Submit up to 50,000 emails per job. Processing is asynchronous — poll GET /v1/jobs/:jobId for progress. Pass an Idempotency-Key header to safely retry job creation without double charges.
/v1/jobs/:jobIdGet bulk job status
Poll to check progress. Status transitions: processing → completed (or failed). Recommended polling interval: 10–15 seconds. Small batches (< 50 emails) typically finish inside 30 seconds.
/v1/jobs/:jobId/resultsGet bulk job results
Once status is "completed", fetch per-email results. Results are paginated — pass page and limit query params. Results are retained for 48 hours (see resultsExpiresAt on the job).
Catch-all verification
4 endpoints in this group.
/v1/catchallStart a catch-all verification task
Kick off deep catch-all verification for a completed bulk job. Only addresses flagged as catch-all in the source job are re-checked. Billed at 2 credits per address (see creditsRequired in the response).
/v1/catchall/:taskIdGet catch-all task status
Poll to check progress and live verdictCounts. Catch-all tasks usually resolve in a few seconds to a few minutes depending on volume.
/v1/catchall/:taskId/resultsGet catch-all task results
Fetch paginated per-email verdicts with the underlying scoring breakdown (domain triage signals and domain age).
/v1/catchall/:taskId/downloadDownload catch-all results as CSV
Downloads all results for a completed catch-all task as a CSV file with Email, Score, Verdict columns. Content-Type is text/csv.
Account
1 endpoint in this group.
/v1/creditsGet current credit balance
Returns your account balance including available, reserved (held for in-flight jobs), and lifetime totals. Verifications that come back as "unknown" are refunded automatically and reflected here.
Errors & rate limits
| Status | Meaning |
|---|---|
| 200 OK | Request succeeded (synchronous verification or status/results fetch). |
| 202 Accepted | Async job or task created and queued. |
| 400 Bad Request | Missing or invalid parameters (bad email format, empty emails array, missing jobId). |
| 401 Unauthorized | Missing, invalid, or revoked API key. |
| 402 Payment Required | Insufficient credits for the requested operation. |
| 404 Not Found | Job or task ID does not exist under your account. |
| 409 Conflict | Job is not in the required state (e.g. requesting results before completion). |
| 410 Gone | Job results have passed the 48-hour retention window. |
| 429 Too Many Requests | Rate limit exceeded — back off and retry. |
| 500 / 502 / 503 | Server or upstream verification service is temporarily unavailable. |
Rate limits
Every response includes RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers (RFC casing) so you can pace requests. RateLimit-Reset is the number of seconds until the current window resets.
| Category | Limit |
|---|---|
| All endpoints (default) | 300 requests / 15 minutes |
| Batch creation (POST /v1/verify-batch, POST /v1/catchall) | 30 requests / 15 minutes |
| Job polling (GET /v1/jobs/:id, GET /v1/jobs/:id/results) | 600 requests / 15 minutes |
| Max emails per bulk job | 50,000 |
| Job results retention | 48 hours |
The three-tier split exists because polling naturally happens more often than batch creation — you might poll every few seconds while a job runs, so 600 / 15 min (≈ 40/min) gives you room without hammering the backend.
429 response format
When you hit a rate limit, the API returns HTTP 429 with this body:
{
"success": false,
"message": "Developer API rate limit exceeded"
}Back off using the RateLimit-Reset header value (seconds until the window resets) before retrying.
Need higher limits? Talk to us — we routinely lift limits for verified integration partners.
Ready to integrate?
Create your API key in seconds. Free trial credits included so you can wire it up end-to-end before spending a cent.