Rodz API Reference: Endpoints, Rate Limits and Error Handling

In a nutshell: This is the complete Rodz API reference. It covers every available endpoint (signals, enrichment, webhooks), authentication via Bearer token, rate limiting at 100 requests per minute, error codes, response formats and cursor-based pagination. Bookmark this page and come back whenever you need to check a parameter, a status code or a limit.

What is the Rodz API?

The Rodz API is a RESTful interface that gives you programmatic access to the full Rodz platform. It allows you to create and manage intent signals, enrich company and contact data, and receive real-time notifications through webhooks. Every feature available in the Rodz dashboard can also be controlled through the API.

The API follows REST conventions. It accepts and returns JSON, uses standard HTTP methods (GET, POST, PUT, DELETE) and communicates results through conventional HTTP status codes. Whether you are building a custom integration with your CRM, automating intent-based workflows or syncing enriched data with your internal tools, the API provides a predictable, well-documented interface to do so.

This reference serves as the pillar page for all Rodz technical guides. If you are just getting started, begin with our authentication and first request guide before diving into the details below.

Prerequisites

Before using the Rodz API, make sure you have the following in place:

1. An active Rodz account with API access enabled. API access is available on all paid plans.
2. An API key generated from your Rodz dashboard under Settings > API Keys. Keep this key secret and never expose it in client-side code.
3. A tool for making HTTP requests. This can be cURL, Postman, Insomnia, or any HTTP client library in your preferred programming language (Python requests, Node.js axios, etc.).
4. Basic knowledge of REST APIs. You should be comfortable with HTTP methods, JSON payloads, and header-based authentication.
5. Familiarity with your integration target. Know where the data should flow, whether that is your CRM, a database, a marketing automation tool or a custom application.

For a step-by-step walkthrough of generating your API key and making your first call, see Getting Started with Rodz API Authentication.

Base URL and Authentication

All API requests are made to the following base URL:

https://api.rodz.io/v1

Every request must include your API key in the Authorization header using the Bearer token scheme:

curl -X GET https://api.rodz.io/v1/signals \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

A few important notes on authentication:

• API keys are tied to your organization. Any member with admin privileges can generate or revoke keys.
• Keys do not expire automatically, but you can rotate them at any time from the dashboard.
• If a request is made without a valid token, the API returns a 401 Unauthorized response.
• If your token is valid but lacks permission for the requested resource, you will receive a 403 Forbidden response.

Never include your API key in query parameters, URLs, or front-end code. Always pass it through the Authorization header.

Signal Endpoints

Signals are the core of the Rodz platform. They represent detectable business events (funding rounds, job postings, leadership changes, product launches, etc.) that indicate buyer intent or a window of opportunity.

The signal endpoints allow you to create, read, update, delete and query signals programmatically. Here is the complete list:

Method	Endpoint	Description
GET	/signals	List all configured signals with pagination
GET	/signals/{id}	Retrieve a single signal by its unique ID
POST	/signals	Create a new signal configuration
PUT	/signals/{id}	Update an existing signal configuration
DELETE	/signals/{id}	Delete a signal configuration
GET	/signals/{id}/matches	Retrieve companies matching a specific signal
GET	/signals/feed	Get the real-time feed of all triggered signals

Key parameters for signal creation

When creating or updating a signal via POST /signals or PUT /signals/{id}, the request body accepts the following fields:

• name (string, required): A human-readable name for the signal.
• type (string, required): The signal type. Accepted values include funding, hiring, leadership_change, product_launch, expansion, partnership, acquisition.
• filters (object, optional): Filtering criteria such as industry, company size, geography or funding amount thresholds.
• status (string, optional): Either active or paused. Defaults to active.
• notification_channels (array, optional): Where to send alerts. Options include webhook, email, slack.

For a detailed guide on configuring your first signal, refer to Configure Your First Intent Signal via the Rodz API.

Signal feed

The /signals/feed endpoint is particularly powerful. It returns a chronological stream of all triggered signal events across your active configurations. Each entry includes the signal type, the matched company, a timestamp and the raw event data that triggered the match.

