Seal Code Generation API

Seal Code Generation Workflow

Two-step process: first discover the user's available seals, then generate codes for specific seals using their UUIDs.

API Workflow Overview

Step 1: GET /api/v3/user/seals - Retrieve the user's available professional seals
Step 2: POST /api/v3/user/seals/{sealId}/codes - Generate seal code for a specific seal

Important: Seal UUIDs are only exposed through API calls and should be stored by the user's application for future use. You cannot generate seal codes without first retrieving the user's available seals.

Step 1: GET /api/v3/user/seals

Retrieve all professional seals associated with the user's account. This endpoint returns the seal UUIDs required for code generation.

Authentication

User API Secret Required: Yes - Generate from the user's account dashboard at My API Keys.

Headers

Header	Required	Description
`X-API-Secret`	Required	the user's user API secret token
`Authorization`	Alternative	Bearer token format: `Bearer YOUR-API-SECRET`

Example Request

GET https://verifythisseal.com/api/v3/user/seals

Headers:
X-API-Secret: usr_secret_abc123def456ghi789jkl

Example cURL Command

curl -X GET "https://verifythisseal.com/api/v3/user/seals" \
  -H "X-API-Secret: usr_secret_abc123def456ghi789jkl"

Response - Available Seals

{
  "success": true,
  "data": {
    "seals": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "identifier": "OH_PE-12345",
        "licenseNumber": "12345",
        "profession": {
          "name": "Professional Engineer",
          "abbreviation": "PE",
          "state": {
            "abbreviation": "OH",
            "name": "Ohio"
          }
        },
        "professionalName": {
          "firstName": "John",
          "lastName": "Smith",
          "fullName": "John Smith"
        },
        "status": "approved",
        "createdAt": "2024-01-15T10:30:00.000Z"
      },
      {
        "id": "660f9511-f3ac-52e5-b827-557766551111",
        "identifier": "CA_RA-67890",
        "licenseNumber": "67890",
        "profession": {
          "name": "Registered Architect",
          "abbreviation": "RA",
          "state": {
            "abbreviation": "CA",
            "name": "California"
          }
        },
        "professionalName": {
          "firstName": "John",
          "lastName": "Smith",
          "fullName": "John Smith"
        },
        "status": "approved",
        "createdAt": "2024-02-20T14:15:00.000Z"
      }
    ],
    "totalSeals": 2
  },
  "meta": {
    "apiVersion": "3.0",
    "timestamp": "2025-08-19T10:30:00.000Z",
    "endpoint": "user/seals",
    "method": "GET"
  }
}

Seal Object Fields

Field	Type	Description
`id`	UUID	Store this UUID - Required for generating seal codes
`identifier`	String	Human-readable seal identifier (State_Profession-License)
`licenseNumber`	String	Professional license number
`profession`	Object	Complete profession and state information
`professionalName`	Object	Seal holder's name information
`status`	String	Seal status (only "approved" seals can generate codes)
`createdAt`	ISO 8601 DateTime	When the seal was added to the user's account

Step 2: POST /api/v3/user/seals/{sealId}/codes

Generate a seal code for a specific professional seal using the UUID from Step 1.

Authentication

User API Secret Required: Yes - Generate from the user's account dashboard at My API Keys.

Headers

Header	Required	Description
`X-API-Secret`	Required	the user's user API secret token
`Authorization`	Alternative	Bearer token format: `Bearer YOUR-API-SECRET`
`Content-Type`	Required	Must be `application/json`

Path Parameters

Parameter	Type	Required	Description
`sealId`	UUID	Required	The seal UUID from Step 1 (GET /api/v3/user/seals)

Request Body Parameters

Parameter	Type	Required	Description
`characteristic1`	String	Required	First identifying characteristic
`characteristic2`	String	Required	Second identifying characteristic
`characteristic3`	String	Required	Third identifying characteristic
`showContactInfo`	Boolean	Optional	Whether to show contact information in verification (default: false)

Example Request

POST https://verifythisseal.com/api/v3/user/seals/550e8400-e29b-41d4-a716-446655440000/codes

Headers:
X-API-Secret: usr_secret_abc123def456ghi789jkl
Content-Type: application/json

Body:
{
  "characteristic1": "ABC Office Building - Structural Plans",
  "characteristic2": "Revision 3 - 2025-08-19",
  "characteristic3": "Sheet S1.1 - Foundation Plan",
  "showContactInfo": false
}

Note: The sealId must be obtained from Step 1 (GET /api/v3/user/seals).

Example cURL Command

