Documentation / API / prospects_similar_to_id

prospects_similar_to_id

POSThttps://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 shows the searches that are left today.

Authentication

Send an API token in the Authorization: Bearer header. The API page shows how to get a token.

Parameters

The tool takes 2 parameters.

campaignint, 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_idstring 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

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.

{
  "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 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.

{
  "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.