Text search

Resolve a short piece of text to the Specter entities it refers to. Pass a passage to pull out the entities mentioned, or a natural-language query (e.g. “competitors of rippling.com” or “fintech investors”) to get the entities that match. Each result includes the entity’s Specter ID, type, and how central it is to the text.

Costs 1 credit per request.

Behaviour

• Accepts up to 1,000 characters.
• Each match carries a context: primary (a main subject or direct match), active (a meaningful supporting role, e.g. an investor in a round), or passive (mentioned in passing).
• People aren’t supported yet.
• No matches returns an empty list.

POST /entities/text-search

Text search

cURL

curl --request POST \
  --url https://app.tryspecter.com/api/v1/entities/text-search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "text": "Competitors of rippling.com worldwide"
}
'

import requests

url = "https://app.tryspecter.com/api/v1/entities/text-search"

payload = { "text": "Competitors of rippling.com worldwide" }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({text: 'Competitors of rippling.com worldwide'})
};

fetch('https://app.tryspecter.com/api/v1/entities/text-search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.tryspecter.com/api/v1/entities/text-search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'text' => 'Competitors of rippling.com worldwide'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.tryspecter.com/api/v1/entities/text-search"

	payload := strings.NewReader("{\n  \"text\": \"Competitors of rippling.com worldwide\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.tryspecter.com/api/v1/entities/text-search")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"Competitors of rippling.com worldwide\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.tryspecter.com/api/v1/entities/text-search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"Competitors of rippling.com worldwide\"\n}"

response = http.request(request)
puts response.read_body

200

Example

[
  {
    "source_name": "Stripe",
    "context": "primary",
    "entity_id": "5e3bc2b700c8f4c966ad2bbd",
    "entity_type": "company"
  }
]

Authorizations

X-API-Key · string · header · required

Body

application/json

The text to resolve.

text · string · required

The text to resolve (max 1,000 characters).

Maximum string length: 1000

Example:

"Competitors of rippling.com worldwide"

Response

200

application/json

The entities resolved from the text. Returns an empty list when there are no matches.

source_name · string

The matched entity's name.

Example:

"Stripe"

context · enum<string>

How central the entity is to the text: primary (a main subject or direct match), active (a meaningful supporting role, e.g. an investor in a round), or passive (mentioned incidentally).

Available options: primary, active, passive

Example:

"primary"

entity_id · string

The entity's Specter ID — a company ID or an investor ID.

Example:

"5e3bc2b700c8f4c966ad2bbd"

entity_type · enum<string>

Entity category. Companies are returned as company, investors as investors.

Available options: company, investors

Example:

"company"