API - Credits & Quotas

Surfe uses a system of credits and daily quotas to manage access to advanced features. Here's how it works, for everyone!

What Are Credits?

When enriching people via the API, Surfe can provide two levels of information:

• Email Credits: Used to enrich email, landline phone and other personal details (depending on availability) like the LinkedIn URL, job title, etc..

• Mobile Credits: Used when you enrich a person for a mobile phone number.

• Only pay for success: You only spend a credit when data is found. Failed searches don’t cost anything.

• Each level consumes credits: email credits for the first level, and mobile credits for the second. If the user does not have enough credits in their account, the enrichment request won't be processed.

This credit system applies to the following endpoints of this API

• Enrich People (Start)
  ​
  ​
  Search Credits: Some endpoints consume search credits instead of enrichment credits.

  • Enrich people by email (reverse email enrichment) — Costs 10 search credits per successful match. Credits are locked at request time and refunded if no match is found.

  • Search People — deducts ⌈results / 10⌉ search credits per call when credit charging is enabled

  • Search Companies — deducts ⌈results / 10⌉ search credits per call when credit charging is enabled
    Enrich Companies — on paid plans, each successfully enriched company costs 1 credit. A company counts as a successful enrichment when both annualRevenue and industry are present in the result. Credits are charged per company as enrichment completes — not at the time the request is made.
    
    Contact the support team to request search credits.

Daily Quotas

We're currently working on aligning the API quota with the customer's plan. Once this is released, Essential & Pro customers will be able to use the higher Search allowance through the API/MCP as well, without needing to purchase additional Search credits.

In the meantime, we can manually increase the API Search quota for eligible accounts if needed.

You have limits to how many profiles you can enrich per day:

People enrichment is additionally capped at 20,000 profiles per hour and 10,000 profiles per minute. These caps apply on top of the daily quota. Exceeding any of the three limits returns a 429 Too Many Requests response. The hourly and per-minute caps reset on each clock hour and clock minute (UTC).

All quotas reset at midnight local time each day.

Even if you stay within your daily quota, you can't send requests too fast. Here's what to keep in mind:

• Max speed: 10 requests per second

• Bursts allowed: Up to 20 quick requests in a short burst

• Reset: Every minute

If you go over, you’ll get an error: 429 – Too Many Requests. Just pause a moment and try again.

How It Works

1. Credits = used for each successful data result.

2. Quotas = count the number of operations, regardless of success.

   • Bulk enrichment counts per person in the batch.

What If You Run Out?

• No credits left → You can't enrich additional contacts.

• Not enough search credits → Search People, Search Companies, Enrich Companies and Enrich People by Email will return a 402 response.

• Quota reached → Further searches or enrichments are blocked until reset.

• To keep going, either wait until midnight for the quota reset or buy more credits if you’ve ran out!

Quick Tips

• Track your usage through your Surfe dashboard or side panel or through the GET /v1/credits endpoint here.

• Buy extra credits anytime.

• Team usage: Extra credits are shared across your team, and expire after 3 months.

• Stay within your plan: If you regularly hit quotas, we can help you upgrade or expand access.

Need Help?

If you're running into limits or need extra capacity, contact our support team. We’re happy to help you scale up.

Additional Resources

• Surfe API Documentation

• Webhooks

• Find your API key

• Setting up the API

• Terms & Conditions of using our API