{
  "data": [
    {
      "id": "evt_abc123",
      "signal_id": "sig_def456",
      "signal_name": "Series A Funding",
      "company": {
        "id": "comp_789",
        "name": "Acme Corp",
        "domain": "acme.com"
      },
      "event_type": "funding",
      "event_data": {
        "round": "Series A",
        "amount": 15000000,
        "currency": "USD",
        "date": "2026-03-01"
      },
      "triggered_at": "2026-03-01T10:30:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImV2dF9hYmMxMjQifQ==",
    "has_more": true
  }
}

Enrichment Endpoints

The enrichment endpoints allow you to look up and enrich company and contact data. This is useful for filling gaps in your CRM, qualifying leads or building detailed prospect profiles before outreach.

Method	Endpoint	Description
GET	/enrichment/company	Enrich a company by domain
GET	/enrichment/company/{id}	Retrieve a previously enriched company
POST	/enrichment/company/bulk	Enrich multiple companies in a single request
GET	/enrichment/contact	Enrich a contact by email or LinkedIn URL
GET	/enrichment/contact/{id}	Retrieve a previously enriched contact
POST	/enrichment/contact/bulk	Enrich multiple contacts in a single request
GET	/enrichment/company/{id}/contacts	List contacts associated with an enriched company
GET	/enrichment/company/{id}/signals	Get signals associated with an enriched company
GET	/enrichment/company/{id}/technographics	Get technology stack for a company
GET	/enrichment/contact/{id}/social	Get social media profiles for a contact
GET	/enrichment/jobs	Search current job postings by company or criteria
GET	/enrichment/news	Search recent news articles by company or topic

Company enrichment

To enrich a company, pass its domain as a query parameter:

curl -X GET "https://api.rodz.io/v1/enrichment/company?domain=acme.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes firmographic data such as company name, industry, employee count, headquarters location, revenue estimate, founding year, social profiles and more.

Contact enrichment

Contact enrichment works similarly. You can query by email address or LinkedIn profile URL:

curl -X GET "https://api.rodz.io/v1/enrichment/contact?email=jane@acme.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

The returned data includes the contact’s full name, current job title, company, seniority level, location and verified contact information.

Bulk enrichment

For large-scale operations, use the bulk endpoints. Submit an array of up to 100 domains (for companies) or 100 emails/LinkedIn URLs (for contacts) in a single request:

{
  "items": [{ "domain": "acme.com" }, { "domain": "globex.io" }, { "domain": "initech.co" }]
}

Bulk requests are processed asynchronously. The response includes a job_id that you can poll or receive results via webhook.

Webhook Endpoints

Webhooks let you receive real-time push notifications when signals are triggered, rather than polling the API. This is the recommended approach for production integrations that need to react to events as they happen.

Method	Endpoint	Description
GET	/webhooks	List all registered webhooks
POST	/webhooks	Register a new webhook endpoint
PUT	/webhooks/{id}	Update a webhook configuration
DELETE	/webhooks/{id}	Delete a registered webhook

Registering a webhook

To register a webhook, send a POST request with the target URL and the event types you want to subscribe to:

{
  "url": "https://your-app.com/webhooks/rodz",
  "events": ["signal.triggered", "enrichment.completed", "signal.created"],
  "secret": "your_signing_secret"
}

The secret field is used to sign webhook payloads. When Rodz sends a webhook to your endpoint, it includes an X-Rodz-Signature header containing an HMAC-SHA256 signature of the request body. Always verify this signature to ensure the request genuinely comes from Rodz.

Webhook payload format

When a signal is triggered, Rodz sends a POST request to your registered URL with a JSON body:

{
  "event": "signal.triggered",
  "timestamp": "2026-03-05T14:22:00Z",
  "data": {
    "signal_id": "sig_def456",
    "signal_name": "Series A Funding",
    "company": {
      "id": "comp_789",
      "name": "Acme Corp",
      "domain": "acme.com"
    },
    "event_type": "funding",
    "event_data": {
      "round": "Series A",
      "amount": 15000000,
      "currency": "USD"
    }
  }
}

Your endpoint must respond with a 200 status code within 10 seconds. If it fails or times out, Rodz retries up to 5 times with exponential backoff (30s, 2min, 10min, 1h, 6h).

For the full webhook setup guide, see Real-Time Intent Signals: Setting Up Rodz Webhooks.

Rate Limiting

The Rodz API enforces rate limits to ensure fair usage and platform stability.

Current limit: 100 requests per minute per API key.

Rate limit information is included in every API response via the following headers:

Header	Description
X-RateLimit-Limit	Maximum number of requests allowed per window (100)
X-RateLimit-Remaining	Number of requests remaining in the current window
X-RateLimit-Reset	Unix timestamp indicating when the rate limit window resets

Handling rate limits

When you exceed the limit, the API returns a 429 Too Many Requests response:

{
  "error": {
    "code": 429,
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after the reset time.",
    "retry_after": 34
  }
}

The retry_after field tells you how many seconds to wait before making another request. Best practices for handling rate limits:

1. Monitor the headers. Check X-RateLimit-Remaining before each request. If it is getting low, slow down.
2. Implement exponential backoff. When you receive a 429 response, wait the duration specified in retry_after, then gradually increase the wait time if the error persists.
3. Use bulk endpoints. Instead of making 100 individual enrichment calls, batch them into a single bulk request. This counts as one request against your rate limit.
4. Cache responses. If you are requesting the same data multiple times, cache the result locally to avoid unnecessary calls.
5. Queue requests. Use a job queue or rate limiter library in your application to throttle outgoing requests to stay within limits.

If your use case requires higher limits, contact the Rodz team to discuss enterprise plans.

Error Codes

The Rodz API uses standard HTTP status codes to indicate the outcome of a request. Here is a complete reference of the codes you may encounter:

Status Code	Name	Description
200	OK	The request succeeded. The response body contains the requested data.
201	Created	A new resource was successfully created (e.g., a new signal or webhook).
400	Bad Request	The request body is malformed, a required field is missing, or a parameter value is invalid. Check the error message for details.
401	Unauthorized	No API key was provided, or the key is invalid. Verify your Authorization header.
403	Forbidden	The API key is valid but does not have permission to access the requested resource. Check your plan or permissions.
404	Not Found	The requested resource does not exist. Verify the ID or endpoint path.
429	Too Many Requests	You have exceeded the rate limit. Wait for the duration specified in retry_after before retrying.
500	Internal Server Error	Something went wrong on the Rodz side. If the problem persists, contact support.

Error response format

All error responses follow a consistent structure:

{
  "error": {
    "code": 400,
    "type": "validation_error",
    "message": "The field 'type' is required when creating a signal.",
    "details": [
      {
        "field": "type",
        "issue": "required",
        "message": "Signal type must be one of: funding, hiring, leadership_change, product_launch, expansion, partnership, acquisition."
      }
    ]
  }
}

The error object always includes code, type and message. The details array is present when there are field-level validation errors, giving you precise information about what needs to be corrected.

Common error types

Type	Description
validation_error	One or more request fields failed validation.
authentication_error	The API key is missing or invalid.
authorization_error	The API key lacks the required permissions.
not_found	The resource with the given ID does not exist.
rate_limit_exceeded	Too many requests in the current time window.
internal_error	An unexpected error on the server. These are rare and typically resolve on their own.

Response Format

All successful API responses return JSON with a consistent structure. Understanding this format will help you parse responses reliably across all endpoints.

Single resource response

When retrieving a single resource (e.g., GET /signals/{id}), the response wraps the data in a data object:

{
  "data": {
    "id": "sig_def456",
    "name": "Series A Funding",
    "type": "funding",
    "status": "active",
    "filters": {
      "industries": ["saas", "fintech"],
      "min_amount": 5000000
    },
    "created_at": "2026-02-15T09:00:00Z",
    "updated_at": "2026-03-01T14:30:00Z"
  }
}

List response

When retrieving a collection (e.g., GET /signals), the response includes a data array and a pagination object:

{
  "data": [
    { "id": "sig_001", "name": "Funding Rounds", "type": "funding", "status": "active" },
    { "id": "sig_002", "name": "New Hires VP+", "type": "hiring", "status": "active" }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6InNpZ18wMDMifQ==",
    "has_more": true
  },
  "meta": {
    "total_count": 47
  }
}

Common fields

Every resource includes these standard fields:

• id (string): A unique identifier prefixed by the resource type (e.g., sig_, comp_, evt_, wh_).
• created_at (string): ISO 8601 timestamp of when the resource was created.
• updated_at (string): ISO 8601 timestamp of the last modification.

Pagination

The Rodz API uses cursor-based pagination for all list endpoints. This approach is more reliable than offset-based pagination, especially when dealing with real-time data where new records can be inserted at any time.

How it works

Every list endpoint accepts two query parameters:

Parameter	Type	Default	Description
cursor	string	(none)	An opaque cursor pointing to the next page of results. Omit on the first request.
limit	integer	25	Number of results per page. Minimum 1, maximum 100.

Paginating through results

Start with a simple request without a cursor:

curl -X GET "https://api.rodz.io/v1/signals?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes a pagination object:

{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6InNpZ18wMTEifQ==",
    "has_more": true
  }
}

