USPTO Filing Bot

How Callbacks Work

The USPTO Filing Bot sends webhook notifications (HTTP POST) to your registered callback URLs whenever an applicant's status changes or a filing progresses. This allows your system to react in real-time without polling.

Key Concepts

• CompanyCallbackUrl — each company (tenant) registers one or more callback URLs. Every event is fan-out delivered to all active URLs for that company.
• Best-effort delivery — callback failures never block the bot. If a delivery fails, it is retried with linear backoff.
• Outbox pattern — events are first written to a CallbackDelivery table, then dispatched asynchronously by a background interval (every 10 seconds).
• Idempotency — each payload includes a correlationId (UUID). Use it to de-duplicate on your side.

Delivery Flow

Lifecycle & Callback Flow

Every callback maps to a specific moment in the applicant's lifecycle. This diagram shows when each event fires:

Payload Structure

All callbacks share a stable payload envelope. Fields are only added, never removed (backward-compatible).

Envelope

{
  "event":         "APPLICANT_STATUS_CHANGED",
  "eventId":       2,
  "occurredAt":    "2026-06-04T15:30:00.000Z",
  "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "applicant":     { ... },
  "application":   { ... },       // only for filing-scoped events
  "transition":    { ... },       // only when a status transition occurred
  "video":         { ... },       // only when a bot recording exists
  "error":         { ... }        // only on failure events
}

Envelope Fields

applicant Object

Included in every callback. Represents the applicant's state at the moment the event fired.

Example applicant Object

{
  "id": 42,
  "customerId": 1001,
  "companyId": 5,
  "firstName": "Mike",
  "lastName": "Jacob",
  "emailAddress": "[email protected]",
  "usptoAccountEmail": "[email protected]",
  "usptoAccountPassword": "xY9!kP2m@LqR7n",
  "mfaSecret": "JBSWY3DPEHPK3PXP",
  "applicantLifeCycleStatusId": 9,
  "applicantLifeCycleStatus": "Account Created",
  "usptoAccountEmailStatusId": 2
}

application Object

Only present for filing-scoped events: FILING_STATUS_CHANGED, SUBMISSION_COMPLETED, SUBMISSION_FAILED.

transition Object

Present when an event represents a status change (applicant lifecycle or filing status).

video Object

Present when a bot video recording is associated with this event's phase.

error Object

Present on failure events.

EMAIL_PROVISIONED

EVENT ID: 10   V1 API

Fired immediately after the third-party email provider successfully creates the USPTO mailbox. This is the first callback you receive for a new applicant.

When it fires

• POST /api/v1/applicants/create-applicant → email provisioning succeeds
• Applicant lifecycle transitions from PENDING (1) to EMAIL_CREATED (2)

Key payload fields at this point

• applicant.usptoAccountEmail — the newly created mailbox address
• applicant.usptoAccountPassword — the generated password
• applicant.mfaSecret — null (MFA not enrolled yet)
• applicant.applicantLifeCycleStatusId — 2 (EMAIL_CREATED)

Example payload

{
  "event": "EMAIL_PROVISIONED",
  "eventId": 10,
  "occurredAt": "2026-06-04T15:00:01.000Z",
  "correlationId": "c9d1e2f3-a4b5-6789-cdef-012345678901",
  "applicant": {
    "id": 42,
    "customerId": 1001,
    "companyId": 5,
    "firstName": "Mike",
    "lastName": "Jacob",
    "emailAddress": "[email protected]",
    "usptoAccountEmail": "[email protected]",
    "usptoAccountPassword": "xY9!kP2m@LqR7n",
    "mfaSecret": null,
    "applicantLifeCycleStatusId": 2,
    "applicantLifeCycleStatus": "Email Created",
    "usptoAccountEmailStatusId": 2
  }
}

APPLICANT_STATUS_CHANGED

EVENT ID: 2   PHASE 1 PHASE 2

The universal lifecycle event. Fired on every applicant lifecycle status transition performed by the bot. This is the most frequent callback — you can build a complete audit trail from this event alone.

When it fires

Every call to the bot's internal setLifecycleStatus() function fires this event. That includes all of these transitions:

Example payload

{
  "event": "APPLICANT_STATUS_CHANGED",
  "eventId": 2,
  "occurredAt": "2026-06-04T15:05:30.000Z",
  "correlationId": "d1e2f3a4-b5c6-7890-abcd-ef0123456789",
  "applicant": {
    "id": 42,
    "customerId": 1001,
    "companyId": 5,
    "firstName": "Mike",
    "lastName": "Jacob",
    "emailAddress": "[email protected]",
    "usptoAccountEmail": "[email protected]",
    "usptoAccountPassword": "xY9!kP2m@LqR7n",
    "mfaSecret": null,
    "applicantLifeCycleStatusId": 4,
    "applicantLifeCycleStatus": "Form Submitted",
    "usptoAccountEmailStatusId": 2
  },
  "transition": {
    "from": 3,
    "to": 4,
    "fromTitle": "Form Filling",
    "toTitle": "Form Submitted"
  }
}

