Name Resolution¶

Resolve an entity or organization name to ranked candidates using Tango's Bayesian resolver. This endpoint is useful for data enrichment workflows, entity linking, and research.

Endpoint: POST /api/resolve/

Overview¶

Given a name and target type, the endpoint returns a ranked list of entity or organization candidates. Results are ranked by quality and filtered based on your access tier:

Free tier: Up to 3 candidates (identifier and display name only)
Pro tier and above: Up to 5 candidates (includes match quality tier)

The resolver learns from location context (state, city), industry signals (NAICS, PSC codes), and any additional information you provide in the context field. More context typically leads to better matches.

Authentication required: API key or OAuth2 token (all callers must be authenticated; unauthenticated requests receive HTTP 401).

Rate limiting: Standard API rate limits apply (no additional premium throttling for this endpoint).

Request¶

POST /api/resolve/
Content-Type: application/json
X-API-KEY: <key>

{
  "name": "Lockheed Martin",
  "target_type": "entity",
  "state": "MD",
  "city": "Bethesda",
  "context": "fighter aircraft maintenance, NAICS 336411"
}

Request body fields¶

Field	Type	Required	Description
`name`	string	Yes	Name to resolve (must be non-blank).
`target_type`	string	Yes	Type of target: `"entity"` or `"organization"`.
`state`	string	No	2-letter state code (e.g., `"MD"`, `"CA"`).
`city`	string	No	City name.
`context`	string	No	Freeform text with additional context for better matching. Can include industry references, contract descriptions, agency names, solicitation details, or any other relevant information. More context generally produces more accurate matches. The API does not document which specific signals are extracted from this field.

Constraints:

name cannot be empty or whitespace-only (400 error)
target_type must be exactly "entity" or "organization" (400 error)
state should be a valid 2-letter code, but is not validated
city and context are free-form text with no constraints

Response¶

Success (HTTP 200)¶

{
  "candidates": [
    {
      "identifier": "ABC123DEF456",
      "display_name": "Lockheed Martin Corporation"
    },
    {
      "identifier": "GHI789JKL012",
      "display_name": "Lockheed Martin Aeronautics"
    },
    {
      "identifier": "MNO345PQR678",
      "display_name": "LMC Holdings LLC"
    }
  ],
  "count": 3
}

Free tier: Returns up to 3 candidates with identifier and display_name fields only.

Pro tier and above: Returns up to 5 candidates with an additional match_tier field:

{
  "candidates": [
    {
      "identifier": "ABC123DEF456",
      "display_name": "Lockheed Martin Corporation",
      "match_tier": "high"
    },
    {
      "identifier": "GHI789JKL012",
      "display_name": "Lockheed Martin Aeronautics",
      "match_tier": "medium"
    },
    {
      "identifier": "MNO345PQR678",
      "display_name": "LMC Holdings LLC",
      "match_tier": "low"
    },
    {
      "identifier": "STU901VWX234",
      "display_name": "Lockheed Martin Space",
      "match_tier": "low"
    },
    {
      "identifier": "YZA567BCD890",
      "display_name": "Lockheed Martin Rotary",
      "match_tier": "low"
    }
  ],
  "count": 5
}

The match_tier field indicates the quality of the match:

"high" — Confident match, likely the intended target
"medium" — Reasonable match, but consider alternatives
"low" — Possible match, but verify before using

When fewer candidates are returned than the tier limit, count reflects the actual number returned.

No matches (HTTP 200)¶

{
  "candidates": [],
  "count": 0
}

Validation errors (HTTP 400)¶

Missing or blank name:

{
  "error": "name is required and must not be blank",
  "code": "validation_error"
}

Invalid target_type:

{
  "error": "target_type must be 'entity' or 'organization'",
  "code": "validation_error"
}

Authentication error (HTTP 401)¶

Standard DRF 401 response for unauthenticated requests.

Server error (HTTP 500)¶

If an unexpected error occurs during resolution (rare), the response is:

{
  "error": "An unexpected error occurred during resolution",
  "code": "server_error"
}

Examples¶

Example 1: Entity resolution with full context¶

curl -X POST https://tango.makegov.com/api/resolve/ \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Boeing",
    "target_type": "entity",
    "state": "WA",
    "city": "Seattle",
    "context": "aerospace defense contractor, NAICS 336414, Department of Defense supplier"
  }'

Response (Pro tier):

{
  "candidates": [
    {
      "identifier": "ABC123DEF456",
      "display_name": "The Boeing Company",
      "match_tier": "high"
    },
    {
      "identifier": "GHI789JKL012",
      "display_name": "Boeing Defense, Space and Security",
      "match_tier": "high"
    },
    {
      "identifier": "MNO345PQR678",
      "display_name": "Boeing Commercial Airplanes",
      "match_tier": "medium"
    }
  ],
  "count": 3
}

Example 2: Minimal request (free tier)¶

curl -X POST https://tango.makegov.com/api/resolve/ \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "target_type": "entity"
  }'

Response (Free tier):

{
  "candidates": [
    {
      "identifier": "ABC123DEF456",
      "display_name": "Acme Corporation"
    }
  ],
  "count": 1
}

Example 3: Organization resolution¶

curl -X POST https://tango.makegov.com/api/resolve/ \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Naval Sea Systems Command",
    "target_type": "organization",
    "context": "Department of the Navy"
  }'

Response:

{
  "candidates": [
    {
      "identifier": "N6233A00",
      "display_name": "Naval Sea Systems Command",
      "match_tier": "high"
    }
  ],
  "count": 1
}

Best practices¶

Provide context: The context field significantly improves match quality. Include any relevant details: industry (NAICS/PSC codes), agency, contract purpose, solicitation details, or other business context.
Use the right target_type: Use "entity" for vendors/contractors and "organization" for government agencies or organizational units.
Location helps: When available, provide state and/or city to disambiguate between entities with similar names in different regions.
Check match_tier (Pro tier): Use the match_tier to gauge confidence. High matches are generally safe to use; medium and low matches should be verified.
Handle no matches: Plan for empty result sets. When no candidates are returned, consider trying alternative names or reducing specificity in the context field.

SDK support¶

The official SDKs do not yet expose a first-class method for the resolve endpoint. Use the HTTP client:

Python (tango-python)Node (tango-node)

import os
from tango import TangoClient

client = TangoClient(api_key=os.environ["TANGO_API_KEY"])
response = client._post(
    "/api/resolve/",
    json={
        "name": "Lockheed Martin",
        "target_type": "entity",
        "state": "MD",
        "context": "aerospace defense",
    }
)
print("Found", response["count"], "candidates")
for candidate in response["candidates"]:
    print(f"  - {candidate['display_name']} ({candidate['identifier']})")

import { TangoClient } from "tango";

const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY });
const response = await client._post("/api/resolve/", {
  name: "Lockheed Martin",
  target_type: "entity",
  state: "MD",
  context: "aerospace defense",
});
console.log(`Found ${response.count} candidates`);
response.candidates.forEach((candidate) => {
  console.log(`  - ${candidate.display_name} (${candidate.identifier})`);
});

Tier-based access¶

All requests must be authenticated. Free tier and pro+ tier users receive different response shapes:

Aspect	Free	Pro+
Max candidates	3	5
Fields	identifier, display_name	identifier, display_name, match_tier
Rate limit	Standard	Standard

See Plans & Data Access for tier definitions.

Report an issue with this page