Skip to content

Company Profile Endpoints ​

Manage the organization's Intelligence Profile — sensitive terms, classification policies, and detection settings.

Authentication

All endpoints require a valid bearer token. Write operations (PUT, POST, DELETE) require the Owner or Admin role.

Get Company Profile ​

Retrieve the full Company Intelligence Profile for an organization.

GET /api/intelligence-profiles/company/{orgId}

Parameters ​

ParameterInTypeRequiredDescription
orgIdpathstringYesOrganization ID

Response ​

json
{
  "org_id": "org_abc123",
  "sensitivity_floor": "balanced",
  "classification_policy": {
    "categories": [
      {
        "name": "project_codename",
        "display_name": "Project Codenames",
        "default_sensitivity": "critical",
        "compliance_tags": ["SOC2"]
      },
      {
        "name": "customer_name",
        "display_name": "Customer Names",
        "default_sensitivity": "high",
        "compliance_tags": []
      }
    ]
  },
  "safe_terms": [
    {
      "term": "GhostAI",
      "reason": "Public product name"
    }
  ],
  "term_count": 42,
  "created_at": "2025-09-15T10:30:00Z",
  "updated_at": "2026-02-20T14:22:00Z"
}
FieldTypeDescription
org_idstringOrganization identifier
sensitivity_floorstringMinimum sensitivity level: relaxed, balanced, strict
classification_policyobjectCategory definitions for organizing terms
safe_termsarrayAllowlisted terms that bypass detection
term_countnumberTotal registered sensitive terms
created_atstringProfile creation timestamp (ISO 8601)
updated_atstringLast modification timestamp (ISO 8601)

Update Company Profile ​

Update the Company Intelligence Profile settings.

PUT /api/intelligence-profiles/company/{orgId}

Parameters ​

ParameterInTypeRequiredDescription
orgIdpathstringYesOrganization ID

Request ​

json
{
  "sensitivity_floor": "strict",
  "classification_policy": {
    "categories": [
      {
        "name": "project_codename",
        "display_name": "Project Codenames",
        "default_sensitivity": "critical",
        "compliance_tags": ["SOC2", "ITAR"]
      }
    ]
  },
  "safe_terms": [
    {
      "term": "GhostAI",
      "reason": "Public product name"
    }
  ]
}
FieldTypeRequiredDescription
sensitivity_floorstringNorelaxed, balanced, or strict
classification_policyobjectNoUpdated category definitions
safe_termsarrayNoUpdated safe terms allowlist

All fields are optional. Only provided fields are updated.

Response ​

Returns the updated profile (same schema as GET).

List Terms ​

Retrieve all registered sensitive terms for an organization.

GET /api/intelligence-profiles/company/{orgId}/terms

Parameters ​

ParameterInTypeRequiredDescription
orgIdpathstringYesOrganization ID
categoryquerystringNoFilter by category
sensitivityquerystringNoFilter by sensitivity level
pagequerynumberNoPage number (default: 1)
per_pagequerynumberNoItems per page (default: 50, max: 200)

Response ​