ACCOUNT_FAILED

EVENT ID: 7   V1 API PHASE 1

Fired when account creation fails. This is a terminal failure — the applicant cannot proceed further without manual intervention.

When it fires

• Email provisioning failure — POST /create-applicant → third-party email provider returns error. Lifecycle remains PENDING (1).
• Bot automation failure — any unrecoverable error during Phase 1 (form fill, captcha timeout, email verification timeout, etc.). Lifecycle transitions to ACCOUNT_FAILED (10).

Example payload (email provisioning failure)

{
  "event": "ACCOUNT_FAILED",
  "eventId": 7,
  "occurredAt": "2026-06-04T15:00:02.000Z",
  "correlationId": "e2f3a4b5-c6d7-8901-bcde-f01234567890",
  "applicant": {
    "id": 43,
    "customerId": 1002,
    "companyId": 5,
    "firstName": "Jane",
    "lastName": "Smith",
    "emailAddress": "[email protected]",
    "usptoAccountEmail": null,
    "usptoAccountPassword": "aB3!mN8x@QwR5z",
    "mfaSecret": null,
    "applicantLifeCycleStatusId": 1,
    "applicantLifeCycleStatus": "Pending",
    "usptoAccountEmailStatusId": 4
  },
  "error": {
    "message": "Email provisioning failed: Mailbox creation limit exceeded"
  }
}

Example payload (bot automation failure)

{
  "event": "ACCOUNT_FAILED",
  "eventId": 7,
  "occurredAt": "2026-06-04T15:12:45.000Z",
  "correlationId": "f3a4b5c6-d7e8-9012-cdef-012345678901",
  "applicant": {
    "id": 42,
    ...
    "applicantLifeCycleStatusId": 10,
    "applicantLifeCycleStatus": "Account Failed",
    "usptoAccountEmailStatusId": 2
  },
  "error": {
    "message": "Captcha solve timeout — extension did not solve within 120 seconds"
  },
  "video": {
    "type": "Signup",
    "typeId": 1,
    "path": "videos/signup_applicant_42_1717513965000.mp4",
    "durationSeconds": 125.4,
    "recordedAt": "2026-06-04T15:10:00.000Z"
  }
}

IDME_VERIFIED

EVENT ID: 8   PHASE 2

Fired when the bot confirms that the applicant has completed ID.me identity verification on USPTO. This is a critical milestone — the applicant is now eligible for trademark filing.

When it fires

• Bot signs into Trademark Center, navigates to /tm/verify-identity
• "ID verification options" text is NOT present → applicant is verified
• Lifecycle transitions from ACCOUNT_CREATED (9) to IDME_VERIFIED (11)

Also fires alongside: APPLICANT_STATUS_CHANGED (transition 9 → 11)

Example payload

{
  "event": "IDME_VERIFIED",
  "eventId": 8,
  "occurredAt": "2026-06-05T10:30:00.000Z",
  "correlationId": "a4b5c6d7-e8f9-0123-abcd-ef4567890123",
  "applicant": {
    "id": 42,
    "customerId": 1001,
    "companyId": 5,
    "firstName": "Mike",
    "lastName": "Jacob",
    "emailAddress": "[email protected]",
    "usptoAccountEmail": "[email protected]",
    "usptoAccountPassword": "xY9!kP2m@LqR7n",
    "mfaSecret": "JBSWY3DPEHPK3PXP",
    "applicantLifeCycleStatusId": 11,
    "applicantLifeCycleStatus": "IDME Verified",
    "usptoAccountEmailStatusId": 2
  },
  "video": {
    "type": "USPTO Verification",
    "typeId": 2,
    "path": "videos/idme_applicant_42_1717578600000.mp4",
    "durationSeconds": 45.2,
    "recordedAt": "2026-06-05T10:29:15.000Z"
  }
}

IDME_VERIFICATION_FAILED

EVENT ID: 9   PHASE 2

Fired when an applicant exceeds the maximum waiting time for ID.me verification. This is a terminal failure — the applicant will not be re-processed.

When it fires

• Applicant has been in ACCOUNT_CREATED (9) for longer than the configured wait limit (default: 48 hours, configurable via IDME_WAIT_LIMIT_MS environment variable)
• Lifecycle transitions to IDME_VERIFICATION_FAILED_WAITING_LIMIT_EXCEED (12)

Also fires alongside: APPLICANT_STATUS_CHANGED (transition 9 → 12)

Example payload

