USPTO Filing Bot

System Overview & Lifecycle

This API powers a fully autonomous USPTO trademark filing bot. The end-to-end flow is:

Key Concepts

• Applicant — a person/entity for whom a USPTO account is created. One applicant can have many applications.
• Application — a single trademark filing tied to an applicant. Created via the master filing API.
• Company — a tenant. Each applicant belongs to a company. Companies have email domains and callback URLs.
• Lookup Codes — all enum-like fields use string codes (not database IDs). The API resolves them server-side.
• Callbacks — the bot sends webhook notifications to your registered callback URLs for status changes.

Important Rules

Response Envelope (All Endpoints)

// Success
{
  "IsSuccess": true,
  "Data": { ... },
  "Message": "Request completed successfully.",
  "StatusCode": 200
}

// Error
{
  "IsSuccess": false,
  "Data": { "errors": [ { "path": "...", "code": "...", "message": "..." } ] },
  "Message": "Validation failed",
  "StatusCode": 400
}

USPTO Wizard Pages

When the bot files a trademark, it drives a multi-page USPTO wizard. Each section of your API payload maps to one or more wizard pages.

Wizard Page Sequence

Entity Type → USPTO Owner Form

Mark Format → Wizard Path

Filing Basis → Wizard Behavior

Address Rules

• Mailing Address — always shown. Primary public address on trademark record.
• Domicile Address — only shown when "same as mailing" is unchecked.
• When country = "United States" → State dropdown appears and must be filled.
• When country ≠ "United States" → State field is hidden.

POST /applicants/create-applicant

Creates a new applicant and provisions a USPTO mailbox. The bot automatically picks up PENDING applicants and begins account creation.

Request Body

{
  "companyId": 1,
  "customerId": 1014,
  "nameTitle": "Mr",
  "firstName": "Mike",
  "middleName": null,
  "lastName": "Jacob",
  "suffix": null,
  "emailAddress": "[email protected]",
  "emailDomain": "trademarkluv.com",
  "country": "US",
  "state": "TX",
  "cityId": null,
  "streetAddress1": "411 Spruce St",
  "streetAddress2": null,
  "zipCode": "78701",
  "phone": {
    "dialCode": "1",
    "countryCode": "US",
    "number": "2179856987"
  }
}

Field Reference

What Happens Internally

1. Country/state codes resolved to database IDs.
2. emailDomain validated against AvailableDomains table.
3. Cryptographically strong USPTO-compliant password auto-generated (14 chars).
4. Applicant inserted with PENDING (1) status.
5. USPTO email mailbox provisioned: {firstname}.{lastname}{customerId}@{emailDomain}.
6. Bot picks up on next cycle (every 10 seconds) and begins automation.

Success Response — 201 Created

{
  "IsSuccess": true,
  "Data": {
    "applicantId": 42,
    "usptoAccountEmail": "[email protected]",
    "lifecycleStatus": "PENDING"
  },
  "Message": "Applicant created successfully.",
  "StatusCode": 201
}

GET /applicants/:id/get-2fa-code

Returns the current live 6-digit TOTP code for an applicant's USPTO MFA account. The code is generated server-side from the MFASecret stored in the database using RFC 6238 (SHA-1, 30-second window) — identical to Google Authenticator output.

URL Parameter

Success Response — 200 OK

{
  "IsSuccess": true,
  "Data": {
    "applicantId": 24,
    "usptoAccountEmail": "[email protected]",
    "totpCode": "482910",
    "generatedAt": "2026-06-06T00:00:00.000Z"
  },
  "Message": "Request completed successfully.",
  "StatusCode": 200
}

Response Fields

Error Responses

POST /applications/create-complete-application

Creates a complete trademark filing in a single atomic transaction. All child entities are inserted together — if any part fails, nothing is saved.

Top-Level Fields

Owner Object

Address Object

Phone Object

Attorney Object

Set to null to file pro se (without attorney). The bot skips the Attorney page entirely.

Correspondence Object

Mark Object

File Reference Object

Two options for providing files:

