{
  "info": {
    "name": "Elvesora Company Domain Lookup API",
    "description": "Ready-to-run requests for bearer-token verification and company-name-to-domain lookup. Saved examples cover found, completed no-match, both validation envelopes, local plan exhaustion, retryable provider throttling, malformed-provider 502, and transient 503 responses. Confidence is an ordinal routing score, not a calibrated probability.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://prospecting.elvesora.com/api"
    },
    {
      "key": "api_key",
      "value": "YOUR_API_KEY"
    },
    {
      "key": "company_name",
      "value": "Acme Corporation"
    },
    {
      "key": "additional_context",
      "value": "United States, industrial manufacturing"
    }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{api_key}}",
        "type": "string"
      }
    ]
  },
  "item": [
    {
      "name": "Verify Domain Lookup token",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          },
          {
            "key": "X-Request-Id",
            "value": "{{$guid}}"
          }
        ],
        "url": {
          "raw": "{{base_url}}/prospecting/ping",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "prospecting",
            "ping"
          ]
        },
        "description": "Checks whether the team bearer token can reach the protected Domain Lookup API without consuming a lookup credit. Normal token-use auditing still applies."
      },
      "response": [
        {
          "name": "Token active",
          "status": "OK",
          "code": 200,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Request-Id",
              "value": "7d9df214-0f4d-4c0f-a2ff-e04fda4d09cb"
            }
          ],
          "body": "{\n  \"status\": \"ok\"\n}"
        },
        {
          "name": "Unauthorized",
          "status": "Unauthorized",
          "code": 401,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Request-Id",
              "value": "7d9df214-0f4d-4c0f-a2ff-e04fda4d09cb"
            }
          ],
          "body": "{\n  \"message\": \"Unauthorized\"\n}"
        }
      ]
    },
    {
      "name": "Lookup company domain",
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "pm.test('Response includes X-Request-Id', function () {",
              "  pm.expect(pm.response.headers.get('X-Request-Id')).to.be.a('string').and.not.empty;",
              "});",
              "",
              "if (pm.response.code === 200) {",
              "  const body = pm.response.json();",
              "  pm.test('Completed lookup routing fields are internally consistent', function () {",
              "    pm.expect(body.success).to.eql(true);",
              "    pm.expect(body.confidence).to.be.within(0, 100);",
              "    if (body.found) {",
              "      pm.expect(body.domain).to.be.a('string').and.not.empty;",
              "      pm.expect(body.confidence).to.be.above(0);",
              "    } else {",
              "      pm.expect(body.domain).to.eql(null);",
              "      pm.expect(body.confidence).to.eql(0);",
              "      pm.expect(body.confidence_band).to.eql('no_match');",
              "      pm.expect(body.review_recommended).to.eql(true);",
              "    }",
              "    if (body.confidence >= 85) {",
              "      pm.expect(body.confidence_band).to.eql('high');",
              "      pm.expect(body.review_recommended).to.eql(false);",
              "    } else if (body.confidence >= 60) {",
              "      pm.expect(body.confidence_band).to.eql('review');",
              "      pm.expect(body.review_recommended).to.eql(true);",
              "    } else if (body.confidence >= 1) {",
              "      pm.expect(body.confidence_band).to.eql('low');",
              "      pm.expect(body.review_recommended).to.eql(true);",
              "    }",
              "  });",
              "}"
            ]
          }
        }
      ],
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "X-Request-Id",
            "value": "{{$guid}}"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"company_name\": \"{{company_name}}\",\n  \"additional_context\": \"{{additional_context}}\"\n}"
        },
        "url": {
          "raw": "{{base_url}}/prospecting/company",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "prospecting",
            "company"
          ]
        },
        "description": "Resolves one company name. A request that passes authentication and the subscription-period credit check reserves one credit before validation and provider execution. Completed found, no-match, cached, validation, and committed provider-error attempts retain that credit; a request blocked by the local credit check or throttled by the provider consumes none. Provider throttling is retryable and returns a bounded retry_after delay in the JSON body."
      },
      "response": [
        {
          "name": "Found match",
          "status": "OK",
          "code": 200,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Request-Id",
              "value": "7d9df214-0f4d-4c0f-a2ff-e04fda4d09cb"
            }
          ],
          "body": "{\n  \"success\": true,\n  \"message\": \"Company lookup completed successfully\",\n  \"company_name\": \"Acme Corporation\",\n  \"normalized_company_name\": \"acme corporation\",\n  \"domain\": \"acme.com\",\n  \"linkedin_url\": \"https://www.linkedin.com/company/acme\",\n  \"industry\": \"Industrial Machinery\",\n  \"sub_industry\": \"Industrial Equipment\",\n  \"sector\": \"Industrials\",\n  \"confidence\": 92,\n  \"confidence_band\": \"high\",\n  \"review_recommended\": false,\n  \"is_live\": true,\n  \"reasons\": [\"Company name matches website brand.\"],\n  \"lower_reasons\": [],\n  \"cached\": false,\n  \"found\": true,\n  \"remaining\": 95,\n  \"limit\": 100\n}"
        },
        {
          "name": "Completed no match",
          "status": "OK",
          "code": 200,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Request-Id",
              "value": "7d9df214-0f4d-4c0f-a2ff-e04fda4d09cb"
            }
          ],
          "body": "{\n  \"success\": true,\n  \"message\": \"No domain found for this company.\",\n  \"company_name\": \"Unknown Company\",\n  \"normalized_company_name\": \"unknown company\",\n  \"domain\": null,\n  \"linkedin_url\": null,\n  \"industry\": null,\n  \"sub_industry\": null,\n  \"sector\": null,\n  \"confidence\": 0,\n  \"confidence_band\": \"no_match\",\n  \"review_recommended\": true,\n  \"is_live\": null,\n  \"reasons\": [\"No reliable public domain matched this company.\"],\n  \"lower_reasons\": [],\n  \"cached\": false,\n  \"found\": false,\n  \"remaining\": 95,\n  \"limit\": 100\n}"
        },
        {
          "name": "Unauthorized",
          "status": "Unauthorized",
          "code": 401,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Request-Id",
              "value": "7d9df214-0f4d-4c0f-a2ff-e04fda4d09cb"
            }
          ],
          "body": "{\n  \"message\": \"Unauthorized\"\n}"
        },
        {
          "name": "Local validation error",
          "status": "Unprocessable Entity",
          "code": 422,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Request-Id",
              "value": "7d9df214-0f4d-4c0f-a2ff-e04fda4d09cb"
            }
          ],
          "body": "{\n  \"message\": \"The company name field is required.\",\n  \"errors\": {\n    \"company_name\": [\n      \"The company name field is required.\"\n    ]\n  }\n}"
        },
        {
          "name": "Dependency validation error",
          "status": "Unprocessable Entity",
          "code": 422,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Request-Id",
              "value": "7d9df214-0f4d-4c0f-a2ff-e04fda4d09cb"
            }
          ],
          "body": "{\n  \"success\": false,\n  \"message\": \"Unable to process this request\",\n  \"errors\": {\n    \"company_name\": [\"The company name field is invalid.\"]\n  },\n  \"response_code\": 422,\n  \"error_type\": \"validation_error\",\n  \"retryable\": false\n}"
        },
        {
          "name": "Credit limit exceeded",
          "status": "Too Many Requests",
          "code": 429,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Request-Id",
              "value": "7d9df214-0f4d-4c0f-a2ff-e04fda4d09cb"
            }
          ],
          "body": "{\n  \"success\": false,\n  \"message\": \"Request limit exceeded. Please upgrade your plan.\",\n  \"limit\": 100,\n  \"remaining\": 0,\n  \"response_code\": 429,\n  \"error_type\": \"usage_limit\",\n  \"retryable\": false\n}"
        },
        {
          "name": "Provider rate limited",
          "status": "Too Many Requests",
          "code": 429,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Request-Id",
              "value": "7d9df214-0f4d-4c0f-a2ff-e04fda4d09cb"
            }
          ],
          "body": "{\n  \"success\": false,\n  \"message\": \"Domain lookup provider is temporarily rate limited. Please retry shortly.\",\n  \"response_code\": 429,\n  \"error_type\": \"rate_limited\",\n  \"retryable\": true,\n  \"retry_after\": 60\n}"
        },
        {
          "name": "Invalid provider response",
          "status": "Bad Gateway",
          "code": 502,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Request-Id",
              "value": "7d9df214-0f4d-4c0f-a2ff-e04fda4d09cb"
            }
          ],
          "body": "{\n  \"success\": false,\n  \"message\": \"Domain lookup provider returned an invalid response. Please retry.\",\n  \"response_code\": 502,\n  \"error_type\": \"lookup_invalid_response\",\n  \"retryable\": true,\n  \"retry_after\": 60\n}"
        },
        {
          "name": "Lookup timeout",
          "status": "Service Unavailable",
          "code": 503,
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            },
            {
              "key": "X-Request-Id",
              "value": "7d9df214-0f4d-4c0f-a2ff-e04fda4d09cb"
            }
          ],
          "body": "{\n  \"success\": false,\n  \"message\": \"Domain lookup is taking longer than expected. Please retry shortly.\",\n  \"response_code\": 503,\n  \"error_type\": \"lookup_timeout\",\n  \"retryable\": true,\n  \"retry_after\": 60\n}"
        }
      ]
    }
  ]
}