File a trademark application (or record an externally-filed application)

Last updated Jun 14, 2026

Query Parameters

dry_runbooleanOptional

If true, simulate the mutation and return the would-be resource, any cascaded resources, and a fee estimate — without side effects. Available on every mutation.

Default false

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

modestringRequired

One of"file_via_matter""record_external"

markstringRequired

drawing_kindstringOptional

standard_character covers the literal text in any font/color/size; special_form covers a stylized mark or logo and requires a drawing_file_id upload.

One of"standard_character""special_form"

Default "standard_character"

drawing_file_idstringOptional

Required when drawing_kind is special_form. The uploaded image of the mark.

classesarray<object>Required

class_numberintegerRequired

identificationstringRequired

Goods/services description for the class. If pulled verbatim from the USPTO Acceptable Identification Manual, no custom-ID surcharge applies; custom text adds a surcharge per the current USPTO fee schedule.

identification_sourcestringOptional

Drives the surcharge calculation.

One of"acceptable_id_manual""custom"

jurisdictionstringRequired

One of"US"

basis_of_filingstringRequired

Section 1(a) actual_use or Section 1(b) intent_to_use.

One of"actual_use""intent_to_use"

first_use_datestring<date>Optional

Required when basis_of_filing is actual_use. Date of first use anywhere.

Format date

first_use_in_commerce_datestring<date>Optional

Required when basis_of_filing is actual_use. Date of first interstate use.

Format date

specimen_file_idstringOptional

Required when basis_of_filing: actual_use. Image showing the mark in actual use on the goods or services (label, packaging, screenshot, etc.).

serial_numberstringOptional

Required when mode is record_external. The USPTO-issued application serial number.

related_search_idstringOptional

Optional pointer to the TrademarkSearch that informed the filing.

claims_prior_registrationbooleanOptional

Set true if claiming priority under a prior US registration (Section 44(d) / 44(e)). Adds a surcharge.

Default false

Response Body

`application/json`

`application/problem+json`

Request

curl -X POST "https://api.mattermode.com/v1/entities/{id}/trademarks" \  -H "Content-Type: application/json" \  -d '{    "mode": "file_via_matter",    "mark": "string",    "classes": [      {        "class_number": 1,        "identification": "string"      }    ],    "jurisdiction": "US",    "basis_of_filing": "actual_use"  }'

