# Score Companies

Get your HG AI Scores directly from the API — no need to export from the Platform or sync through Salesforce. Score companies against your account's scoring models, filter and rank companies by tier, and pull scores into your own workflow or CRM in real time.

## Use Cases

- **Programmatic target account lists** — search and rank companies by score instead of exporting and sorting manually in the Platform UI
- **Real-time scoring in your workflow** — score a company the moment a record is created in your CRM or internal system
- **Prioritize outbound** — filter your existing pipeline by tier to focus on the highest-fit accounts first


## Prerequisites

- Your org has access to HG Platform to manage your scoring models
- The `scoring` entitlement on your account, on top of your regular API access


If you get a 422 saying scoring isn't available, or a 401 on these endpoints specifically, contact your account manager.

## Common Workflow

Search for companies scoring in your top tiers, then pull the full score breakdown and enrichment data for that list:

```json
// 1. Search for A/B tier companies with 1,000+ employees
{
  "fields": ["id", "name", "domain"],
  "filters": {
    "firmographics": {"employees": {"min": 1000}},
    "scoring": {"model_id": "7e347cba", "tier": ["A", "B"]}
  },
  "sorts": [{"field": "total_score", "direction": "DESC"}],
  "limit": 25
}
```

```json
// 2. Pull full scores for the returned company IDs
{
  "companies": {"ids": ["3AB6196C456CE3313A04A57BA6FA7BE3", "..."]},
  "model_ids": ["7e347cba"]
}
```

```json
// 3. Enrich the same companies with firmographics, technographics, and spend
{
  "companies": {"ids": ["3AB6196C456CE3313A04A57BA6FA7BE3", "..."]},
  "fields": ["firmographics", "technographics", "spend"]
}
```

See [Enrich Companies](/v2/guides/enrichment) for the full list of available field groups.

## List Scoring Models

Get every scoring model currently live in your account.

```
GET /data-api/v2/scoring/models
```

No parameters — returns all live models for your account. Draft models aren't included.

### Response

```json
{
  "models": [
    {
      "model_id": "7e347cba",
      "model_name": "Enterprise ICP",
      "model_version_id": "b1c2d3e4",
      "version": 3
    }
  ],
  "count": 1
}
```

| Field | Description |
|  --- | --- |
| `model_id` | Stable identifier for the model — use this in `companies/score` and search filters. Persists across republishes. |
| `model_name` | Display name of the model |
| `model_version_id` | The currently published version of this model |
| `version` | Version number |


## Search Companies by Tier or Score

Filter and sort [Company Search](/v2/guides/find-companies#company-search) results by tier or score. This is the same "score-based segmentation" you'd do manually in the Platform's Companies view, now available as a filter.

```json
{
  "fields": ["id", "name", "domain"],
  "filters": {
    "scoring": {
      "model_id": "7e347cba",
      "tier": ["A", "B"],
      "total_score": {"min": 70, "max": 100}
    }
  },
  "sorts": [{"field": "total_score", "direction": "DESC"}]
}
```

| Filter field | Description |
|  --- | --- |
| `model_id` | Required. The model to filter/sort against. |
| `tier` | Array of tiers to match, any of `A`, `B`, `C`, `D`, `F`, `DQ` |
| `total_score`, `fit_score`, `need_score`, `intent_score` | Each accepts `{min, max}`, inclusive, 0-100 |


To sort by score, add `total_score`, `fit_score`, `need_score`, or `intent_score` to `sorts` — this requires `filters.scoring.model_id` to be set, and the score sort must be the first entry in `sorts`.

**Search doesn't return the score values themselves** — only companies matching the filter, with the standard `fields` you requested. To get the actual score numbers for those companies, pass their IDs to `companies/score`.

## Score Companies

Score up to 25 companies against one or more models in a single call.

```
POST /data-api/v2/companies/score
```

### Request

```json
{
  "companies": {
    "ids": ["3AB6196C456CE3313A04A57BA6FA7BE3"]
  },
  "model_ids": ["7e347cba"]
}
```

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `companies.ids` | array | Yes* | HG company IDs (max 25) |
| `companies.domains` | array | Yes* | Company domains (max 25) |
| `model_ids` | array | No | Model IDs to score against (max 6). Omit to score against all live models — errors if your account has more than 6 live models and none are specified. |


*Either `ids` or `domains` is required, but not both.

### Response

```json
{
  "scores": [
    {
      "hg_id": "3AB6196C456CE3313A04A57BA6FA7BE3",
      "company_name": "Cisco Systems",
      "domain": null,
      "model_id": "7e347cba",
      "model_name": "Enterprise ICP",
      "model_version_id": "b1c2d3e4",
      "tier": "A",
      "total_score": 87,
      "fit_score": 90,
      "need_score": 72,
      "intent_score": 60,
      "is_disqualified": false
    }
  ],
  "count": 1
}
```

| Field | Description |
|  --- | --- |
| `tier` | `A`, `B`, `C`, `D`, `F`, or `DQ` |
| `total_score` | Composite score (0-100) |
| `fit_score` | Fit dimension score (0-100) |
| `need_score` | Need dimension score (0-100) |
| `intent_score` | Intent dimension score (0-100) |
| `is_disqualified` | `true` when `tier` is `DQ` |


You get one row per company per model. If a company isn't scored under a given model, that row's score fields come back `null` instead of erroring — the request as a whole still succeeds.

## Credits

None of the scoring endpoints consume credits.