POST /v1/entities/lookup

Resolve an entity from any combination of identifiers. Read-only — never creates entities.

Request

POST https://api.vendorval.com/v1/entities/lookup
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body

{
  identifiers?: Array<{
    type: "uei" | "tin" | "duns" | "cage"
    value: string
  }>
  legal_name?: string
  address?: string
  mode?: "exact" | "fuzzy"   // default: "exact"
}

At least one of identifiers, legal_name, or address is required.

Example

{
  "identifiers": [
    { "type": "uei", "value": "ABCD12345678" },
    { "type": "tin", "value": "12-3456789" }
  ],
  "legal_name": "Acme Federal Services LLC"
}

Response

200 — Match found

{
  id: string
  legal_name: string
  identifiers: Record<string, string>   // TIN masked as ****{last4}
  sam_gov: {
    registration_status: "active" | "inactive" | "expired" | "debarred"
    cage?: string
    expiration_date?: string
    entity_type?: string
  }
  addresses: Array<{
    type: "physical" | "mailing"
    line1: string
    line2?: string
    city: string
    state: string
    zip: string
    country: string
  }>
  confidence: number              // 0–1
  sources: Array<{
    name: string
    retrieved_at: string          // ISO 8601
    version?: string
  }>
}

404 — No match

{
  "error": "entity_not_found",
  "message": "No entity matched the provided identifiers."
}

Fuzzy mode — Multiple candidates

{
  candidates: Array<{
    id: string
    legal_name: string
    confidence: number
  }>
}

Error codes

Status	Error	Meaning
400	invalid_request	Missing required fields or invalid identifier type
401	unauthorized	Invalid or missing API key
404	entity_not_found	No match found
429	rate_limited	Too many requests
500	internal_error	Server error