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 record. Supports two modes controlled by the isOldApplicant flag:

• New applicant (isOldApplicant: false, default) — provisions a fresh USPTO mailbox. Bot picks up automatically and begins Phase 1 account creation.
• Old applicant (isOldApplicant: true) — tenant supplies existing USPTO credentials directly. Mailbox provisioning is skipped. Bot picks up at Phase 2 (claim verification → filing) immediately.

Request Body — New Applicant (isOldApplicant: false)

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

Request Body — Old Applicant (isOldApplicant: true)

{
  "companyId": 1,
  "customerId": 1014,
  "nameTitle": "Mr",
  "firstName": "Mike",
  "middleName": null,
  "lastName": "Jacob",
  "suffix": null,
  "emailAddress": "[email protected]",
  "isOldApplicant": true,
  "usptoAccountEmail": "[email protected]",
  "usptoAccountPassword": "Tr@deMark#9821",
  "mfaSecret": "JBSWY3DPEHPK3PXP",
  "botCode": null,
  "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

Mode A — New Applicant (isOldApplicant: false)

1. Country/state codes resolved to database IDs.
2. emailDomain validated against AvailableDomains table.
3. Duplicate check on emailAddress and customerId + companyId. Returns existing record if found.
4. Bot assigned via botCode (explicit) or automatic least-loaded allocation policy.
5. Cryptographically strong USPTO-compliant password auto-generated (14 chars).
6. Applicant inserted with lifecycle PENDING (1), email status PENDING.
7. USPTO mailbox provisioned: {pseudo}{customerId}@{emailDomain}. Lifecycle flipped to EMAIL_CREATED (2).
8. Bot picks up on next cycle (every 10 seconds) and begins Phase 1 account creation.

Mode B — Old Applicant (isOldApplicant: true)

1. Country/state codes resolved to database IDs.
2. Duplicate check on usptoAccountEmail, emailAddress, and customerId + companyId. Returns existing record if found.
3. Bot assigned via botCode (explicit) or automatic least-loaded allocation policy.
4. Applicant inserted with provided credentials. Lifecycle set directly to IDME_VERIFICATION_CLAIMED (13), email status CREATED. No password generation. No mailbox provisioning.
5. APPLICANT_STATUS_CHANGED callback fired immediately.
6. Bot picks up on next cycle and begins Phase 2 (claim verification → filing) directly.

Success Response — 201 Created

{
  "IsSuccess": true,
  "Data": {
    "applicantId": 42,
    "usptoAccountEmail": "[email protected]",
    "usptoAccountPassword": "Tr@deMark#9821",
    "emailProvisioned": true
  },
  "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

PUT /applicants/:id/claim-idme-verified

Allows a tenant to report whether an applicant has completed ID.me identity verification. Only applicants currently in ACCOUNT_CREATED (9) status are eligible.

URL Parameter

Query Parameters

Behavior

Success Response — 200 OK

// isVerified=true (default)
{
  "IsSuccess": true,
  "Data": {
    "applicantId": 42,
    "isVerified": true
  },
  "Message": "ID.me verification claim accepted. Bot will verify shortly.",
  "StatusCode": 200
}

// isVerified=false
{
  "IsSuccess": true,
  "Data": {
    "applicantId": 42,
    "isVerified": false
  },
  "Message": "Applicant marked as ID.me verification failed (terminal).",
  "StatusCode": 200
}

Error Responses

GET /applicants/get-applicant-info

Returns a comprehensive snapshot of an applicant with full filing detail for all (or one specific) application. Includes resolved lookup titles, live TOTP code, and complete filing data (owners, attorney, correspondence, mark, goods/services, declaration).

Query Parameters

Response Shape

The response includes the full applicant profile at the top level, with an applications array containing detailed filing data for each application. All lookup IDs are resolved to { id, title } pairs.

Each Application Object

Example Request

GET /api/v1/applicants/get-applicant-info?applicantId=42
GET /api/v1/applicants/get-applicant-info?applicantId=42&applicationId=101

Success Response — 200 OK (abbreviated)

{
  "IsSuccess": true,
  "Data": {
    "id": 42,
    "customerId": 1001,
    "firstName": "Mike",
    "lastName": "Jacob",
    "emailAddress": "[email protected]",
    "usptoAccountEmail": "[email protected]",
    "usptoAccountPassword": "xY9!kP2m@LqR7n",
    "mfaSecret": "JBSWY3DPEHPK3PXP",
    "totpCode": "482910",
    "accountCreatedAt": "2026-06-04T15:00:00.000Z",
    "phone": { "dialCode": "1", "countryCode": "US", "number": "2179856987" },
    "address": {
      "streetAddress1": "411 Spruce St",
      "city": { "id": 5, "title": "San Francisco" },
      "state": { "id": 5, "title": "California" },
      "stateISO2": "CA",
      "country": { "id": 1, "title": "United States" }
    },
    "lifeCycleStatus": { "id": 11, "title": "IDME Verified" },
    "emailStatus": { "id": 2, "title": "Created" },
    "company": { "id": 5, "title": "TradeMark Luv" },
    "applications": [
      {
        "id": 101,
        "filingStatus": { "id": 3, "title": "Done" },
        "applicationType": { "id": 1, "title": "Standard" },
        "clientApplicationId": "CLIENT-REF-001",
        "owners": [ { "ownerOrder": 1, "entityType": { "id": 1, "title": "Individual" }, ... } ],
        "attorney": null,
        "correspondence": { "name": "Mike Jacob", "primaryEmail": "[email protected]", ... },
        "mark": { "format": { "id": 1, "title": "Standard Character Mark" }, "text": "NEXOCRAFT", ... },
        "goodsServices": [ { "entryOrder": 1, "entryType": { "id": 1, "title": "ID Manual" }, ... } ],
        "declaration": { "signatureMethod": { "id": 1, "title": "Electronic Signature" }, ... }
      }
    ]
  },
  "Message": "Request completed successfully.",
  "StatusCode": 200
}

Error Responses

POST /utility/create-uspto-email

Provisions a standalone USPTO-compatible email mailbox via the third-party email provider. This does not create an Applicant record — it is a pure utility for callers that need a mailbox outside the normal onboarding flow.

Request Body

{
  "domain": "chattrik.com",
  "name": "Munib Shaikh",
  "email": "munib.shaikh"
}

Field Reference

What Happens Internally

1. Input validated via Zod — email containing @ is rejected with 400.
2. A cryptographically strong USPTO-compliant password is auto-generated (14 chars, mixed case + digits + special characters).
3. Third-party email vendor API is called with agent_Code = 0.
4. Full email address (email@domain) and password are returned.

Success Response — 201 Created

{
  "IsSuccess": true,
  "Data": {
    "emailAddress": "[email protected]",
    "password": "Xk7$mNp3Qw&jR2"
  },
  "Message": "Created",
  "StatusCode": 201
}

Error Responses

Error Response — 502 (vendor failure)

{
  "IsSuccess": false,
  "Data": {
    "emailAddress": "[email protected]",
    "vendorMessage": "Mailbox creation limit exceeded"
  },
  "Message": "USPTO mailbox provisioning failed at the email provider.",
  "StatusCode": 502
}

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 files a color logo with an attorney. members[] is included here for reference but is optional for LLC types — USPTO's form has no members section for LLCs.

{
  "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.