Business intelligence

Get entity data by entity ID

GET /v1/entities/{entity_id}

View as markdown Open in ChatGPT Open in Claude

Retrieve complete entity data using the stable entity ID returned from entity resolution.

Performance & Accuracy: This endpoint prioritizes data accuracy and completeness over speed. For entities not yet in our system, initial processing may take 2-5 minutes as we comprehensively gather and verify information from multiple authoritative sources (business registries, financial databases, etc.). Entities already in our database typically return within seconds. As our database grows, more entities will have instant responses.

This endpoint provides immediate responses with different statuses based on data availability:

building: Initial data compilation is in progress. No data available yet. You should poll this endpoint.
complete: Entity data is complete and current. Data is available and fresh.
refreshing: Previously compiled data is available but a refresh is in progress. You get immediate access to current data while new data is being prepared.

For building and refreshing states, clients should poll this endpoint periodically (recommended interval: 5-10 seconds) until the status becomes "complete".

This design allows multiple customers to efficiently poll the same entity without creating duplicate processing jobs.

Path parameters

entity_idstring required
The stable entity ID returned from entity resolution (e.g., "siq_2ZYEAh7VdPkWsvlsqW9lG")

Responses

200 OK

entity_idstring required
The stable entity ID that was requested
statusstring (enum) required
buildingcompleterefreshing
The current status of the entity data:
- building - Initial data compilation is in progress, no data available yet
- complete - Entity data is complete and current, data is available
- refreshing - Previously compiled data is available but being refreshed
dataobject
The complete entity data (present when status is "complete" or "refreshing")
Show 11 nested fieldsHide nested fields
- idstring
  The stable entity ID
- namestring
  The entity name
- typestring (enum)
  businessnonprofitgovernmentpersonotherunknown
  The entity type
- subtypestring (enum)
  Show 9 possible valuesHide possible values
  incorporated_entityunincorporated_entitynonprofit_entitygovernment_entitynatural_personcomplex_business_structuretrading_name_onlyother_entityunknown
  The entity subtype
- statusstring (enum)
  activeinactive
  The entity status
- headquartersobject
  Show 1 nested fieldHide nested fields
  addressobject
  Show 10 nested fieldsHide nested fields
  citystring
  statestring
  countrystring
  state_codestring
  postal_codestring
  sub_premisestring
  country_codestring
  street_numberstring
  street_addressstring
  formatted_addressstring
- primary_legal_entityobject
  Show 3 nested fieldsHide nested fields
  idstring
  namestring
  jurisdictionobject
  Show 2 nested fieldsHide nested fields
  country_codestring
  state_provincestring
- attributesobject
  Show 14 nested fieldsHide nested fields
  descriptionstring
  websitestring
  domainstring
  employee_countinteger
  Total employee count
  employee_rangestring
  Human-readable employee range bucket
  revenueinteger
  Annual revenue in USD
  revenue_rangestring
  Human-readable revenue range bucket
  founding_datestring <date>
  Date the company was founded (YYYY-MM-DD)
  stock_tickerstring
  Stock ticker symbol
  exchangestring
  Stock exchange where the entity is listed
  is_publicboolean
  Whether the entity is publicly traded
  market_capinteger
  Market capitalization in USD
  funding_total_usdinteger
  Total funding raised in USD
  funding_rounds_countinteger
  Number of funding rounds
- social_profilesobject
  Social media and professional profile handles for the entity
  Show 4 nested fieldsHide nested fields
  crunchbaseobject
  Show 1 nested fieldHide nested fields
  handlestring
  linkedinobject
  Show 1 nested fieldHide nested fields
  handlestring
  facebookobject
  Show 1 nested fieldHide nested fields
  handlestring
  twitterobject
  Show 1 nested fieldHide nested fields
  handlestring
- classificationobject
  Show 5 nested fieldsHide nested fields
  naics_codes_2022array<object>
  Show 5 nested fieldsHide nested fields
  codestring
  namestring
  relevanceinteger
  confidenceinteger
  is_primaryboolean
  sic_codesarray<object>
  Standard Industrial Classification codes
  Show 5 nested fieldsHide nested fields
  codestring
  namestring
  relevanceinteger
  confidenceinteger
  is_primaryboolean
  business_tagsarray<string>
  business_modelarray<string>
  Deprecated. Free-text business-model labels — not a controlled vocabulary, so the values vary between records and between refreshes of the same record, and a single string mixes market segment, revenue model, sales channel and industry. Superseded on the /v3 surface by the enumerated market_segment and revenue_model. This field is unchanged on /v1, is still populated on every response, and has no removal date — no action is required.
  products_servicesarray<string>