json
{
  "terms": [
    {
      "id": "term_x1y2z3",
      "term": "Project Falcon",
      "category": "project_codename",
      "sensitivity": "critical",
      "metadata": {
        "added_by": "admin@company.com",
        "notes": "FY26 strategic initiative"
      },
      "created_at": "2026-01-10T08:00:00Z"
    },
    {
      "id": "term_a1b2c3",
      "term": "Acme Corp",
      "category": "customer_name",
      "sensitivity": "high",
      "metadata": {},
      "created_at": "2026-01-12T14:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 50
}

Add Term ​

Register a new sensitive term.

POST /api/intelligence-profiles/company/{orgId}/terms

Parameters ​

ParameterInTypeRequiredDescription
orgIdpathstringYesOrganization ID

Request ​

json
{
  "term": "Project Falcon",
  "category": "project_codename",
  "sensitivity": "critical",
  "metadata": {
    "notes": "FY26 strategic initiative"
  }
}
FieldTypeRequiredDescription
termstringYesWord or phrase to detect (case-insensitive)
categorystringYesClassification category (must exist in policy)
sensitivitystringNolow, medium, high, critical — defaults to category default
metadataobjectNoFree-form metadata for audit and reporting

Response ​

json
{
  "id": "term_x1y2z3",
  "term": "Project Falcon",
  "category": "project_codename",
  "sensitivity": "critical",
  "metadata": {
    "notes": "FY26 strategic initiative"
  },
  "created_at": "2026-02-25T10:00:00Z"
}

Status: 201 Created

Bulk Add Terms ​

Register multiple terms in a single request.

POST /api/intelligence-profiles/company/{orgId}/terms/bulk

Parameters ​

ParameterInTypeRequiredDescription
orgIdpathstringYesOrganization ID

Request ​

json
{
  "terms": [
    {
      "term": "Project Falcon",
      "category": "project_codename",
      "sensitivity": "critical"
    },
    {
      "term": "Acme Corp",
      "category": "customer_name",
      "sensitivity": "high"
    },
    {
      "term": "NeuralForge",
      "category": "product",
      "sensitivity": "medium"
    }
  ]
}
FieldTypeRequiredDescription
termsarrayYesArray of term objects (same schema as Add Term)

Response ​

json
{
  "created": 3,
  "skipped": 0,
  "errors": [],
  "terms": [
    {
      "id": "term_x1y2z3",
      "term": "Project Falcon",
      "category": "project_codename",
      "sensitivity": "critical",
      "created_at": "2026-02-25T10:00:00Z"
    },
    {
      "id": "term_a1b2c3",
      "term": "Acme Corp",
      "category": "customer_name",
      "sensitivity": "high",
      "created_at": "2026-02-25T10:00:00Z"
    },
    {
      "id": "term_d4e5f6",
      "term": "NeuralForge",
      "category": "product",
      "sensitivity": "medium",
      "created_at": "2026-02-25T10:00:00Z"
    }
  ]
}
FieldTypeDescription
creatednumberNumber of terms successfully created
skippednumberNumber of duplicate terms skipped
errorsarrayValidation errors for individual terms
termsarraySuccessfully created terms

Status: 201 Created

Delete Term ​

Remove a sensitive term from the registry.

DELETE /api/intelligence-profiles/company/{orgId}/terms/{termId}

Parameters ​

ParameterInTypeRequiredDescription
orgIdpathstringYesOrganization ID
termIdpathstringYesTerm ID to delete

Response ​

Status: 204 No Content

Auto-Research Company ​

Research a company from public information and return structured suggestions for the Company Intelligence Profile. This endpoint does not save anything — use the standard PUT/POST endpoints to apply the suggestions.

POST /api/intelligence-profiles/company/{orgId}/auto-research

Parameters ​

ParameterInTypeRequiredDescription
orgIdpathstringYesOrganization ID

Request ​

json
{
  "company_name": "Acme Technologies",
  "domain": "acme.com",
  "website_url": "https://www.acme.com"
}
FieldTypeRequiredDescription
company_namestringNoCompany name to research. Falls back to organization name if omitted.
domainstringNoCompany domain for website scraping. Falls back to admin email domain if omitted.
website_urlstringNoDirect URL to the company website

All fields are optional. If company_name is not provided and cannot be inferred from the organization, a 400 error is returned.

Response ​

json
{
  "company_description": "Acme Technologies is a fintech platform that processes payment data for small businesses. They handle credit card numbers, bank account details, and merchant transaction records.",
  "industry_details": {
    "sector": "Financial Technology",
    "sub_industry": "Payment Processing",
    "regulated": true
  },
  "products_services": [
    {"name": "AcmePay", "description": "Payment processing API for SMBs"},
    {"name": "Acme Dashboard", "description": "Merchant analytics and reporting"}
  ],
  "data_classification_tiers": [
    {"tier": "Public", "description": "Marketing materials and public docs", "examples": ["blog posts", "pricing page"]},
    {"tier": "Internal", "description": "Internal operations data", "examples": ["employee directory", "internal memos"]},
    {"tier": "Confidential", "description": "Customer and financial data", "examples": ["transaction records", "merchant details"]},
    {"tier": "Restricted", "description": "PCI-regulated cardholder data", "examples": ["credit card numbers", "CVVs"]}
  ],
  "suggested_sensitivity_floor": "paranoid",
  "suggested_sensitive_terms": [
    {"term": "AcmePay", "term_type": "sensitive", "category": "product_codename", "reasoning": "Proprietary payment product name", "source": "https://www.acme.com/products"},
    {"term": "Merchant ID", "term_type": "sensitive", "category": "internal_id", "reasoning": "Internal merchant identifier", "source": "https://www.acme.com/about"}
  ],
  "suggested_safe_terms": [
    {"term": "Acme Technologies", "term_type": "safe", "category": "public_info", "reasoning": "Public company name", "source": "https://www.acme.com/about"},
    {"term": "fintech", "term_type": "safe", "category": "false_positive", "reasoning": "Industry standard term", "source": "https://www.acme.com/about"}
  ],
  "field_confidence": {
    "company_description": 0.92,
    "industry_details": 0.88,
    "products_services": 0.85,
    "data_classification_tiers": 0.78,
    "suggested_sensitivity_floor": 0.80,
    "suggested_sensitive_terms": 0.75,
    "suggested_safe_terms": 0.82
  },
  "research_metadata": {
    "search_queries": [
      "Acme Technologies company overview fintech",
      "Acme Technologies products services payment",
      "Acme Technologies compliance regulations PCI"
    ],
    "pages_scraped": 4,
    "llm_passes": 2,
    "elapsed_seconds": 12.3,
    "domain_discovered": true,
    "detected_vertical": "financial"
  },
  "sources": ["https://www.acme.com/about", "https://www.acme.com/products", "https://www.acme.com/compliance", "https://techcrunch.com/acme-series-b"],
  "confidence": 0.85,
  "warnings": []
}
FieldTypeDescription
company_descriptionstringAI-generated company description
industry_detailsobjectSector, sub-industry, and regulation status
products_servicesarrayIdentified products and services
data_classification_tiersarraySuggested data classification tiers
suggested_sensitivity_floorstringRecommended sensitivity floor
suggested_sensitive_termsarrayTerms suggested as sensitive, with reasoning and source URL
suggested_safe_termsarrayTerms suggested as safe, with reasoning and source URL
field_confidenceobjectPer-field confidence scores (0.0–1.0), computed from source agreement and extraction quality
research_metadataobjectPipeline diagnostics: search_queries (array of queries used), pages_scraped (count), llm_passes (number of LLM passes), elapsed_seconds, domain_discovered (boolean), detected_vertical (string)
sourcesarrayURLs used during research
confidencenumberOverall confidence score (0.0 to 1.0)
warningsarrayAny warnings or limitations encountered

Rate Limiting ​

This endpoint is rate-limited to one request per organization per 5 minutes.

Status: 200 OK

Error Responses ​

All endpoints return standard error responses:

StatusDescription
400Invalid request body or parameters
401Missing or invalid authentication token
403Insufficient permissions (admin role required for writes)
404Organization or term not found
409Duplicate term (on create)
422Validation error (e.g., category does not exist in policy)
json
{
  "error": "forbidden",
  "message": "Admin role required to modify the Company Intelligence Profile",
  "status": 403
}

SOC 2 Type II Certified | BAA Available | HIPAA-Ready