// Option A: Reference existing uploaded file
{ "fileAssetId": 123 }

// Option B: URL for bot to download
{ "sourceUrl": "https://example.com/logo.png" }

Mark Cross-Field Validation

Goods/Services Object

Goods/Services Cross-Field Validation

Declaration Object

PUT /applications/create-complete-application/:appId

Atomically replaces an existing PENDING application. Deletes all child entities and re-inserts from the new payload.

Request body is identical to POST. The applicantId in the body is still required.

Lookup API Reference

Other Lookup Endpoints

GET /api/v1/lookup/countries
GET /api/v1/lookup/states?countryId=1
GET /api/v1/lookup/cities?stateId=44
GET /api/v1/lookup/domains?companyId=1
GET /api/v1/lookup/companies
GET /api/v1/lookup/uspto-classes
GET /api/v1/lookup/uspto-sub-classes?classCode=045

All Lookup Values

Application Types

Owner Entity Types

Owner Member Roles

Alternate Name Types

Mark Formats

Stylized Mark Types

Filing Basis

Goods Entry Types

Signature Methods

Name Likeness Types

Consent Proof Types

Error Codes Reference

Schema Validation Errors (Zod — HTTP 400)

Business Validation Errors (HTTP 400)

HTTP Status Codes

Complete Example Payloads

Example 1: Individual Owner, Standard Text Mark, 1A Basis

Scenario: An individual files a standard character trademark already in use.

{
  "applicantId": 42,
  "clientApplicationId": "CLIENT-REF-001",
  "application": { "typeCode": "standard" },
  "owners": [
    {
      "ownerOrder": 1,
      "entityTypeCode": "individual",
      "firstName": "Mike",
      "lastName": "Jacob",
      "countryOfCitizenshipCode": "US",
      "domicile": {
        "streetLine1": "411 Spruce St",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94102",
        "country": "United States"
      },
      "sameDomicileAndMailing": true,
      "noPhysicalLocation": false,
      "email": "[email protected]",
      "phone": { "dialCode": "1", "number": "2179856987" }
    }
  ],
  "attorney": null,
  "correspondence": {
    "name": "Mike Jacob",
    "primaryEmail": "[email protected]"
  },
  "mark": {
    "formatCode": "Standard Character Mark",
    "text": "NEXOCRAFT",
    "description": "The mark consists of standard characters NEXOCRAFT."
  },
  "goodsServices": [
    {
      "entryOrder": 1,
      "entryTypeCode": "idManual",
      "classNumber": "045",
      "subClassCode": "045-2381",
      "filingBasisCode": "1A",
      "firstUseAnywhereDate": "01/15/2023",
      "firstUseInCommerceDate": "03/01/2023",
      "specimen": {
        "description": "Screenshot of homepage showing the mark in use.",
        "webUrl": "https://techbrand.com",
        "accessDate": "2024-01-15",
        "file": { "sourceUrl": "https://example.com/specimen.jpg" }
      }
    }
  ],
  "declaration": {
    "signatureMethodCode": "Electronic Signature",
    "signatoryName": "Mike Jacob",
    "signatureText": "/Mike Jacob/",
    "acknowledgeBasis": true,
    "acknowledgeUniqueness": true,
    "acknowledgeFactualContents": true,
    "acknowledgeWarning": true
  }
}

Example 2: US LLC with Attorney, Logo Mark, Intent to Use

Scenario: A US LLC with members files a color logo with an attorney.

