Create an application

POST /api/v1/applications

Saves a draft and returns review_url for the owner, who checks it and signs. Nothing goes to the attorney or the USPTO until they do. A draft can be partial: issues lists what's left. Drafts expire after 30 days.

In the MCP server this is create_application.

Example

curl -X POST https://api.joinopenfile.com/v1/applications \
  -H "content-type: application/json" \
  -d '{
  "mark": "Quillbrook",
  "kind": "name",
  "classes": [
    {
      "number": 4,
      "wording": "Candles; scented candles; candle wicks"
    }
  ],
  "owner": {
    "type": "llc",
    "name": "Quillbrook Candle Co. LLC",
    "state_of_organization": "Delaware",
    "street": "1 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "email": "owner@example.com"
  },
  "basis": "itu"
}'

Body

Name	Type	Required	Description
`mark`	string	No	The name, slogan or wording to protect, exactly as the person wants it.
`kind`	`name`, `slogan`, `logo`	No	What the mark is. A logo is filed as words first.
`description`	string	No	What's sold under the mark, in the person's words.
`website`	string	No	The brand's website.
`classes`	array of object	No	The classes to file in, 1 to 10.
`owner`	object	No	Who will own the mark. On an update, only the fields you send change.
`owner.type`	`individual`, `llc`, `corporation`, `partnership`	No	The owner's legal form.
`owner.name`	string	No	The owner's exact legal name.
`owner.citizenship`	string	No	Individual owners: citizenship.
`owner.state_of_organization`	string	No	Company owners: the state it was formed in.
`owner.street`	string	No	Street address where the owner lives or is based. Not a PO box.
`owner.city`	string	No	City.
`owner.state`	string	No	State.
`owner.zip`	string	No	5-digit ZIP code.
`owner.email`	string	No	Where we reach the owner about this application.
`basis`	`use`, `itu`	No	`use`: already selling under the mark. `itu`: planning to, with a real intent.
`first_use`	string	No	With `use`: first used anywhere, as `YYYY-MM` or `YYYY-MM-DD`.
`first_use_in_commerce`	string	No	With `use`: first sold across state lines, as `YYYY-MM` or `YYYY-MM-DD`.

Response

201

Name	Type	Required	Description
`id`	string	No	Application id.
`object`	`application`	No	Always `application`.
`status`	`draft`, `signed`, `expired`	No	`draft`: waiting for the owner. `signed`: the owner signed and it went to the attorney. `expired`: 30 days passed unsigned.
`ready`	boolean	No	True when nothing is missing and the owner can sign.
`issues`	array of object	No	What's missing, each with the field and what to ask.
`review_url`	string	No	Send this to the owner: it opens the application for them to check and sign. Contains the token.
`token`	string	No	Only on create. Keep it: reads and updates need it.
`application`	object	No	Every field is optional, so an application can be built up as the person answers. Send only what the person told you or confirmed.
`application.mark`	string	No	The name, slogan or wording to protect, exactly as the person wants it.
`application.kind`	`name`, `slogan`, `logo`	No	What the mark is. A logo is filed as words first.
`application.description`	string	No	What's sold under the mark, in the person's words.
`application.website`	string	No	The brand's website.
`application.classes`	array of object	No	The classes to file in, 1 to 10.
`application.owner`	object	No	Who will own the mark. On an update, only the fields you send change.
`application.owner.type`	`individual`, `llc`, `corporation`, `partnership`	No	The owner's legal form.
`application.owner.name`	string	No	The owner's exact legal name.
`application.owner.citizenship`	string	No	Individual owners: citizenship.
`application.owner.state_of_organization`	string	No	Company owners: the state it was formed in.
`application.owner.street`	string	No	Street address where the owner lives or is based. Not a PO box.
`application.owner.city`	string	No	City.
`application.owner.state`	string	No	State.
`application.owner.zip`	string	No	5-digit ZIP code.
`application.owner.email`	string	No	Where we reach the owner about this application.
`application.basis`	`use`, `itu`	No	`use`: already selling under the mark. `itu`: planning to, with a real intent.
`application.first_use`	string	No	With `use`: first used anywhere, as `YYYY-MM` or `YYYY-MM-DD`.
`application.first_use_in_commerce`	string	No	With `use`: first sold across state lines, as `YYYY-MM` or `YYYY-MM-DD`.
`quote`	object	No
`quote.object`	`quote`	No	Always `quote`.
`quote.currency`	string	No	Always `usd`.
`quote.classes`	integer	No	Classes priced.
`quote.lines`	array of object	No	Every fee, one line each.
`quote.total`	integer	No	Sum of `lines`, in dollars.
`checks`	array of object	No	Refusal grounds this mark may run into. Empty when none came up.
`filing`	object	No	Once signed: the filing, with its own `token`.
`filing.id`	string	No	Filing id.
`filing.object`	`filing`	No	Always `filing`.
`filing.status`	`received`, `changes`, `approved`, `filed`, `declined`	No	Where the filing is.
`filing.status_label`	string	No	The status in plain words.
`filing.note`	string	No	From the attorney, when the status is `changes` or `declined`.
`filing.mark`	string	No	The mark.
`filing.owner`	string	No	The owner.
`filing.basis`	`use`, `itu`	No	Filing basis.
`filing.classes`	array of object	No	The classes filed.
`filing.has_specimen`	boolean	No	True once a specimen is attached.
`filing.signed_by`	string	No	Who signed.
`filing.paid`	boolean	No	True once payment is recorded.
`filing.serial`	string	No	USPTO serial number, once filed.
`filing.filed_at`	string	No	When it was filed.
`filing.uspto_url`	string	No	The USPTO's record, once filed.
`filing.status_url`	string	No	The customer's status link. It contains the token.
`filing.created_at`	string	No	When it was signed.
`created_at`	string	No	When it was created.
`updated_at`	string	No	When it last changed.
`expires_at`	string	No	When an unsigned draft expires.

Errors

Status	When
`400`	Invalid input.
`429`	Too many requests.

The body is the error shape.

Next: Get an application