{
  "event": "IDME_VERIFICATION_FAILED",
  "eventId": 9,
  "occurredAt": "2026-06-06T15:00:00.000Z",
  "correlationId": "b5c6d7e8-f9a0-1234-bcde-f56789012345",
  "applicant": {
    "id": 42,
    ...
    "applicantLifeCycleStatusId": 12,
    "applicantLifeCycleStatus": "Idme Verification Failed Waiting Limit Exceed",
    "usptoAccountEmailStatusId": 2
  },
  "video": {
    "type": "USPTO Verification",
    "typeId": 2,
    "path": "videos/idme_applicant_42_1717686000000.mp4",
    "durationSeconds": 30.1,
    "recordedAt": "2026-06-06T14:59:30.000Z"
  }
}

FILING_STATUS_CHANGED

EVENT ID: 3   PHASE 3

Fired on every filing status transition. Includes the application object and a filing-status transition.

When it fires

Example payload

{
  "event": "FILING_STATUS_CHANGED",
  "eventId": 3,
  "occurredAt": "2026-06-06T16:00:00.000Z",
  "correlationId": "c6d7e8f9-a0b1-2345-cdef-678901234567",
  "applicant": {
    "id": 42,
    ...
    "applicantLifeCycleStatusId": 11,
    "applicantLifeCycleStatus": "IDME Verified"
  },
  "application": {
    "id": 101,
    "applicantId": 42,
    "filingStatusId": 3,
    "filingStatus": "Done"
  },
  "transition": {
    "from": 2,
    "to": 3,
    "fromTitle": "Under Process",
    "toTitle": "Done"
  },
  "video": {
    "type": "Filing",
    "typeId": 3,
    "path": "videos/filing_applicant_42_1717689600000.mp4",
    "durationSeconds": 340.5,
    "recordedAt": "2026-06-06T15:54:20.000Z"
  }
}

SUBMISSION_COMPLETED

EVENT ID: 5   PHASE 3

Fired when a trademark filing is saved as a draft on USPTO successfully. This is the final success event in the entire flow.

When it fires

• Filing wizard completed all pages without error
• Filing status transitions to DONE (3)
• Fires alongside: FILING_STATUS_CHANGED (transition UNDER_PROCESS → DONE)

Example payload

{
  "event": "SUBMISSION_COMPLETED",
  "eventId": 5,
  "occurredAt": "2026-06-06T16:00:01.000Z",
  "correlationId": "d7e8f9a0-b1c2-3456-defg-789012345678",
  "applicant": { ... },
  "application": {
    "id": 101,
    "applicantId": 42,
    "filingStatusId": 3,
    "filingStatus": "Done"
  },
  "video": {
    "type": "Filing",
    "typeId": 3,
    "path": "videos/filing_applicant_42_1717689600000.mp4",
    "durationSeconds": 340.5,
    "recordedAt": "2026-06-06T15:54:20.000Z"
  }
}

SUBMISSION_FAILED

EVENT ID: 6   PHASE 3

Fired when a trademark filing fails at any point during the wizard automation.

When it fires

• Filing wizard encounters an unrecoverable error (validation, page not found, timeout, etc.)
• Filing status transitions to ERROR (4)
• Fires alongside: FILING_STATUS_CHANGED (transition UNDER_PROCESS → ERROR)

Example payload

{
  "event": "SUBMISSION_FAILED",
  "eventId": 6,
  "occurredAt": "2026-06-06T16:05:00.000Z",
  "correlationId": "e8f9a0b1-c2d3-4567-efgh-890123456789",
  "applicant": { ... },
  "application": {
    "id": 102,
    "applicantId": 42,
    "filingStatusId": 4,
    "filingStatus": "Error"
  },
  "error": {
    "message": "Failed at step 'goods-services': Validation error — class 045 not found in ID Manual"
  },
  "video": {
    "type": "Filing",
    "typeId": 3,
    "path": "videos/filing_applicant_42_1717689900000.mp4",
    "durationSeconds": 180.2,
    "recordedAt": "2026-06-06T16:02:00.000Z"
  }
}

Complete Event Matrix

This table shows every callback event, when it fires, what triggers it, and what extra payload fields are included.

Lookup Tables

Applicant Lifecycle Statuses

Filing Statuses

Callback Event IDs

Email Provisioning Statuses

Bot Video Types

Delivery & Retry Logic

Delivery Status Lifecycle

Delivery Status Reference

Configuration (per CompanyCallbackUrl)

Security Considerations

Idempotency

Every payload includes a correlationId (UUID v4). If your server receives the same correlationId twice (e.g. due to retry), treat the second delivery as a no-op. Store processed correlationIds for at least the retry window duration.

Response Contract

• Return 2xx to acknowledge successful receipt. The response body is ignored.
• Return non-2xx (or let the request timeout) to trigger a retry.
• Process the payload asynchronously if your logic is slow — respond 200 immediately, then process in background.