{
  "applicantId": 42,
  "application": { "typeCode": "standard" },
  "owners": [
    {
      "ownerOrder": 1,
      "entityTypeCode": "us_llc",
      "entityName": "TechBrand LLC",
      "stateOfIncorporationCode": "DE",
      "domicile": {
        "streetLine1": "123 Innovation Drive",
        "city": "Austin",
        "state": "Texas",
        "postalCode": "78701",
        "country": "US"
      },
      "sameDomicileAndMailing": true,
      "email": "[email protected]",
      "phone": { "dialCode": "1", "number": "5125550101" },
      "website": "https://techbrand.com",
      "members": [
        { "roleCode": "member", "name": "John Carter", "entityType": "individual", "countryCode": "US" },
        { "roleCode": "manager", "name": "Jane Doe", "entityType": "individual", "countryCode": "US" }
      ]
    }
  ],
  "attorney": {
    "name": "Jane Smith",
    "firmName": "Smith IP Law PLLC",
    "barStateCode": "TX",
    "barNumber": "TX-24098765",
    "email": "[email protected]",
    "phone": { "dialCode": "1", "number": "5125559988" },
    "address": {
      "streetLine1": "500 Congress Ave",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701",
      "country": "US"
    }
  },
  "correspondence": {
    "name": "Jane Smith",
    "primaryEmail": "[email protected]",
    "secondaryEmails": ["[email protected]"]
  },
  "mark": {
    "formatCode": "Special Form",
    "text": "TECHBRAND",
    "stylizedMarkTypeCode": "Wording and Design",
    "colorClaimed": true,
    "description": "The mark consists of TECHBRAND in stylized blue text with a gear icon.",
    "colorClaim": "The color blue is claimed as a feature of the mark.",
    "drawingFile": { "sourceUrl": "https://example.com/logo.png" }
  },
  "goodsServices": [
    {
      "entryOrder": 1,
      "entryTypeCode": "freeForm",
      "classNumber": "042",
      "freeFormText": "Software as a service (SaaS) featuring platforms for business automation",
      "filingBasisCode": "1B"
    }
  ],
  "declaration": {
    "signatureMethodCode": "Electronic Signature",
    "signatoryName": "John Carter",
    "signatoryTitle": "CEO",
    "signatureText": "/John Carter/",
    "acknowledgeBasis": true,
    "acknowledgeUniqueness": true,
    "acknowledgeFactualContents": true,
    "acknowledgeWarning": true
  }
}

Example 3: Trust with Translations & Name Consent

Scenario: A trust with trustees files a color logo containing a foreign word and a living person's name.

{
  "applicantId": 42,
  "application": { "typeCode": "standard" },
  "owners": [
    {
      "ownerOrder": 1,
      "entityTypeCode": "trust",
      "entityName": "Carter Family Trust",
      "domicile": {
        "streetLine1": "500 Park Ave",
        "city": "New York",
        "state": "NY",
        "postalCode": "10022",
        "country": "United States"
      },
      "sameDomicileAndMailing": false,
      "mailingAddress": {
        "streetLine1": "PO Box 5500",
        "city": "New York",
        "state": "NY",
        "postalCode": "10022",
        "country": "US"
      },
      "email": "[email protected]",
      "phone": { "dialCode": "1", "number": "2125550300" },
      "members": [
        { "roleCode": "trustee", "name": "John Carter", "entityType": "individual", "countryCode": "US" },
        { "roleCode": "trustee", "name": "Sarah Carter", "entityType": "individual", "countryCode": "US" }
      ]
    }
  ],
  "attorney": null,
  "correspondence": {
    "name": "John Carter",
    "primaryEmail": "[email protected]"
  },
  "mark": {
    "formatCode": "Special Form",
    "text": "CASA CARTER",
    "stylizedMarkTypeCode": "Wording and Design",
    "colorClaimed": true,
    "description": "The mark consists of CASA CARTER in stylized gold script over a shield design.",
    "colorClaim": "The colors gold and navy blue are claimed as features of the mark.",
    "drawingFile": { "sourceUrl": "https://example.com/casa-carter-logo.png" },
    "translations": [
      {
        "isNonLatinPhrase": false,
        "nonEnglishWord": "Casa",
        "language": "Spanish",
        "hasEnglishMeaning": true,
        "englishTranslation": "House"
      }
    ],
    "nameConsents": [
      {
        "likenessTypeCode": "name",
        "legalName": "John Carter",
        "isSignatory": true,
        "consentToRegister": true,
        "proofTypeCode": "declaration"
      }
    ]
  },
  "goodsServices": [
    {
      "entryOrder": 1,
      "entryTypeCode": "idManual",
      "classNumber": "025",
      "subClassCode": "025-0100",
      "filingBasisCode": "1B"
    }
  ],
  "declaration": {
    "signatureMethodCode": "Electronic Signature",
    "signatoryName": "John Carter",
    "signatoryTitle": "Trustee",
    "signatureText": "/John Carter/",
    "acknowledgeBasis": true,
    "acknowledgeUniqueness": true,
    "acknowledgeFactualContents": true,
    "acknowledgeWarning": true
  }
}