- operational_presencearray<object>
  Show 5 nested fieldsHide nested fields
  idstring
  country_codestring
  countrystring
  countinteger
  is_home_jurisdictionboolean
messagestring
Human-readable message about the current status
metadataobject
Show 3 nested fieldsHide nested fields
- last_updatedstring <date-time>
  When the data was last updated
- processing_started_atstring <date-time>
  When processing started (for building/refreshing states)
- estimated_completionstring <date-time>
  Estimated completion time (for building/refreshing states)

400 Bad Request

errorobject
An error object.
Show 2 nested fieldsHide nested fields
- messagestring
  The error message
- typestring
  The error code

401 Unauthorized

messagestring
The error object.
request_idstring
The request ID for the error.

404 Entity not found

messagestring
codestring

500 Internal Server Error

errorobject
An error object.
Show 2 nested fieldsHide nested fields
- messagestring
  The error message
- typestring
  The error code

502 Request timeout

errorobject
An error object.
Show 2 nested fieldsHide nested fields
- messagestring
  The error message
- typestring
  The error code

Example request

cURL

curl --request GET \
  --url 'https://api.savvyiq.ai/v1/entities/siq_2ZYEAh7VdPkWsvlsqW9lG' \
  --header 'apikey: YOUR_API_KEY'

Example response

Entity data complete200

{
  "entity_id": "siq_2ZYEAh7VdPkWsvlsqW9lG",
  "status": "complete",
  "data": {
    "id": "siq_2ZYEAh7VdPkWsvlsqW9lG",
    "name": "Google",
    "type": "business",
    "subtype": "incorporated_entity",
    "status": "active",
    "headquarters": {
      "address": {
        "city": "Mountain View",
        "state": "California",
        "country": "United States",
        "state_code": "CA",
        "postal_code": "94043",
        "sub_premise": null,
        "country_code": "US",
        "street_number": null,
        "street_address": "1600 Amphitheatre Parkway",
        "formatted_address": null
      }
    },
    "primary_legal_entity": {
      "id": "le_2Zp3YaC1I4wgYZpQDPgx8",
      "name": "GOOGLE LLC",
      "jurisdiction": {
        "country_code": "US",
        "state_province": "Delaware"
      }
    },
    "attributes": {
      "description": "Google LLC is a global technology company specializing in internet-related services and products. Its core business revolves around online advertising and search engine technology. The company also focuses on cloud computing, computer software, quantum computing, e-commerce, consumer electronics, and artificial intelligence (AI). Google's mission is to organize the world's information and make it universally accessible and useful.",
      "website": "https://goo.gle/3DLEokh",
      "domain": "goo.gle",
      "employee_count": 10001,
      "employee_range": "10K+",
      "revenue": 256700000000,
      "revenue_range": "$10B+",
      "founding_date": "1998-09-04",
      "stock_ticker": null,
      "exchange": null,
      "is_public": null,
      "market_cap": null,
      "funding_total_usd": null,
      "funding_rounds_count": null
    },
    "social_profiles": {
      "crunchbase": {
        "handle": "google"
      },
      "linkedin": {
        "handle": "company/google"
      },
      "facebook": {
        "handle": "Google"
      }
    },
    "classification": {
      "naics_codes_2022": [
        {
          "code": "541511",
          "name": "Custom Computer Programming Services",
          "relevance": 90,
          "confidence": 100,
          "is_primary": false
        },
        {
          "code": "518210",
          "name": "Computing Infrastructure Providers, Data Processing, Web Hosting, and Related Services",
          "relevance": 90,
          "confidence": 100,
          "is_primary": false
        },
        {
          "code": "541512",
          "name": "Computer Systems Design Services",
          "relevance": 70,
          "confidence": 80,
          "is_primary": false
        },
        {
          "code": "513210",
          "name": "Software Publishers",
          "relevance": 70,
          "confidence": 80,
          "is_primary": false
        },
        {
          "code": "51",
          "name": "Information",
          "relevance": 80,
          "confidence": 100,
          "is_primary": false
        }
      ],
      "sic_codes": [
        {
          "code": "7374",
          "name": "Computer Processing and Data Preparation and Processing Services",
          "relevance": 95,
          "confidence": 90,
          "is_primary": true
        },
        {
          "code": "7371",
          "name": "Computer Programming Services",
          "relevance": 90,
          "confidence": 90,
          "is_primary": false
        },
        {
          "code": "7379",
          "name": "Computer Related Services, Not Elsewhere Classified",
          "relevance": 85,
          "confidence": 80,
          "is_primary": false
        },
        {
          "code": "7372",
          "name": "Prepackaged Software",
          "relevance": 75,
          "confidence": 70,
          "is_primary": false
        }
      ],
      "business_tags": [
        "search engine",
        "online advertising",
        "cloud services",
        "artificial intelligence",
        "software development",
        "consumer electronics",
        "data analytics",
        "machine learning",
        "internet services"
      ],
      "business_model": [
        "Advertising",
        "B2C",
        "B2B",
        "Software as a Service (SaaS)",
        "E-commerce"
      ],
      "products_services": [
        "Search Engine",
        "Online Advertising",
        "Cloud Computing (Google Cloud Platform)",
        "Web Navigation (Chrome)",
        "Video Sharing (YouTube)",
        "Email (Gmail)",
        "Navigation and Mapping (Waze, Maps, Earth)",
        "Productivity (Workspace)",
        "Operating Systems (Android, ChromeOS)",
        "Cloud Storage (Drive)",
        "AI (Google Assistant, Gemini)",
        "Machine Learning APIs (TensorFlow)"
      ]
    },
    "operational_presence": [
      {
        "id": "op_30lFgfjlLov9pfV4roOST",
        "country_code": "US",
        "country": "United States of America",
        "count": 49,
        "is_home_jurisdiction": true
      }
    ]
  },
  "message": null,
  "metadata": {
    "last_updated": "2026-03-07T02:47:18.522Z",
    "processing_started_at": null,
    "estimated_completion": null
  }
}

