Skip to main content
VerifyThisSeal.com
A Seal CodeA Professional
Stamps Center Documents Center Brand Center User Guides
Pricing Contact
Login
← Back to User Guides

Professional Look Up API

GET /api/lookup-professional

This endpoint allows you to search for and verify design professionals by their state, license number, and name. It uses progressive matching to handle variations in name formatting and returns comprehensive professional information including their verification status within the VerifyThisSeal system.

Authentication

API Key Required: Yes - Contact us for Access.

Secret Key: Required if the API key is created with a secret key.

User Specific Authentication: No at this time.

API Key Authentication

The API uses a two-level authentication system:

  1. API Key (Required): Primary authentication key

    Provided in X-API-Key header. Must be included in all API requests.

  2. Secret Key (Conditional): Secondary authentication key

    Provided in X-API-Secret header. Required ONLY if the API key was created with a secret key. Must be provided as a pair with its corresponding API key. Requests will be rejected if no secret key is provided when one is required, an invalid secret key is provided, or a secret key is provided for an API key that doesn't use one.

Rate Limiting

Rate Limit: 25 failed requests per 15 minutes per IP address (variable upon request).

Logging: All requests are logged for monitoring, analytics, and abuse detection.

Headers

X-API-Key: YOUR-API-KEY (Required)
X-API-Secret: YOUR-SECRET-KEY (Required if API key was created with a secret key)

Query Parameters

state=string // Two-character state abbreviation (e.g., "CA", "TX", "OH") license_number=string // Professional license number (partial matching supported) first_name=string // Professional's first name (partial matching with progressive expansion) last_name=string // Professional's last name (partial matching with progressive expansion)

Example Call

GET http://verifythisseal.com/api/lookup-professional?state=OH&license_number=5555&first_name=John&last_name=Smith Headers: X-API-Key: YOUR-API-KEY X-API-Secret: YOUR-SECRET-KEY // Only if required by your API key

Response

Professional Found

{ "success": true, "professional": { "state": "OH", "state_name": "Ohio", "profession_type": "RA", "profession_name": "Registered Architect", "license_number": "OH_RA-5555", "first_name": "John", "last_name": "Smith", "status": "claimed_with_codes" }, "message": "Professional found and verified" }

No Professional Found

{ "success": true, "professional": null, "message": "No matching professional found" }

Multiple Matches Found

{ "success": false, "error": "multiple_matches", "message": "Found 3 matching professionals. Please provide the complete license number including any prefixes or suffixes to uniquely identify the professional. You may also attempt to validate using VerifyThisSeal.com/professionals.", "count": 3 }

Response Fields

When a professional is found, the API returns comprehensive information:

professional Object

  • state: Two-character state abbreviation where the license is valid
  • state_name: Full state name
  • profession_type: Profession abbreviation (e.g., "RA", "PE", "LS")
  • profession_name: Full profession name (e.g., "Registered Architect")
  • license_number: Complete professional license number
  • first_name, last_name: Professional's full name as registered
  • status: VerifyThisSeal system status:
    • "claimed_with_codes" - Professional has claimed their profile and has active seal codes
    • "claimed_no_codes" - Professional has claimed their profile but no active seal codes
    • "claimed_pending" - Professional has claimed their profile but verification is pending
    • "unclaimed" - Professional exists in database but hasn't claimed their profile

Progressive Matching Algorithm

The endpoint uses intelligent progressive matching to handle name variations:

  1. Starts with minimal character matching (1 character first name, 2 characters last name)
  2. Progressively expands character matching until a unique match is found
  3. Handles common variations like nicknames, abbreviations, and formatting differences
  4. Returns single result when unique match is achieved
  5. Returns error if multiple professionals match even with full name expansion

Error Responses

Missing Required Parameters (400)

{ "success": false, "message": "All parameters are required: state, license_number, first_name, last_name" }

Invalid State Format (400)

{ "success": false, "message": "State must be a 2-character abbreviation (e.g., \"CA\", \"TX\")" }

Multiple Professionals Match (400)

{ "success": false, "error": "multiple_matches", "message": "Found 3 matching professionals. Please provide the complete license number including any prefixes or suffixes to uniquely identify the professional. You may also attempt to validate using VerifyThisSeal.com/professionals.", "count": 3 }

Missing API Key (401)

{ "success": false, "message": "API key required. Please include X-API-Key header or api_key in request body." }

Invalid API Key (401)

{ "success": false, "message": "Invalid API key" }

Server Error (500)

{ "success": false, "message": "Internal server error during professional lookup" }

Rate Limit Exceeded (429)

{ "success": false, "message": "Too many failed professional lookup requests from this IP. Please try again after 15 minutes.", "retryAfter": 900 }

Invalid Input (400)

{ "success": false, "message": "Invalid request format detected." }

High-Performance Endpoints

For applications requiring optimized performance, alternative endpoints are available:

  • /api/lookup-professional-fast - Memory-cached responses for frequently accessed professionals
  • /api/lookup-professional-optimized - Streamlined database queries for reduced latency

These endpoints use the same parameters and authentication but provide faster response times for high-volume applications.

Example Usage

curl "http://verifythisseal.com/api/lookup-professional?state=OH&license_number=5555&first_name=John&last_name=Smith" \ -H "X-API-Key: VTS-DEMO-KEY-2025"

Notes

  1. State Format: Always use 2-character state abbreviations (e.g., "CA" for California, "TX" for Texas).
  2. License Number Matching: Partial license numbers are supported. The system will find matches containing your provided string.
  3. Name Matching: The progressive matching algorithm handles variations in name formatting, abbreviations, and common nicknames automatically.
  4. Unique Results: The endpoint is designed to return a single professional when possible. If multiple professionals match your criteria, you'll receive an error asking for more specific license number information.
  5. Professional Status: The status field indicates whether the professional has claimed their VerifyThisSeal profile and their current verification status within our system.
  6. Read-Only Operation: This endpoint only reads professional data and does not modify any information.
  7. Comprehensive Database: Our database includes professionals from all 50 US states across multiple disciplines including architects, engineers, surveyors, and other licensed design professionals.
  8. API Usage Tracking: All requests are logged with the API key used (partially masked) for audit and analytics purposes.

Test Data

For testing purposes, you can use:

  • State: OH
  • License Number: 5555
  • First Name: John
  • Last Name: Smith
  • Expected Result: Ohio Registered Architect details with claimed status

Was this article helpful?