const body = JSON.stringify({  "mode": "file_via_matter",  "mark": "string",  "classes": [    {      "class_number": 1,      "identification": "string"    }  ],  "jurisdiction": "US",  "basis_of_filing": "actual_use"})fetch("https://api.mattermode.com/v1/entities/{id}/trademarks", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

package mainimport (  "fmt"  "net/http"  "io/ioutil"  "strings")func main() {  url := "https://api.mattermode.com/v1/entities/{id}/trademarks"  body := strings.NewReader(`{    "mode": "file_via_matter",    "mark": "string",    "classes": [      {        "class_number": 1,        "identification": "string"      }    ],    "jurisdiction": "US",    "basis_of_filing": "actual_use"  }`)  req, _ := http.NewRequest("POST", url, body)  req.Header.Add("Content-Type", "application/json")  res, _ := http.DefaultClient.Do(req)  defer res.Body.Close()  body, _ := ioutil.ReadAll(res.Body)  fmt.Println(res)  fmt.Println(string(body))}

import requestsheaders = {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",}payload = {    "mode": "file_via_matter",    "mark": "example",    "classes": [        {            "class_number": 1,            "identification": "example"        }    ],    "jurisdiction": "US",    "basis_of_filing": "actual_use"}resp = requests.post(    "https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/trademarks",    headers=headers,    json=payload,)resp.raise_for_status()print(resp.json())

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;import java.net.http.HttpRequest.BodyPublishers;var body = BodyPublishers.ofString("""{  "mode": "file_via_matter",  "mark": "string",  "classes": [    {      "class_number": 1,      "identification": "string"    }  ],  "jurisdiction": "US",  "basis_of_filing": "actual_use"}""");HttpClient client = HttpClient.newBuilder()  .connectTimeout(Duration.ofSeconds(10))  .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()  .uri(URI.create("https://api.mattermode.com/v1/entities/{id}/trademarks"))  .header("Content-Type", "application/json")  .POST(body)  .build();try {  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());  System.out.println("Status code: " + response.statusCode());  System.out.println("Response body: " + response.body());} catch (Exception e) {  e.printStackTrace();}

using System;using System.Net.Http;using System.Text;var body = new StringContent("""{  "mode": "file_via_matter",  "mark": "string",  "classes": [    {      "class_number": 1,      "identification": "string"    }  ],  "jurisdiction": "US",  "basis_of_filing": "actual_use"}""", Encoding.UTF8, "application/json");var client = new HttpClient();var response = await client.PostAsync("https://api.mattermode.com/v1/entities/{id}/trademarks", body);var responseBody = await response.Content.ReadAsStringAsync();

curl --request POST 'https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/trademarks' \  --header 'Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc' \  --header 'Matter-Version: 2026-06-10' \  --header 'Idempotency-Key: ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b' \  --header 'Content-Type: application/json' \  --data '{  "mode": "file_via_matter",  "mark": "example",  "classes": [    {      "class_number": 1,      "identification": "example"    }  ],  "jurisdiction": "US",  "basis_of_filing": "actual_use"}'

const response = await fetch("https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/trademarks", {  method: "POST",  headers: {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",    "Content-Type": "application/json",  },  body: JSON.stringify({    "mode": "file_via_matter",    "mark": "example",    "classes": [      {        "class_number": 1,        "identification": "example"      }    ],    "jurisdiction": "US",    "basis_of_filing": "actual_use"  }),});if (!response.ok) {  throw new Error(`Matter API ${response.status}: ${await response.text()}`);}const data = await response.json();console.log(data);

Response

application/json

{
  "object": "trademark",
  "id": "string",
  "entity_id": "string",
  "mark": "string",
  "drawing_kind": "standard_character",
  "drawing_file_id": "string",
  "classes": [
    {
      "class_number": 1,
      "identification": "string",
      "identification_source": "acceptable_id_manual"
    }
  ],
  "jurisdiction": "US",
  "basis_of_filing": "actual_use",
  "status": "pending_filing",
  "first_use_date": "2019-08-24",
  "first_use_in_commerce_date": "2019-08-24",
  "specimen_file_id": "string",
  "serial_number": "string",
  "registration_number": "string",
  "filed_at": "2019-08-24T14:15:22Z",
  "published_at": "2019-08-24T14:15:22Z",
  "notice_of_allowance_at": "2019-08-24T14:15:22Z",
  "registered_at": "2019-08-24T14:15:22Z",
  "related_search_id": "string",
  "application_attributes": {
    "has_custom_identification": true,
    "additional_classes_count": 0,
    "claims_prior_registration": true,
    "estimated_fee_usd_cents": 0
  },
  "statement_of_use": {
    "filed_at": "2019-08-24T14:15:22Z",
    "first_use_date": "2019-08-24",
    "first_use_in_commerce_date": "2019-08-24",
    "specimen_file_id": "string",
    "extensions_filed": 0
  },
  "maintenance_obligations": [
    {
      "declaration_kind": "section_8",
      "window_start": "2019-08-24",
      "window_end": "2019-08-24",
      "filed_at": "2019-08-24T14:15:22Z",
      "status": "upcoming"
    }
  ],
  "related_document_id": "string",
  "partner_filing_id": "string"
}

{
  "type": "https://mattermode.com/docs/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "Request body could not be parsed as JSON.",
  "doc_url": "https://mattermode.com/docs/guides/errors#invalid_request",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/authentication_required",
  "title": "Authentication required",
  "status": 401,
  "code": "authentication_required",
  "detail": "No bearer token was supplied. Pass `Authorization: Bearer sk_live_...` on every request.",
  "doc_url": "https://mattermode.com/docs/guides/errors#authentication_required",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/invalid_state_transition",
  "title": "Invalid state transition",
  "status": 409,
  "code": "invalid_state_transition",
  "detail": "Entity ent_Nq3KcAbc is in state `dissolved`; `dissolve` is not a valid transition.",
  "doc_url": "https://mattermode.com/docs/guides/errors#invalid_state_transition",
  "request_id": "req_Qw9xYz8A",
  "current_state": "dissolved",
  "attempted_transition": "dissolve",
  "allowed_transitions": []
}

{
  "type": "https://mattermode.com/docs/errors/dissolution_prerequisites_missing",
  "title": "Dissolution prerequisites missing",
  "status": 409,
  "code": "dissolution_prerequisites_missing",
  "detail": "Voluntary dissolution requires `board_resolution_id` and `stockholder_consent_id`, or `auto_generate_resolutions: true`.",
  "doc_url": "https://mattermode.com/docs/guides/errors#dissolution_prerequisites_missing",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/valuation_stale",
  "title": "409A valuation stale",
  "status": 409,
  "code": "valuation_stale",
  "detail": "Active 409A val_AbCd1234 is older than 12 months or superseded by a material event. Issuing ISOs at the prior strike risks IRC §409A violation. Refresh via POST /entities/{id}/valuations/{id}/refresh_request.",
  "doc_url": "https://mattermode.com/docs/guides/errors#valuation_stale",
  "request_id": "req_Qw9xYz8A"
}

Create a trademark.

Create a Trademark (tmk_*) representing a U.S. trademark application. Two modes:

- mode: file_via_matter — Matter's USPTO-filing partner submits the application. Returns a Trademark in pending_filing; advances to filed once USPTO assigns a serial number (via webhook). - mode: record_external — record an application that was filed off-platform (outside counsel, Trademarkia, LegalZoom IP). Caller supplies serial_number. Returns a Trademark in filed.

## Basis of filing

- `actual_use` (Section 1(a)) — the mark is already in use in interstate commerce. Requires first_use_date (anywhere) and first_use_in_commerce_date (interstate), plus a specimen showing the mark on the actual goods/services. - `intent_to_use` (Section 1(b)) — the mark is not yet in use but the applicant has a bona fide intention to use it. No specimen at filing; a Statement of Use (with specimen and dates) must be filed within 6 months of the Notice of Allowance to register the mark. See /trademarks/{id}/statement_of_use.

## Application attributes (drive surcharges)

Per USPTO's January 2025 fee structure, a base application fee applies plus surcharges for: custom goods/services descriptions (vs the pre-approved Acceptable Identification Manual), each additional class beyond the first, prior-registration claims, and lengthy goods/services descriptions. Matter computes the expected fee from application_attributes and surfaces it in the response so callers can confirm before authorizing.

## Cascade

- Maintenance-window obligations roll onto the entity's compliance calendar automatically: Section 8 Declaration of Use due in the fifth-to-sixth year post-registration; Combined Section 8&9 Declaration + Renewal due every ten years thereafter; optional Section 15 incontestability declaration eligible after five continuous years of post-registration use. - A Document of type trademark_application is generated and attached to the Trademark for record-keeping.

?dry_run=true returns the proposed application package and the computed fee without filing.

Last updated Jun 14, 2026

Query Parameters

dry_runbooleanOptional

If true, simulate the mutation and return the would-be resource, any cascaded resources, and a fee estimate — without side effects. Available on every mutation.

Default false

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

modestringRequired

One of"file_via_matter""record_external"

markstringRequired

drawing_kindstringOptional

standard_character covers the literal text in any font/color/size; special_form covers a stylized mark or logo and requires a drawing_file_id upload.

One of"standard_character""special_form"

Default "standard_character"

drawing_file_idstringOptional

Required when drawing_kind is special_form. The uploaded image of the mark.

classesarray<object>Required

class_numberintegerRequired

identificationstringRequired

identification_sourcestringOptional

Drives the surcharge calculation.

One of"acceptable_id_manual""custom"

jurisdictionstringRequired

One of"US"

basis_of_filingstringRequired

Section 1(a) actual_use or Section 1(b) intent_to_use.

One of"actual_use""intent_to_use"

first_use_datestring<date>Optional

Required when basis_of_filing is actual_use. Date of first use anywhere.

Format date

first_use_in_commerce_datestring<date>Optional

Required when basis_of_filing is actual_use. Date of first interstate use.

Format date

specimen_file_idstringOptional

Required when basis_of_filing: actual_use. Image showing the mark in actual use on the goods or services (label, packaging, screenshot, etc.).

serial_numberstringOptional

Required when mode is record_external. The USPTO-issued application serial number.

related_search_idstringOptional

Optional pointer to the TrademarkSearch that informed the filing.

claims_prior_registrationbooleanOptional

Set true if claiming priority under a prior US registration (Section 44(d) / 44(e)). Adds a surcharge.

Default false

Response Body

`application/json`

`application/problem+json`

Request

curl -X POST "https://api.mattermode.com/v1/entities/{id}/trademarks" \  -H "Content-Type: application/json" \  -d '{    "mode": "file_via_matter",    "mark": "string",    "classes": [      {        "class_number": 1,        "identification": "string"      }    ],    "jurisdiction": "US",    "basis_of_filing": "actual_use"  }'

const body = JSON.stringify({  "mode": "file_via_matter",  "mark": "string",  "classes": [    {      "class_number": 1,      "identification": "string"    }  ],  "jurisdiction": "US",  "basis_of_filing": "actual_use"})fetch("https://api.mattermode.com/v1/entities/{id}/trademarks", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

package mainimport (  "fmt"  "net/http"  "io/ioutil"  "strings")func main() {  url := "https://api.mattermode.com/v1/entities/{id}/trademarks"  body := strings.NewReader(`{    "mode": "file_via_matter",    "mark": "string",    "classes": [      {        "class_number": 1,        "identification": "string"      }    ],    "jurisdiction": "US",    "basis_of_filing": "actual_use"  }`)  req, _ := http.NewRequest("POST", url, body)  req.Header.Add("Content-Type", "application/json")  res, _ := http.DefaultClient.Do(req)  defer res.Body.Close()  body, _ := ioutil.ReadAll(res.Body)  fmt.Println(res)  fmt.Println(string(body))}

import requestsheaders = {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",}payload = {    "mode": "file_via_matter",    "mark": "example",    "classes": [        {            "class_number": 1,            "identification": "example"        }    ],    "jurisdiction": "US",    "basis_of_filing": "actual_use"}resp = requests.post(    "https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/trademarks",    headers=headers,    json=payload,)resp.raise_for_status()print(resp.json())

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;import java.net.http.HttpRequest.BodyPublishers;var body = BodyPublishers.ofString("""{  "mode": "file_via_matter",  "mark": "string",  "classes": [    {      "class_number": 1,      "identification": "string"    }  ],  "jurisdiction": "US",  "basis_of_filing": "actual_use"}""");HttpClient client = HttpClient.newBuilder()  .connectTimeout(Duration.ofSeconds(10))  .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()  .uri(URI.create("https://api.mattermode.com/v1/entities/{id}/trademarks"))  .header("Content-Type", "application/json")  .POST(body)  .build();try {  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());  System.out.println("Status code: " + response.statusCode());  System.out.println("Response body: " + response.body());} catch (Exception e) {  e.printStackTrace();}

using System;using System.Net.Http;using System.Text;var body = new StringContent("""{  "mode": "file_via_matter",  "mark": "string",  "classes": [    {      "class_number": 1,      "identification": "string"    }  ],  "jurisdiction": "US",  "basis_of_filing": "actual_use"}""", Encoding.UTF8, "application/json");var client = new HttpClient();var response = await client.PostAsync("https://api.mattermode.com/v1/entities/{id}/trademarks", body);var responseBody = await response.Content.ReadAsStringAsync();

curl --request POST 'https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/trademarks' \  --header 'Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc' \  --header 'Matter-Version: 2026-06-10' \  --header 'Idempotency-Key: ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b' \  --header 'Content-Type: application/json' \  --data '{  "mode": "file_via_matter",  "mark": "example",  "classes": [    {      "class_number": 1,      "identification": "example"    }  ],  "jurisdiction": "US",  "basis_of_filing": "actual_use"}'

const response = await fetch("https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/trademarks", {  method: "POST",  headers: {    "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc",    "Matter-Version": "2026-06-10",    "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",    "Content-Type": "application/json",  },  body: JSON.stringify({    "mode": "file_via_matter",    "mark": "example",    "classes": [      {        "class_number": 1,        "identification": "example"      }    ],    "jurisdiction": "US",    "basis_of_filing": "actual_use"  }),});if (!response.ok) {  throw new Error(`Matter API ${response.status}: ${await response.text()}`);}const data = await response.json();console.log(data);

Response

application/json

{
  "object": "trademark",
  "id": "string",
  "entity_id": "string",
  "mark": "string",
  "drawing_kind": "standard_character",
  "drawing_file_id": "string",
  "classes": [
    {
      "class_number": 1,
      "identification": "string",
      "identification_source": "acceptable_id_manual"
    }
  ],
  "jurisdiction": "US",
  "basis_of_filing": "actual_use",
  "status": "pending_filing",
  "first_use_date": "2019-08-24",
  "first_use_in_commerce_date": "2019-08-24",
  "specimen_file_id": "string",
  "serial_number": "string",
  "registration_number": "string",
  "filed_at": "2019-08-24T14:15:22Z",
  "published_at": "2019-08-24T14:15:22Z",
  "notice_of_allowance_at": "2019-08-24T14:15:22Z",
  "registered_at": "2019-08-24T14:15:22Z",
  "related_search_id": "string",
  "application_attributes": {
    "has_custom_identification": true,
    "additional_classes_count": 0,
    "claims_prior_registration": true,
    "estimated_fee_usd_cents": 0
  },
  "statement_of_use": {
    "filed_at": "2019-08-24T14:15:22Z",
    "first_use_date": "2019-08-24",
    "first_use_in_commerce_date": "2019-08-24",
    "specimen_file_id": "string",
    "extensions_filed": 0
  },
  "maintenance_obligations": [
    {
      "declaration_kind": "section_8",
      "window_start": "2019-08-24",
      "window_end": "2019-08-24",
      "filed_at": "2019-08-24T14:15:22Z",
      "status": "upcoming"
    }
  ],
  "related_document_id": "string",
  "partner_filing_id": "string"
}

{
  "type": "https://mattermode.com/docs/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "Request body could not be parsed as JSON.",
  "doc_url": "https://mattermode.com/docs/guides/errors#invalid_request",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/authentication_required",
  "title": "Authentication required",
  "status": 401,
  "code": "authentication_required",
  "detail": "No bearer token was supplied. Pass `Authorization: Bearer sk_live_...` on every request.",
  "doc_url": "https://mattermode.com/docs/guides/errors#authentication_required",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/invalid_state_transition",
  "title": "Invalid state transition",
  "status": 409,
  "code": "invalid_state_transition",
  "detail": "Entity ent_Nq3KcAbc is in state `dissolved`; `dissolve` is not a valid transition.",
  "doc_url": "https://mattermode.com/docs/guides/errors#invalid_state_transition",
  "request_id": "req_Qw9xYz8A",
  "current_state": "dissolved",
  "attempted_transition": "dissolve",
  "allowed_transitions": []
}

{
  "type": "https://mattermode.com/docs/errors/dissolution_prerequisites_missing",
  "title": "Dissolution prerequisites missing",
  "status": 409,
  "code": "dissolution_prerequisites_missing",
  "detail": "Voluntary dissolution requires `board_resolution_id` and `stockholder_consent_id`, or `auto_generate_resolutions: true`.",
  "doc_url": "https://mattermode.com/docs/guides/errors#dissolution_prerequisites_missing",
  "request_id": "req_Qw9xYz8A"
}

{
  "type": "https://mattermode.com/docs/errors/valuation_stale",
  "title": "409A valuation stale",
  "status": 409,
  "code": "valuation_stale",
  "detail": "Active 409A val_AbCd1234 is older than 12 months or superseded by a material event. Issuing ISOs at the prior strike risks IRC §409A violation. Refresh via POST /entities/{id}/valuations/{id}/refresh_request.",
  "doc_url": "https://mattermode.com/docs/guides/errors#valuation_stale",
  "request_id": "req_Qw9xYz8A"
}

Create a trademark.

Query Parameters

Request Body

Response Body

202application/json

400application/problem+json

401application/problem+json

409application/problem+json

Create a trademark.

Query Parameters

Request Body

Response Body

202application/json

400application/problem+json

401application/problem+json

409application/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`