Entity data compilation in progress (building)

{
  "entity_id": "siq_2ZYEAh7VdPkWsvlsqW9lG",
  "status": "building",
  "data": null,
  "message": "Initial data compilation in progress",
  "metadata": {
    "last_updated": null,
    "processing_started_at": "2024-10-01T19:02:20.343Z",
    "estimated_completion": "2024-10-01T19:05:20.343Z"
  }
}

Entity data available but refreshing

{
  "entity_id": "siq_2ZYEAh7VdPkWsvlsqW9lG",
  "status": "refreshing",
  "data": {
    "id": "siq_2ZYEAh7VdPkWsvlsqW9lG",
    "name": "Google",
    "type": "business",
    "subtype": "incorporated_entity",
    "status": "active",
    "headquarters": {
      "address": {
        "city": "Mountain View",
        "state": "California",
        "country": "United States",
        "state_code": "CA",
        "postal_code": "94043",
        "sub_premise": null,
        "country_code": "US",
        "street_number": null,
        "street_address": "1600 Amphitheatre Parkway",
        "formatted_address": null
      }
    },
    "primary_legal_entity": {
      "id": "le_2Zp3YaC1I4wgYZpQDPgx8",
      "name": "GOOGLE LLC",
      "jurisdiction": {
        "country_code": "US",
        "state_province": "Delaware"
      }
    },
    "attributes": {
      "description": "Google LLC is a multinational technology company specializing in internet-related services and products.",
      "website": "https://www.google.com",
      "domain": "google.com"
    },
    "classification": {
      "naics_codes_2022": [
        {
          "code": "51",
          "name": "Information",
          "relevance": 90,
          "confidence": 100,
          "is_primary": true
        }
      ],
      "business_tags": [
        "Search Engine",
        "Artificial Intelligence",
        "Online Advertising"
      ],
      "business_model": [
        "Online Advertising",
        "B2C Services",
        "B2B SaaS"
      ],
      "products_services": [
        "Search",
        "Online Advertising",
        "Google Workspace"
      ]
    },
    "operational_presence": [
      {
        "id": "op_30lFgfjlLov9pfV4roOST",
        "country_code": "US",
        "country": "United States of America",
        "count": 49,
        "is_home_jurisdiction": true
      }
    ]
  },
  "message": "Data refresh in progress - current data available",
  "metadata": {
    "last_updated": "2024-10-01T19:02:20.343Z",
    "processing_started_at": "2024-10-01T20:15:30.123Z",
    "estimated_completion": "2024-10-01T20:18:45.567Z"
  }
}