Seal Validation API

seal_code=string              // Seal code without dashes (e.g., "6FP4UL6Y5E")
professional_seal_number=string // Professional seal number (e.g., "OH_RA-5555" or just "5555")

GET http://verifythisseal.com/api/validate-seal?seal_code=6FP4UL6Y5E&professional_seal_number=5555

Headers:
X-API-Key: YOUR-API-KEY
X-API-Secret: YOUR-SECRET-KEY  // Only if required by your API key

Response

Successful Match (Contact Info Enabled, Contact Info is NULL if Disabled)

{
  "success": true,
  "match": true,
  "seal_details": {
    "seal_code": "6FP4UL6Y5E",
    "characteristic_1": "SG Hospitality TI\r\n100 State Street\r\nColumbus, Ohio 43215",
    "characteristic_2": "ARM Arch+Co.\r\n901 W. Main St\r\nColumbus, Ohio 43215\r\n614-123-4482", 
    "characteristic_3": "Project No. 25-931 / Permit Set 03.14.15",
    "seal_holder": {
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@example.com",
      "phone_number": "6141234567"
    },
    "profession": {
      "name": "Registered Architect",
      "abbreviation": "RA",
      "license_number": "OH_RA-5555",
      "state": "Ohio",
      "state_abbreviation": "OH",
      "regulating_board": {
        "name": "Architects Board",
        "website": "https://com.ohio.gov/divisions/architects-board"
      }
    },
    "view_count": 42
  },
  "message": "Seal code validated successfully"
}

No Match (Professional Number Mismatch)

{
  "success": true,
  "match": false,
  "message": "Seal code found but professional seal number does not match"
}

Seal Code Not Found

{
  "success": true,
  "match": false,
  "message": "Seal code not found or inactive"
}

Response Fields

When a successful match is found, the API returns comprehensive information about the validated seal:

seal_details Object

• seal_code: The validated seal code

• characteristic_1, characteristic_2, characteristic_3: The three identifying characteristics printed on the physical seal

• view_count: Total number of successful validations (web + API) for this seal

seal_holder Object

• first_name, last_name: Name of the professional who owns this seal

• email, phone_number: Contact information fields (always present but set to null if the seal holder has disabled public contact sharing for this specific seal code)

profession Object

• name: Full profession name (e.g., "Registered Architect")

• abbreviation: Profession abbreviation (e.g., "RA")

• license_number: Complete professional license number

• state, state_abbreviation: State where the license is valid

• regulating_board: Object containing name and website of the regulating board

Error Responses

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"
}

Missing Required Secret Key (401)

{
  "success": false,
  "message": "This API key requires a secret key. Please provide it in the X-API-Secret header"
}

Invalid API Key and Secret Pair (401)

{
  "success": false,
  "message": "Invalid API key and secret pair"
}

Unexpected Secret Key (401)

{
  "success": false,
  "message": "This API key does not use a secret key. Please remove the X-API-Secret header"
}

Missing Required Fields (400)

{
  "success": false,
  "message": "Both seal_code and professional_seal_number are required"
}

Invalid Professional Seal Number (400)

{
  "success": false,
  "message": "Professional seal number must contain at least 4 characters"
}

Server Error (500)

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

Rate Limit Exceeded (429)

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

Malicious Input Detected (400)

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

Input Too Long (400)

{
  "success": false,
  "message": "Seal code too long. Maximum 50 characters allowed."
}

Example Usage

curl "http://localhost:8080/api/validate-seal?seal_code=6FP4UL6Y5E&professional_seal_number=5555" \
  -H "X-API-Key: VTS-DEMO-KEY-2025"

Notes

1. Seal Code Format: The API accepts seal codes without dashes.

2. Professional Seal Number: Only the last 4 digits are used for validation. You can pass the full professional seal number (e.g., "OH_RA-5555") or just the last 4 digits (e.g., "5555").

3. Read-Only with View Tracking: This API endpoint only reads data and does not modify seal information. However, successful validations are tracked as public views in the system analytics.

4. View Counter: Each successful validation increments a public view counter for that seal code. The view_count field in the response shows the total number of times this seal has been successfully validated (including both web interface and API validations).

5. Comprehensive Professional Data: Successful validations return complete information about the seal holder including their name, profession details, and the regulating board information. Contact information (email and phone) is only included if the seal holder has specifically enabled public contact sharing for that seal code.

6. Privacy Controls: Each seal code has individual privacy settings. Seal holders can choose whether to make their contact information publicly accessible through API validations. The email and phone_number fields are always included in successful responses for API consistency, but will be set to null when contact sharing is disabled.

7. API Usage Tracking: All API requests are logged with the API key used (partially masked) for audit and analytics purposes.

Test Data

For testing purposes, you can use:

• Seal Code: 6FP4UL6Y5E (dashes are not permitted to be sent in the request 6FP-4UL6-Y5E)

• Professional Seal Number: 5555 (or OH_RA-5555)

• Expected Result: Match with Ohio Registered Architect details