# Step 1: Get your seals first
curl -X GET "https://verifythisseal.com/api/v3/user/seals" \
  -H "X-API-Secret: usr_secret_abc123def456ghi789jkl"

# Step 2: Use a seal UUID from Step 1 response
curl -X POST "https://verifythisseal.com/api/v3/user/seals/550e8400-e29b-41d4-a716-446655440000/codes" \
  -H "X-API-Secret: usr_secret_abc123def456ghi789jkl" \
  -H "Content-Type: application/json" \
  -d '{
    "characteristic1": "ABC Office Building - Structural Plans",
    "characteristic2": "Revision 3 - 2025-08-19", 
    "characteristic3": "Sheet S1.1 - Foundation Plan",
    "showContactInfo": false
  }'

Response

Successful Code Generation (201 Created)

{
  "success": true,
  "data": {
    "sealCode": "7P7-PVAJ-SQV",
    "sealCodeRaw": "7P7PVAJSQV",
    "characteristics": {
      "characteristic1": "ABC Office Building - Structural Plans",
      "characteristic2": "Revision 3 - 2025-08-19",
      "characteristic3": "Sheet S1.1 - Foundation Plan"
    },
    "showContactInfo": false,
    "professionalSeal": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "identifier": "OH_PE-12345",
      "licenseNumber": "12345",
      "profession": {
        "name": "Professional Engineer",
        "abbreviation": "PE",
        "state": {
          "abbreviation": "OH",
          "name": "Ohio"
        }
      },
      "professionalName": {
        "firstName": "John",
        "lastName": "Smith",
        "fullName": "John Smith"
      }
    },
    "generatedBy": {
      "userId": "user-uuid-here",
      "name": "John Smith"
    },
    "createdAt": "2025-08-19T10:30:00.000Z",
    "verificationUrl": "https://verifythisseal.com/code?seal_code=7P7-PVAJ-SQV"
  },
  "meta": {
    "apiVersion": "3.0",
    "timestamp": "2025-08-19T10:30:00.000Z",
    "endpoint": "user/seals/codes",
    "method": "POST"
  }
}

Response Fields

`data` Object

Field	Type	Description
`sealCode`	String	Formatted seal code (XXX-XXXX-XXX) for display and verification
`sealCodeRaw`	String	Raw seal code (XXXXXXXXXX) without formatting for database storage
`characteristics`	Object	The three identifying characteristics provided for this seal code
`showContactInfo`	Boolean	Whether contact information will be shown during verification
`professionalSeal`	Object	Complete information about the professional seal used
`generatedBy`	Object	Information about the user who generated this code
`createdAt`	ISO 8601 DateTime	Timestamp when the seal code was created
`verificationUrl`	String	Direct URL for public verification of this seal code

`professionalSeal` Object Details

id: UUID of the professional seal
identifier: State and license identifier (e.g., "OH_PE-12345")
licenseNumber: Professional license number
profession: Detailed profession information including name, abbreviation, and state
professionalName: Full name details of the seal holder

Error Responses

Missing API Secret (401)

{
  "success": false,
  "error": "Missing API secret. Include X-API-Secret header or Authorization: Bearer header.",
  "code": "MISSING_API_SECRET"
}

Invalid API Secret (401)

{
  "success": false,
  "error": "Invalid or expired API secret",
  "code": "INVALID_API_SECRET"
}

Missing Required Fields (400)

{
  "success": false,
  "error": "All three identifying characteristics are required",
  "code": "MISSING_CHARACTERISTICS"
}

Invalid Seal ID Format (400)

{
  "success": false,
  "error": "Invalid seal ID format",
  "code": "INVALID_SEAL_ID_FORMAT"
}

Seal Not Found (404)

{
  "success": false,
  "error": "Professional seal not found or not accessible",
  "code": "SEAL_NOT_FOUND"
}

Subscription Required (402)

{
  "success": false,
  "error": "Subscription required. You have used all 3 free seal codes. Please subscribe to generate additional codes.",
  "code": "SUBSCRIPTION_REQUIRED",
  "data": {
    "freeCodesUsed": 3,
    "freeCodesLimit": 3,
    "subscriptionStatus": "inactive",
    "enterpriseCoverage": "none"
  }
}

Rate Limit Exceeded (429)

{
  "success": false,
  "error": "Rate limit exceeded. Please wait before making additional requests.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 3600
}

Server Error (500)

{
  "success": false,
  "error": "Internal server error while generating seal code",
  "code": "CODE_GENERATION_ERROR"
}

Security Features

All requests are validated and logged for audit purposes.

Integration Notes

Complete Workflow Example