Fetching USPTO Classes

GET /api/v1/lookup/uspto-classes
→ [
    { "Id": 1, "ClassCode": "001", "ClassTitle": "Chemicals", "ClassType": "Goods" },
    { "Id": 9, "ClassCode": "009", "ClassTitle": "Electrical and Scientific Apparatus", "ClassType": "Goods" },
    { "Id": 42, "ClassCode": "042", "ClassTitle": "Computer & Scientific & Legal", "ClassType": "Services" },
    { "Id": 45, "ClassCode": "045", "ClassTitle": "Personal & Legal & Social", "ClassType": "Services" }
  ]

GET /api/v1/lookup/uspto-sub-classes?classCode=045
→ [
    { "Id": 100, "SubClassCode": "045-2381", "ClassCode": "045", "SubClassTitle": "Online social networking..." },
    { "Id": 101, "SubClassCode": "045-2380", "ClassCode": "045", "SubClassTitle": "Social introduction..." }
  ]

Date Format Summary

Bot Automation Details

Filing Data Pipeline

Bot Behavior Highlights

• Draft, not submit: The bot saves as a USPTO draft — does NOT click final "Submit".
• Signature date writeback: USPTO auto-generates a signing date. Bot reads it and writes back to your DB.
• AI mark description: For Special Form, bot accepts USPTO's AI suggestion. Falls back to your text if AI fails.
• Color conversion: Color image + colorClaimed = false → bot auto-accepts B&W conversion.
• Multi-owner tabs: Bot adds owner tabs via "+ Add" and fills each sequentially.
• Phone dial code: Bot interacts with flag-picker. US default ("1") needs no interaction.
• Screenshots: Taken at key steps and on every error. Stored in screenshots/.
• Error reporting: Page validation errors captured and sent via webhook.

Webhook Callbacks

Callbacks are delivered with retry logic (configurable per company). Failed deliveries use linear backoff up to a configurable maximum.

WebSocket — Live TOTP Authenticator

The server exposes a WebSocket endpoint that pushes the current live TOTP codes for all enrolled applicants every 10 seconds (configurable via AUTHENTICATOR_REFRESH_INTERVAL_MS env var). No polling required — just connect and listen.

Connect & Listen

const ws = new WebSocket("https://filingbot.crmbytes.com/api/authenticator");

ws.onopen = () => console.log("Connected");

ws.onmessage = (e) => {
  const snapshot = JSON.parse(e.data);
  console.log(snapshot);
};

ws.onclose = () => console.log("Disconnected");
ws.onerror = (err) => console.error("WS error", err);

Behavior on Connect

Message Shape (IAuthenticatorSnapshot)

{
  "capturedAt": "2026-06-06T00:00:00.000Z",
  "entries": [
    {
      "issuer": "[email protected]",
      "account": "Applicant #24",
      "code": "482910"
    },
    {
      "issuer": "[email protected]",
      "account": "Applicant #42",
      "code": "719034"
    }
  ]
}

Field Reference

Key Points

• Server-sent only — this is a one-way broadcast. The client never sends messages; the server ignores any inbound frames.
• All applicants in one message — every broadcast contains codes for all enrolled applicants. Filter by issuer or account on the client side.
• Same port — no extra port. The WS server is attached to the same HTTP server as the REST API (:3001 by default).
• Codes expire every 30s — RFC 6238, SHA-1, 30-second window. A code received near a window boundary may expire within seconds. The next broadcast (within 10s) will carry the fresh code.
• Only enrolled applicants — applicants without an MFASecret (Phase 1 not yet completed) are silently excluded from the snapshot.