To get the next page, pass the next_cursor value as the cursor parameter:

curl -X GET "https://api.rodz.io/v1/signals?limit=10&cursor=eyJpZCI6InNpZ18wMTEifQ==" \
  -H "Authorization: Bearer YOUR_API_KEY"

Continue this process until has_more is false, which indicates you have reached the last page.

Pagination best practices

• Always check has_more before requesting the next page. Do not assume there are more results.
• Do not modify or construct cursors manually. They are opaque tokens generated by the server.
• Use a consistent limit value across all pages of the same query to avoid unexpected behavior.
• For large exports, consider using the bulk enrichment endpoints or contacting support for a data export.

Putting It All Together

Here is a practical example that ties together authentication, signal creation, feed polling and error handling in a single workflow:

import requests
import time

API_KEY = "your_api_key_here"
BASE_URL = "https://api.rodz.io/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Step 1: Create a signal
signal_payload = {
    "name": "Series B+ Funding in SaaS",
    "type": "funding",
    "filters": {
        "industries": ["saas"],
        "min_amount": 10000000
    },
    "notification_channels": ["webhook"]
}

response = requests.post(f"{BASE_URL}/signals", json=signal_payload, headers=HEADERS)

if response.status_code == 201:
    signal = response.json()["data"]
    print(f"Signal created: {signal['id']}")
