Write Flags

POST/api/v1/idap/{resource_type}/{resource_id}/flags

Overview

Flags are the bidirectional state layer between your app and SpiderIQ. SpiderIQ owns the data fields (name, email, rating, etc.). Your app writes flags to annotate resources with business state (qualified, contacted, rejected, etc.). Both sides respect each other's writes.

Flags are the only write surface your app has on SpiderIQ data — a clean boundary that keeps data ownership clear.

Media Resources

Flags are not supported on media resources. Returns 400 Bad Request.

Path Parameters

resource_typestringrequired

The resource type.

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

resource_idstringrequired

The resource identifier.

Request Body

addarray

List of flag names to add. Max 20 flags per request. Each flag name must be 1–50 characters.

Example: ["qualified", "priority"]

removearray

List of flag names to remove. Max 20 flags per request.

Example: ["new"]

flagged_bystringrequired

Identifies who is setting the flag. Use the format agent:<name> for AI agents or user:<name> for human users.

Examples: "agent:maya_001", "user:martin", "system:auto_qualify"

reasonstring

Optional human-readable reason for the flag change. Max 1000 characters. Stored in flag history for audit.

Example: "4.6 star rating, verified email, recently opened"

Flag Vocabulary

Use standardized flag names for consistent behavior across your workflows:

Lifecycle Flags (set by your app)

Flag	Meaning
new	Freshly discovered, not yet reviewed
in_progress	Currently being worked on
qualified	Meets qualification criteria
converted	Successfully converted (deal closed, meeting booked, etc.)
closed	No longer active

Disposition Flags (set by your app)

Flag	Meaning
interested	Lead showed interest
not_interested	Lead explicitly declined
no_response	No response after outreach
opted_out	Lead opted out of communications

Quality Flags (set by either side)

Flag	Meaning
priority	High-priority resource
low_quality	Poor data quality
duplicate	Potential duplicate (triggers FuzzIQ merge review)
stale	Data is outdated

Contact Flags (set by either side)

Flag	Meaning
contacted	Outreach has been made
do_not_contact	Do not contact — SpiderIQ prevents all outreach workers from touching this resource
bounced	Email/phone bounced

Processing Flags (set by SpiderIQ)

Flag	Meaning
enriching	Currently being enriched by a worker
verifying	Email verification in progress
crawling	Website crawl in progress

Rejection (set by your app)

Flag	Meaning
rejected	Resource is rejected — excluded from list/sync responses by default

Behavioral Rules

Important

These flags trigger side effects beyond simple annotation:

Flag	Behavior
rejected	Resource excluded from all list/sync responses unless explicitly requested with flags=rejected
do_not_contact	SpiderIQ prevents all outreach workers from touching this resource across all campaigns for your tenant
duplicate	Triggers FuzzIQ merge review — a deduplication process that may merge this resource with others

Flag history is append-only. Even when a flag is removed, the history entry persists with a removed_at timestamp. This provides a full audit trail of all flag changes.

Response

idap_refstring

The idap:// reference for the flagged resource.

flagsarray

List of currently active flags after the write.

flag_historyarray

Recent flag history entries (most recent first). Each entry contains:

• action — "add" or "remove"
• flag — the flag name
• flagged_by — who made the change
• reason — optional reason
• at — ISO 8601 timestamp

Example Request

cURL

curl -X POST "https://spideriq.ai/api/v1/idap/businesses/a1b2c3d4/flags" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "add": ["qualified", "priority"],
    "remove": ["new"],
    "flagged_by": "agent:maya_001",
    "reason": "4.6 star rating, verified email, recently opened"
  }'

Python

import httpx

response = httpx.post(
    "https://spideriq.ai/api/v1/idap/businesses/a1b2c3d4/flags",
    headers={"Authorization": "Bearer <your_token>"},
    json={
        "add": ["qualified", "priority"],
        "remove": ["new"],
        "flagged_by": "agent:maya_001",
        "reason": "4.6 star rating, verified email, recently opened",
    },
)
result = response.json()
print(f"Active flags: {result['flags']}")

JavaScript

const response = await fetch(
  "https://spideriq.ai/api/v1/idap/businesses/a1b2c3d4/flags",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer <your_token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      add: ["qualified", "priority"],
      remove: ["new"],
      flagged_by: "agent:maya_001",
      reason: "4.6 star rating, verified email, recently opened",
    }),
  }
);
const result = await response.json();
console.log("Active flags:", result.flags);

Response Example

{
  "idap_ref": "idap://businesses/a1b2c3d4",
  "flags": ["qualified", "priority", "contacted"],
  "flag_history": [
    {
      "action": "add",
      "flag": "qualified",
      "flagged_by": "agent:maya_001",
      "reason": "4.6 star rating, verified email, recently opened",
      "at": "2026-04-11T10:35:00Z"
    },
    {
      "action": "add",
      "flag": "priority",
      "flagged_by": "agent:maya_001",
      "reason": "4.6 star rating, verified email, recently opened",
      "at": "2026-04-11T10:35:00Z"
    },
    {
      "action": "remove",
      "flag": "new",
      "flagged_by": "agent:maya_001",
      "reason": "4.6 star rating, verified email, recently opened",
      "at": "2026-04-11T10:35:00Z"
    }
  ]
}

{
  "detail": "resource_not_found"
}

Idempotency

Flag writes are safe to retry:

• Adding a flag that already exists is a no-op — no duplicate flag is created, no error returned
• Removing a flag that doesn't exist is a no-op — no error returned
• The response always reflects the current state after the write