Resolve Resource

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

Overview

Look up a single resource by an external identifier instead of its internal UUID. This is the read-side primitive for dynamic landing pages, agent workflows, and any integration where you know a stable key like a Google Place ID, domain, VAT number, or VayaPin pin name — but not the SpiderIQ UUID.

The response shape matches Fetch Resource (idap_ref, flags, data, optional related), so the same client code that handles GET /{type}/{id} works here.

Tutorial

For an end-to-end walkthrough using this endpoint to personalize a landing page per lead, see the Personalized Landing Page tutorial.

Rules

• Exactly one identifier query parameter must be provided. Passing zero or more than one returns 400.
• The identifier must be valid for the resource type (see the matrix below). Passing place_id to /contacts/resolve, for example, returns 400 with the allowed key list for that type.
• A successful lookup returns one resource. A miss returns 404 (resource_not_found).
• All lookups are scoped to your tenant. Cross-tenant identifiers return 404 (not 403).
• media is not a valid resource type for this endpoint — use the Media Proxy instead (400).

Path Parameters

resource_typestringrequired

The resource type to resolve.

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

Query Parameters — Identifier Matrix

Exactly one of these must be supplied, and it must be valid for the chosen resource_type:

Identifier	Valid resource types	Notes
place_id	businesses	Google Maps CID / Place ID (e.g. 0x47e66fdad6f1cc73:0x341211b3fccd79e1)
domain	businesses, domains	Primary domain on the business row, or the canonical record in domains
email	emails, contacts	Email address (lowercase) — emails returns the verification record, contacts returns the person
linkedin	contacts	Contact's LinkedIn profile URL
twitter	contacts	Contact's X / Twitter profile URL
url	linkedin_profiles	The profile URL stored on linkedin_profiles.linkedin_url
vat	company_registry	VAT number (matches company_registry.vat_number)
registration_number	company_registry	Local company-registry number
lei	company_registry	Legal Entity Identifier
tax_id	company_registry	Tax ID (US EIN, etc.)
source_id	company_registry	The source_id half of the composite (source, source_id) key
pin_name	businesses, pins	VayaPin pin name (e.g. BB:TAPAS). On businesses, the server joins via pins.business_id.
pin_data_set_id	businesses, pins	VayaPin pin data-set UUID. Joined-key on businesses.
account_id	businesses, pins	VayaPin account UUID. Joined-key on businesses.
pin_subscription_id	businesses, pins	VayaPin subscription UUID. Joined-key on businesses.

Joined keys on businesses (Wave D.1)

The four VayaPin pin keys — pin_name, pin_data_set_id, account_id, pin_subscription_id — live on the pins table, not on businesses. The server resolves them via JOIN pins ON pins.business_id = businesses.id, scoped to your tenant. Use these to walk from a VayaPin callback's pin identifier directly to the parent business in one call.

Common Query Parameters

includestring

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

Example (businesses): include=emails,phones,pins,contacts

fieldsstring

Comma-separated list of fields to return on the resolved resource (server projects the response).

Example: fields=name,email,domain,google_rating

formatstringdefault: json

Response format.

Options: json, yaml, md

Response

idap_refstring

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

resource_typestring

The resource type that was resolved.

resource_idstring

The internal UUID of the resolved resource — use this with Fetch Resource, Write Flags, or Delete Business.

tenant_idstring

Your client ID (tenant).

created_atdatetime

When the resource was first created.

modified_atdatetime

When the resource was last modified.

flagsarray

Currently active flags (e.g., ["qualified", "contacted"]).

dataobject

The resource data — same shape as Fetch Resource for the matching resource_type.

relatedobject

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

Examples

By Google Place ID

curl "https://spideriq.ai/api/v1/idap/businesses/resolve?place_id=0x47e66fdad6f1cc73:0x341211b3fccd79e1&include=emails,phones" \
  -H "Authorization: Bearer $TOKEN"

By domain

curl "https://spideriq.ai/api/v1/idap/businesses/resolve?domain=mariospizzeria.com&include=emails,phones" \
  -H "Authorization: Bearer $TOKEN"

By VayaPin pin_name

# Walks pins.business_id → businesses.id server-side
curl "https://spideriq.ai/api/v1/idap/businesses/resolve?pin_name=BB:TAPAS&include=emails,phones,pins" \
  -H "Authorization: Bearer $TOKEN"

By VAT

curl "https://spideriq.ai/api/v1/idap/company_registry/resolve?vat=GB123456789" \
  -H "Authorization: Bearer $TOKEN"

By email (contacts)

curl "https://spideriq.ai/api/v1/idap/contacts/resolve?email=jane@mariospizzeria.com" \
  -H "Authorization: Bearer $TOKEN"

By LinkedIn URL (profiles)

curl "https://spideriq.ai/api/v1/idap/linkedin_profiles/resolve?url=https://linkedin.com/in/janedoe" \
  -H "Authorization: Bearer $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-05-24T08:12:00Z",
  "flags": ["qualified"],
  "data": {
    "name": "Mario's Pizzeria",
    "domain": "mariospizzeria.com",
    "google_place_id": "0x47e66fdad6f1cc73:0x341211b3fccd79e1",
    "google_rating": 4.6,
    "city": "Miami",
    "country_code": "US"
  },
  "related": {
    "emails": [
      { "address": "info@mariospizzeria.com", "verified": true }
    ],
    "phones": [
      { "number": "+1-305-555-1234" }
    ]
  }
}

{
  "detail": "Provide exactly one identifier: place_id, domain, email, url, linkedin, twitter, vat, registration_number, lei, tax_id, source_id, pin_name, pin_data_set_id, account_id, or pin_subscription_id"
}

{
  "detail": "Provide exactly one identifier, not multiple"
}

{
  "detail": "Identifier 'place_id' is not valid for resource type 'contacts'. Allowed: ['email', 'linkedin', 'twitter']"
}

{
  "detail": "resource_not_found"
}

After Resolving

The resource_id returned here is the UUID. Pipe it into any of the other IDAP endpoints:

# Read full record with all related types
curl "https://spideriq.ai/api/v1/idap/businesses/$RESOURCE_ID?include=emails,phones,pins,contacts" \
  -H "Authorization: Bearer $TOKEN"

# Flag the lead as qualified
curl -X POST "https://spideriq.ai/api/v1/idap/businesses/$RESOURCE_ID/flags" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"add": ["qualified"], "flagged_by": "agent:landing-page"}'

# Hard-delete a confirmed duplicate (see Delete Business)
curl -X DELETE "https://spideriq.ai/api/v1/idap/businesses/$RESOURCE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"reason": "merged into 6f...c1"}'