elif response.status_code == 429:
    retry_after = response.json()["error"]["retry_after"]
    print(f"Rate limited. Retrying in {retry_after} seconds.")
    time.sleep(retry_after)
else:
    print(f"Error: {response.status_code} - {response.json()['error']['message']}")

# Step 2: Poll the signal feed with pagination
cursor = None
all_events = []

while True:
    params = {"limit": 50}
    if cursor:
        params["cursor"] = cursor

    feed_response = requests.get(f"{BASE_URL}/signals/feed", params=params, headers=HEADERS)

    if feed_response.status_code == 200:
        data = feed_response.json()
        all_events.extend(data["data"])
        if data["pagination"]["has_more"]:
            cursor = data["pagination"]["next_cursor"]
        else:
            break
    elif feed_response.status_code == 429:
        retry_after = feed_response.json()["error"]["retry_after"]
        time.sleep(retry_after)
    else:
        break

print(f"Fetched {len(all_events)} signal events.")

This example demonstrates proper error handling, rate limit respect and cursor-based pagination in a real-world script.

Frequently Asked Questions

What is the base URL for the Rodz API?

All requests go to https://api.rodz.io/v1. This is the only supported API version. All endpoints are relative to this base URL.

How do I authenticate my API requests?

Include your API key in the Authorization header using the Bearer scheme: Authorization: Bearer YOUR_API_KEY. Never pass your key as a query parameter or in the request body. For full setup instructions, see the authentication guide.

What happens when I exceed the rate limit?

The API returns a 429 Too Many Requests response with a retry_after value in seconds. Wait for that duration, then retry. You can monitor your remaining quota via the X-RateLimit-Remaining response header on every request.

Does the API support bulk operations?

Yes. The enrichment endpoints support bulk requests for both companies and contacts. You can submit up to 100 items per bulk request. Bulk operations are processed asynchronously, and you receive a job_id to track progress.

How does cursor-based pagination work?

On your first request, omit the cursor parameter. The response includes a pagination.next_cursor value. Pass that value as the cursor parameter on the next request. Repeat until pagination.has_more is false.

Can I receive signal events in real time without polling?

Yes. Register a webhook via POST /webhooks to receive push notifications whenever a signal is triggered. This eliminates the need to poll the feed endpoint. See our webhook setup guide for details.

What enrichment data is available for companies?

Company enrichment returns firmographic data including company name, domain, industry, employee count, revenue estimate, headquarters location, founding year, social profiles and technology stack. You can also retrieve associated contacts and recent signals for any enriched company.

Where can I find the full interactive API documentation?

The complete interactive documentation with request/response examples, parameter descriptions and a live testing console is available at api.rodz.io/docs. Use it alongside this reference to explore endpoints interactively.

Next Steps

This reference covers the entire Rodz API surface area. Here is where to go next depending on your goal:

• First time integrating? Start with Getting Started: Authentication and Your First Request.
• Setting up signals? Follow the Configure Your First Intent Signal guide.
• Need real-time delivery? Set up webhooks with the Webhook Setup Guide.
• Want to explore interactively? Visit the Rodz API Docs.

If you run into any issues or need higher rate limits for your use case, reach out to the Rodz team. We are here to help you get the most out of the platform.