Skip to main content

​
Polling strategy

All async APIs require polling. Poll the status endpoint once per minute for up to 90 minutes. If your request has not completed within 90 minutes, treat it as timed out — our team is automatically notified and will investigate promptly. 
async function pollRequest(requestId, token, opts = {}) {
  const {
    maxAttempts = 90,
    interval = 60000,       // 1 minute between each poll
  } = opts;

  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(
      `https://api.wokelo.ai/api/enterprise/request/status/?request_id=${requestId}`,
      { headers: { Authorization: `Bearer ${token}` } }
    );

    const { status } = await res.json();

    if (status === "COMPLETED") return fetchResult(requestId);
    if (status === "FAILED") throw new Error("Request failed");

    await new Promise(r => setTimeout(r, interval));
  }

  // Timed out after 90 minutes — our team will be notified and look into it.
  throw new Error(
    "Polling timed out after 90 minutes. Our team has been notified and will investigate."
  );
}

​
Error guides

HTTP CodeMeaningRetry?Action
200Success (sync)NoParse response
202Accepted (async)NoPoll with request_id
400Bad RequestNoFix request parameters
401UnauthorizedOnceRe-authenticate, then retry
403ForbiddenNoCheck API access level
404Not FoundNoVerify endpoint URL and resource ID
429Rate LimitedYesExponential backoff (start 1s, max 60s)
500Server ErrorYesRetry with backoff (max 3 retries)
502/503Service UnavailableYesRetry with backoff (max 5 retries)

​
Webhooks

Instead of polling for results after submitting a request, you can use webhooks to receive the data automatically once processing is complete. When a request finishes, we’ll send the payload directly to your configured endpoint — no repeated status checks required. Webhook configuration is handled by our customer success team. Please reach out to our Customer Success team to get webhook endpoint registered and activated.

​
How It Works

  1. Submit an enrichment request via any of the supported endpoints (e.g. POST /api/enterprise/company/enrich/). You’ll receive a request_id with a PENDING status as usual.
  2. Once processing is complete, we’ll send an HTTP POST request to your registered webhook URL.
  3. Your server should respond with a 200 OK to acknowledge receipt.
Here is sample payload. 
{
    "request_id": "5b5c8248-50e3-4e5d-b91e-5c75378971dd",
    "status": "COMPLETED"
}