# Complete workflow example
# Step 1: Get available seals
SEALS_RESPONSE=$(curl -s -X GET "https://verifythisseal.com/api/v3/user/seals" \
  -H "X-API-Secret: usr_secret_abc123def456ghi789jkl")

# Step 2: Extract seal ID from response (example using jq)
SEAL_ID=$(echo $SEALS_RESPONSE | jq -r '.data.seals[0].id')

# Step 3: Generate seal code using the extracted UUID
curl -X POST "https://verifythisseal.com/api/v3/user/seals/$SEAL_ID/codes" \
  -H "X-API-Secret: usr_secret_abc123def456ghi789jkl" \
  -H "Content-Type: application/json" \
  -d '{
    "characteristic1": "Project ABC - Structural Plans",
    "characteristic2": "Revision 2 - 2025-08-19",
    "characteristic3": "Sheet S1.1",
    "showContactInfo": false
  }'

Application Integration Pattern

One-time Setup: Call GET /api/v3/user/seals to discover available seals
Store UUIDs: Cache the seal UUIDs in the user's application database/storage
User Selection: Present human-readable seal identifiers to users for selection
Code Generation: Use stored UUIDs to generate codes without repeated seal lookups
Refresh as Needed: Periodically refresh the seal list if users add new professional licenses

Subscription Requirements

Subscription/Enterprise Coverage Required: Seal code generation requires an active subscription or enterprise coverage after the first 3 free seal codes per user account.

Free Tier: 3 seal codes per user account
Active Subscription: Unlimited seal code generation
Enterprise Coverage: Unlimited seal code generation for covered professionals

Rate Limiting

Rate Limit: Based on the user's API secret configuration (default: 100 requests per hour)

UUID Management

Store UUIDs: Cache UUIDs in the user's application's storage for repeated use
Refresh When Needed: Re-fetch the seal list when users add new professional licenses to their account

Verification Integration

Generated seal codes can be verified using:

Public Web Interface: https://verifythisseal.com/code?seal_code=XXX-XXXX-XXX
API Verification: Use the public verification API endpoints

Email Notifications

When a seal code is generated via API, the seal owner receives an email notification with the seal code details.

Best Practices

Application Integration

Cache Seal Data: Store seal UUIDs and metadata from Step 1 in the user's application
User-Friendly Display: Show users readable seal identifiers instead of UUIDs
Efficient Workflows: Only call GET /api/v3/user/seals when initializing or when users add new licenses

Characteristic Guidelines

Specific and Unique: Use characteristics that uniquely identify the document or project.
Descriptive: Include sufficient detail for clear identification during verificatio.n
Standardized Format: Maintain consistent formatting across the user's organization

Error Handling

Implement Retry Logic: For temporary failures and rate limits
Handle Subscription States: Monitor for subscription requirement errors
Log API Responses: Maintain records for audit and troubleshooting

Storage Recommendations

Store Both Formats: Keep both formatted and raw seal code versions
Link Characteristics: Associate the three characteristics with the user's document management system
Verification URL: Store the verification URL for easy access

Support and Troubleshooting

For API integration support, documentation questions, or technical issues:

Email: support@verifythisseal.com
API Documentation: verifythisseal.com/docs/api
Account Dashboard: Manage API Keys
Professional Seals: View My Seals

API Version

Current Version: 3.0

Important Notes

Production Ready: This API generates real, verifiable seal codes
Billing Impact: Generated seal codes count against the user's subscription limits
Permanent Codes: Generated seal codes remain permanently verifiable

Seal Code Generation Workflow

API Workflow Overview

Step 1: GET /api/v3/user/seals

Authentication

Headers

Example Request

Example cURL Command

Response - Available Seals

Seal Object Fields

Step 2: POST /api/v3/user/seals/{sealId}/codes

Authentication

Headers

Path Parameters

Request Body Parameters

Example Request

Example cURL Command

Response

Successful Code Generation (201 Created)

Response Fields

data Object

professionalSeal Object Details

Error Responses

Missing API Secret (401)

Invalid API Secret (401)

Missing Required Fields (400)

Invalid Seal ID Format (400)

Seal Not Found (404)

Subscription Required (402)

Rate Limit Exceeded (429)

Server Error (500)

Security Features

Integration Notes

Complete Workflow Example

Application Integration Pattern

Subscription Requirements

Rate Limiting

UUID Management

Verification Integration

Email Notifications

Best Practices

Application Integration

Characteristic Guidelines

Error Handling

Storage Recommendations

Support and Troubleshooting

API Version

Important Notes

`data` Object

`professionalSeal` Object Details