Skip to main content

​
SDKs & Code Examples

Naturalead provides a REST API accessible from any language. Below are examples and helper patterns for the most common languages.
Official SDKs are on the roadmap. For now, use the REST API directly with any HTTP client.

​
Quick Reference

cURL

Command-line examples for every endpoint.

Python

Using requests or httpx with helper patterns.

JavaScript

Node.js examples with fetch and error handling.

​
Authentication Setup

All examples assume you have an API key stored in an environment variable: 
export NATURALEAD_API_KEY="nl_live_your_api_key_here"

​
Common Patterns

​
Error Handling

Always check the HTTP status code before parsing the response body: 
import requests

def api_request(method, path, **kwargs):
    response = requests.request(
        method,
        f"{BASE_URL}{path}",
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        **kwargs
    )

    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 5))
        raise Exception(f"Rate limited. Retry after {retry_after}s")

    if not response.ok:
        error = response.json().get("error", "Unknown error")
        raise Exception(f"API error {response.status_code}: {error}")

    if response.status_code == 204:
        return None

    return response.json()

​
Rate Limit Handling

Monitor rate limit headers to proactively throttle your requests:
Python
import time

def api_request_with_backoff(method, path, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        response = requests.request(
            method,
            f"{BASE_URL}{path}",
            headers={"X-API-Key": API_KEY},
            **kwargs
        )

        remaining = int(response.headers.get("RateLimit-Remaining", 100))
        if remaining < 10:
            reset = int(response.headers.get("RateLimit-Reset", 5))
            time.sleep(min(reset, 5))

        if response.status_code != 429:
            return response

        retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
        time.sleep(retry_after)

    raise Exception("Max retries exceeded")