Skip to main content

List / Sync Resources

GET/api/v1/idap/{resource_type}

Overview​

The primary sync endpoint for IDAP. Use cursor-based pagination to page through resources, and the since parameter for delta sync — fetching only resources that changed since your last poll.

This is the IMAP FETCH equivalent: your app stores its last sync cursor, and on each check fetches only what's new or changed.

Media Resources

Media listing is not supported on this endpoint. Use the Media Proxy endpoint to fetch individual media files.

Path Parameters​

resource_typestringrequired

The resource type to list.

Options: businesses, domains, contacts, emails, phones, company_registry, linkedin_profiles

Query Parameters​

sincedatetime

Return resources modified after this ISO 8601 timestamp.

Example: since=2026-04-11T00:00:00Z

untildatetime

Return resources modified before this ISO 8601 timestamp.

Example: until=2026-04-12T00:00:00Z

limitintegerdefault: 100

Maximum number of results per page (1–500).

cursorstring

Opaque cursor from a previous response's next_cursor field. Pass this to get the next page.

fieldsstring

Comma-separated list of fields to return per resource.

Example: fields=name,email,enrichment_score

includestring

Comma-separated list of related resource types to include with each item.

Example: include=emails,phones

formatstringdefault: json

Response format.

Options: json, yaml, md

campaign_idstring

Filter resources by campaign ID.

sourcestring

Filter by source worker.

Options: spider_maps, spider_site, spider_verify, spider_maps_enrich, spider_people, spider_landing, spider_company_data

flagsstring

Filter by flags (comma-separated). Prefix with ! to exclude.

Examples:

  • flags=qualified — only resources with the qualified flag
  • flags=qualified,contacted — resources with both flags
  • flags=!rejected — exclude rejected resources
  • flags=qualified,!rejected — qualified but not rejected
sortstringdefault: created_at

Sort field. Common values: created_at, updated_at, name.

orderstringdefault: desc

Sort order.

Options: asc, desc

Response​

resource_typestring

The resource type being listed.

countinteger

Number of items in this page.

has_moreboolean

Whether more items exist beyond this page.

next_cursorstring

Opaque cursor for fetching the next page. null when there are no more results.

itemsarray

Array of IDAP resources. Each item contains idap_ref, resource_type, resource_id, created_at, modified_at, flags, data, and optionally related.

Example Request​

curl "https://spideriq.ai/api/v1/idap/businesses?since=2026-04-11T00:00:00Z&limit=20&flags=!rejected&format=json" \
  -H "Authorization: Bearer <your_token>"

Response Example

{
  "resource_type": "businesses",
  "count": 3,
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0wNC0xMVQxMDozMjowMFoiLCJpIjoiYTFiMmMzZDQifQ==",
  "items": [
    {
      "idap_ref": "idap://businesses/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "resource_type": "businesses",
      "resource_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tenant_id": "cli_b3q656h2cg8j9o6z",
      "created_at": "2026-04-11T10:00:00Z",
      "modified_at": "2026-04-11T10:32:00Z",
      "flags": ["qualified"],
      "data": {
        "name": "Mario's Pizzeria",
        "email": "info@mariospizzeria.com",
        "google_rating": 4.6
      }
    },
    {
      "idap_ref": "idap://businesses/b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "resource_type": "businesses",
      "resource_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "tenant_id": "cli_b3q656h2cg8j9o6z",
      "created_at": "2026-04-11T11:00:00Z",
      "modified_at": "2026-04-11T14:20:00Z",
      "flags": ["new"],
      "data": {
        "name": "Bella Italia",
        "email": "contact@bellaitalia.com",
        "google_rating": 4.2
      }
    }
  ]
}
{
  "resource_type": "businesses",
  "count": 0,
  "has_more": false,
  "next_cursor": null,
  "items": []
}

Pagination​

Use the next_cursor value from each response to fetch the next page:

# Page 1
curl "https://spideriq.ai/api/v1/idap/businesses?limit=50" \
  -H "Authorization: Bearer $TOKEN"
# Response: { "has_more": true, "next_cursor": "eyJ0Ijo..." }

# Page 2
curl "https://spideriq.ai/api/v1/idap/businesses?limit=50&cursor=eyJ0Ijo..." \
  -H "Authorization: Bearer $TOKEN"
# Response: { "has_more": false, "next_cursor": null }

Delta Sync Pattern​

For efficient incremental sync, store the latest modified_at timestamp from each response and use it as the since parameter on the next poll:

import httpx
from datetime import datetime

last_sync = None  # Store this persistently

while True:
    params = {"limit": 100, "flags": "!rejected"}
    if last_sync:
        params["since"] = last_sync

    response = httpx.get(
        "https://spideriq.ai/api/v1/idap/businesses",
        params=params,
        headers={"Authorization": "Bearer <your_token>"},
    )
    data = response.json()

    for item in data["items"]:
        process_resource(item)
        # Track the latest timestamp
        if item["modified_at"]:
            last_sync = max(last_sync or "", item["modified_at"])

    if not data["has_more"]:
        break
    params["cursor"] = data["next_cursor"]
Sync Frequency

Poll every 30–60 seconds for near-real-time sync. The since parameter ensures you only receive changed resources, keeping each response small.

Default Behavior​

  • Resources with the rejected flag are excluded by default from list responses. To include them, explicitly pass flags=rejected.
  • Results are sorted by created_at DESC by default.
  • All results are scoped to your tenant — no cross-tenant data is ever returned.