Skip to main content

Quickstart

Verify a vendor in under 5 minutes.

Prerequisites​

  • An API key from app.vendorval.com
  • Any HTTP client (curl, fetch, your language's HTTP library)

Step 1 — Resolve the entity​

Send the identifiers you have. You can mix and match — the more you provide, the higher the confidence score.

curl https://api.vendorval.com/v1/entities/lookup \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifiers": [
      { "type": "uei", "value": "ABCD12345678" }
    ],
    "legal_name": "Acme Federal Services LLC"
  }'

Response:

{
  "id": "ent_01abc...",
  "legal_name": "Acme Federal Services LLC",
  "identifiers": {
    "uei": "ABCD12345678",
    "tin": "****6789"
  },
  "sam_gov": {
    "registration_status": "active",
    "cage": "7XYZ2",
    "expiration_date": "2027-01-15"
  },
  "confidence": 0.97,
  "sources": [{ "name": "sam_gov", "retrieved_at": "2026-04-19T00:00:00Z" }]
}

Step 2 — Run verification​

Use the entity ID from step 1 to run checks. Use cached mode for fast responses, realtime when you need guaranteed-current data.

curl https://api.vendorval.com/v1/verify \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "ent_01abc...",
    "checks": ["sam_registration", "tin_match"],
    "mode": "cached"
  }'

Response:

{
  "id": "ver_01xyz...",
  "entity_id": "ent_01abc...",
  "overall_result": "pass",
  "results": [
    {
      "check_type": "sam_registration",
      "status": "pass",
      "confidence": 0.99,
      "origin": "sam_gov",
      "data_freshness_seconds": 43200,
      "evidence_uri": "s3://vendorval-evidence/ver_01xyz/sam_registration.json"
    },
    {
      "check_type": "tin_match",
      "status": "pass",
      "confidence": 0.95,
      "origin": "irs_tin_matching",
      "data_freshness_seconds": 0,
      "evidence_uri": "s3://vendorval-evidence/ver_01xyz/tin_match.json"
    }
  ]
}

One-call shortcut​

The /v1/verify endpoint also accepts identifiers directly. If the entity doesn't exist yet, it will be created automatically:

curl https://api.vendorval.com/v1/verify \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifiers": [
      { "type": "uei", "value": "ABCD12345678" }
    ],
    "legal_name": "Acme Federal Services LLC",
    "checks": ["sam_registration"],
    "mode": "cached"
  }'

JavaScript example​

const BASE = 'https://api.vendorval.com'
const KEY  = 'YOUR_API_KEY'

// Step 1: resolve
const entity = await fetch(`${BASE}/v1/entities/lookup`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    identifiers: [{ type: 'uei', value: 'ABCD12345678' }],
    legal_name: 'Acme Federal Services LLC',
  }),
}).then(r => r.json())

// Step 2: verify
const result = await fetch(`${BASE}/v1/verify`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    entity_id: entity.id,
    checks: ['sam_registration', 'tin_match'],
    mode: 'cached',
  }),
}).then(r => r.json())

console.log(result.overall_result) // "pass"

Next steps​