Fetch Resource

GET/api/v1/idap/{resource_type}/{resource_id}

Overview

Fetch a single resource from any IDAP resource type. Returns the resource data, active flags, and optionally related child resources via the include parameter.

Media Resources

Media resources (idap://media/...) are not supported on this endpoint — use the dedicated Media Proxy endpoint instead. Requesting a media resource here returns 501 Not Implemented.

Path Parameters

resource_typestringrequired

The resource type to fetch.

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

resource_idstringrequired

The unique resource identifier (UUID format).

Query Parameters

fieldsstring

Comma-separated list of fields to return. When omitted, all fields are returned.

Example: fields=name,email,phone,enrichment_score

includestring

Comma-separated list of related resource types to include. Returns nested child resources under the related key.

Example: include=emails,phones

tip

Use include to avoid making separate requests for related data. For example, fetch a business and its associated emails and phone numbers in one call.

formatstringdefault: json

Response format.

Options: json, yaml, md

Response

idap_refstring

The full idap:// reference for this resource (e.g., idap://businesses/abc123).

resource_typestring

The resource type (e.g., businesses).

resource_idstring

The resource identifier.

tenant_idstring

Your client ID (tenant).

created_atdatetime

When this resource was first created.

modified_atdatetime

When this resource was last modified.

flagsarray

List of currently active flags on this resource (e.g., ["qualified", "contacted"]).

dataobject

The resource data fields. Contents vary by resource type. Use fields parameter to project specific fields.

relatedobject

Related child resources, keyed by type. Only present when include parameter is used.

Example: { "emails": [...], "phones": [...] }

Example Request

cURL

curl "https://spideriq.ai/api/v1/idap/businesses/a1b2c3d4-e5f6-7890-abcd-ef1234567890?include=emails,phones" \
  -H "Authorization: Bearer <your_token>"

Python

import httpx

response = httpx.get(
    "https://spideriq.ai/api/v1/idap/businesses/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    params={"include": "emails,phones"},
    headers={"Authorization": "Bearer <your_token>"},
)
data = response.json()
print(data["idap_ref"])       # idap://businesses/a1b2c3d4-...
print(data["flags"])          # ["qualified"]
print(data["related"]["emails"])  # [{"address": "info@...", ...}]

cURL (YAML)

curl "https://spideriq.ai/api/v1/idap/businesses/a1b2c3d4-e5f6-7890-abcd-ef1234567890?format=yaml&fields=name,email,google_rating" \
  -H "Authorization: Bearer <your_token>"

Response Example

{
  "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-03-15T10:00:00Z",
  "modified_at": "2026-04-11T10:32:00Z",
  "flags": ["qualified", "contacted"],
  "data": {
    "name": "Mario's Pizzeria",
    "address": "123 Brickell Ave, Miami FL",
    "category": "Pizza Restaurant",
    "google_rating": 4.6,
    "review_count": 234,
    "website": "https://mariospizzeria.com",
    "source": "spider_maps",
    "campaign_id": "campaign-456"
  },
  "related": {
    "emails": [
      {
        "address": "info@mariospizzeria.com",
        "verified": true,
        "verification_status": "valid"
      }
    ],
    "phones": [
      {
        "number": "+1-305-555-1234",
        "type": "business"
      }
    ]
  }
}

{
  "detail": "resource_not_found"
}

{
  "detail": "Use GET /idap/media/{media_id} for media resources"
}

Field Projection

Use the fields parameter to reduce response size and token cost for AI agents:

# Full response: ~40 fields, ~800 tokens
curl "https://spideriq.ai/api/v1/idap/businesses/abc123" -H "Authorization: Bearer $TOKEN"

# Projected: 4 fields, ~120 tokens (85% savings)
curl "https://spideriq.ai/api/v1/idap/businesses/abc123?fields=name,email,phone,google_rating" \
  -H "Authorization: Bearer $TOKEN"

tip

Always use fields projection when your agent only needs a subset of data. A business record can have 40+ fields after enrichment.