<!-- The markdown copy of https://oppalerts.com/docs/api/prospects_similar_to_id . All pages: https://oppalerts.com/docs/llms.txt -->

[Documentation](https://oppalerts.com/docs/) / [API](https://oppalerts.com/docs/api/) / prospects_similar_to_id

# prospects_similar_to_id

`POST https://api.oppalerts.com/v1/prospects/similar_to_id`

Lists the Prospect Index pages most semantically similar to a page identified by its document_id.

## What it does

The tool returns the 100 pages of the Prospect Index that are nearest in semantic similarity to one page, nearest first. You name the page by its `document_id`. Take it from the `id` of a search result.

The `campaign` is optional. With a campaign, a result whose site is an organization of the campaign has an `org` key that tells what the site is to the campaign.

All `news_` and `prospects_` tools of one account share one daily count of index searches. Only one index search runs at a time. [account_calls_left](https://oppalerts.com/docs/api/account_calls_left) shows the searches that are left today.

## Authentication

Send an API token in the `Authorization: Bearer` header. [The API page](https://oppalerts.com/docs/api/) shows how to get a token.

## Parameters

The tool takes 2 parameters.

**`campaign`int, optional, 1 to 4294967295**

Optional. The campaign id, a whole number from 1 to 4294967295, from `campaigns_list`. When you send it, the campaign must be in this account, and a result whose site is an organization of the campaign has an org key that tells what the site is to the campaign. When you do not send it, no result has an org key.

**`document_id`string of digits, required**

Required. The document id, from a search result: a decimal string of 1 to 20 digits. It is a string because the value exceeds the largest whole number that JavaScript can represent exactly.

### Rules

- Copies of the same text on other sites are not merged: each copy is a separate result.
- found is true when the index has the document and its vector.
- When found is false, document holds empty values, and results is an empty list.

## Example

### Request

```bash
curl -X POST https://api.oppalerts.com/v1/prospects/similar_to_id \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"campaign": 3, "document_id": "2305843009217850096"}'
```

### Response

The full sample answer.

```json
{
  "found": true,
  "document": {
    "id": "2305843009217850096",
    "url": "https://cityguide-example.org/advertise/media-kit",
    "host": "cityguide-example.org",
    "document_type": "page",
    "published_at": "2026-05-10T00:00:00Z",
    "indexed_at": "2026-08-17T21:00:00Z",
    "pr_host": 39,
    "prot_host": 678,
    "pr_domain": 61,
    "prot_domain": 861,
    "similarity_score": 46.8,
    "relevance_weight": 1247.0,
    "org": {
      "relationship": "org_publisher"
    },
    "page": {
      "title": "Advertise with City Guide: media kit",
      "snippet": "Reach 400,000 monthly readers planning weekend trips. Sponsorship and hotel placements available.",
      "link_counts": {
        "article": {
          "follow": 12,
          "nofollow": 3,
          "sponsored": 2,
          "ugc": 0
        },
        "nav": {
          "follow": 34,
          "nofollow": 0,
          "sponsored": 0,
          "ugc": 0
        },
        "comments": {
          "follow": 0,
          "nofollow": 0,
          "sponsored": 0,
          "ugc": 0
        }
      },
      "meta": {
        "favicon": "https://cityguide-example.org/favicon-32.png",
        "feeds": [
          "https://cityguide-example.org/feed"
        ],
        "contact": [
          "https://cityguide-example.org/contact"
        ]
      },
      "sections": {
        "article": {
          "links": [
            {
              "url": "https://grand-resorts.example/awards",
              "text": "Grand Resorts",
              "title": "",
              "rel": [
                "nofollow"
              ],
              "org": {
                "relationship": "org_competitor"
              }
            }
          ],
          "emails": [
            "press@cityguide-example.org"
          ],
          "phones": [
            "+1 555 0100"
          ],
          "service_accounts": [
            {
              "service": "linkedin",
              "username": "cityguide",
              "label": "City Guide",
              "url": "https://linkedin.com/company/cityguide"
            }
          ]
        },
        "nav": {
          "links": [
            {
              "url": "https://partner-example.com/",
              "text": "Our partner",
              "title": "Partner",
              "rel": [
                "sponsored"
              ],
              "org": {
                "relationship": "org_partner"
              }
            }
          ],
          "emails": [
            "hello@cityguide-example.org"
          ],
          "phones": [
            "+1 555 0101"
          ],
          "service_accounts": [
            {
              "service": "twitter",
              "username": "cityguide",
              "label": "",
              "url": "https://x.com/cityguide"
            }
          ]
        },
        "comments": {
          "links": [
            {
              "url": "https://reader-blog-example.net/trip-notes",
              "text": "my trip notes",
              "title": "",
              "rel": [
                "ugc"
              ],
              "org": {
                "relationship": "org_partner"
              }
            }
          ],
          "emails": [
            "comments@cityguide-example.org"
          ],
          "phones": [
            "+1 555 0102"
          ],
          "service_accounts": [
            {
              "service": "reddit",
              "username": "cityguide",
              "label": "",
              "url": "https://reddit.com/u/cityguide"
            }
          ]
        }
      }
    }
  },
  "results": [
    {
      "id": "2305843009217850096",
      "url": "https://cityguide-example.org/advertise/media-kit",
      "host": "cityguide-example.org",
      "document_type": "page",
      "published_at": "2026-05-10T00:00:00Z",
      "indexed_at": "2026-08-17T21:00:00Z",
      "pr_host": 39,
      "prot_host": 678,
      "pr_domain": 61,
      "prot_domain": 861,
      "similarity_score": 46.8,
      "relevance_weight": 1247.0,
      "org": {
        "relationship": "org_publisher"
      },
      "page": {
        "title": "Advertise with City Guide: media kit",
        "snippet": "Reach 400,000 monthly readers planning weekend trips. Sponsorship and hotel placements available.",
        "link_counts": {
          "article": {
            "follow": 12,
            "nofollow": 3,
            "sponsored": 2,
            "ugc": 0
          },
          "nav": {
            "follow": 34,
            "nofollow": 0,
            "sponsored": 0,
            "ugc": 0
          },
          "comments": {
            "follow": 0,
            "nofollow": 0,
            "sponsored": 0,
            "ugc": 0
          }
        },
        "meta": {
          "favicon": "https://cityguide-example.org/favicon-32.png",
          "feeds": [
            "https://cityguide-example.org/feed"
          ],
          "contact": [
            "https://cityguide-example.org/contact"
          ]
        },
        "sections": {
          "article": {
            "links": [
              {
                "url": "https://grand-resorts.example/awards",
                "text": "Grand Resorts",
                "title": "",
                "rel": [
                  "nofollow"
                ],
                "org": {
                  "relationship": "org_competitor"
                }
              }
            ],
            "emails": [
              "press@cityguide-example.org"
            ],
            "phones": [
              "+1 555 0100"
            ],
            "service_accounts": [
              {
                "service": "linkedin",
                "username": "cityguide",
                "label": "City Guide",
                "url": "https://linkedin.com/company/cityguide"
              }
            ]
          },
          "nav": {
            "links": [
              {
                "url": "https://partner-example.com/",
                "text": "Our partner",
                "title": "Partner",
                "rel": [
                  "sponsored"
                ],
                "org": {
                  "relationship": "org_partner"
                }
              }
            ],
            "emails": [
              "hello@cityguide-example.org"
            ],
            "phones": [
              "+1 555 0101"
            ],
            "service_accounts": [
              {
                "service": "twitter",
                "username": "cityguide",
                "label": "",
                "url": "https://x.com/cityguide"
              }
            ]
          },
          "comments": {
            "links": [
              {
                "url": "https://reader-blog-example.net/trip-notes",
                "text": "my trip notes",
                "title": "",
                "rel": [
                  "ugc"
                ],
                "org": {
                  "relationship": "org_partner"
                }
              }
            ],
            "emails": [
              "comments@cityguide-example.org"
            ],
            "phones": [
              "+1 555 0102"
            ],
            "service_accounts": [
              {
                "service": "reddit",
                "username": "cityguide",
                "label": "",
                "url": "https://reddit.com/u/cityguide"
              }
            ]
          }
        }
      }
    }
  ]
}
```

The answer has these top-level fields: `found` (`true` when the index has the document and its vector; when it is `false`, `document` holds empty values, and `results` is an empty list), `document` (the page you named), and `results` (the 100 nearest pages, nearest first). Each result has the fields of a search result. `document` has the same fields. Copies of the same text on other sites are not merged: each copy is a separate result.

## Errors

- `bad_param`: HTTP 400. A field is unknown, empty, of the wrong type, or out of its range, or the call breaks a rule of this page. The message names the field.
- `no_campaign`: HTTP 404. The campaign is not a campaign of your account.
- `one_at_a_time`: HTTP 429. Another index search of the account is running. Wait a few seconds and send the call again. A refused call uses no daily call.
- `daily_limit`: HTTP 429. The account has used all of its index searches for today.
- `backend_error`: HTTP 502. The search server did not answer, or its answer could not be read. Send the call again later. The call counts as 1 search.
- `search_stopped`: HTTP 422. The search took more than 10 seconds and the server stopped it. The message says how to make the search more specific. A stopped search counts as 1 search.

The API answers with the HTTP status and a JSON body: `error` holds the error code, and `error_description` holds the message.

### Limits

- Each call draws from the one daily count of index searches that every `news_` and `prospects_` tool of the account shares. [account_calls_left](https://oppalerts.com/docs/api/account_calls_left) shows the counts.
- Only one index search runs at a time per account.
- A call that is refused uses no daily search. A search that is stopped at 10 seconds counts as 1 search.

### Strict Rules

- An unknown field is refused, also inside an object. A field name of an older version of this tool is an unknown field.
- A bad value is refused: a value of the wrong type, a value out of its range, a value that is not in its list, and an empty text, list, or object. To send no value, leave the field out.
- The error names the field.
- No field has a default value. A field that you do not send applies no condition.
- An error about the form of a call, such as a refused field, names the field. Its message ends with one sentence: "Read the documentation at https://oppalerts.com/docs for the correct format." Every other error has only its own sentence.

An example: the answer (HTTP 400) to a call that sends the field `limit`, which this tool does not have.

```json
{
  "error": "bad_param",
  "error_description": "limit is not a field of this tool. Read the documentation at https://oppalerts.com/docs for the correct format."
}
```

## Same tool in MCP

The MCP tool is `prospects_similar_to_id`. See [prospects_similar_to_id in MCP](https://oppalerts.com/docs/mcp/prospects_similar_to_id).

## Related pages

- [prospects_similar_to_id in MCP](https://oppalerts.com/docs/mcp/prospects_similar_to_id)
- [Similar Prospects in the web app](https://oppalerts.com/docs/app/opportunities/similar_prospects)
- [news_similar_to_id: the same call on the News Index](https://oppalerts.com/docs/api/news_similar_to_id)
- [prospects_search: find a page id](https://oppalerts.com/docs/api/prospects_search)
