Add a specimen

POST /api/v1/filings/{id}/specimen

Adds or replaces the photo or screenshot showing the mark in use, until the attorney has filed. If the attorney asked for a change, this sends the filing back for review.

Needs the token for this application or filing.

In the MCP server this is add_specimen.

Example

curl -X POST https://api.joinopenfile.com/v1/filings/$ID/specimen \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{
  "content_base64": "iVBORw0KGgo...",
  "content_type": "image/png",
  "name": "label.png"
}'

Parameters

Name	Type	Required	Description
`id`	string	Yes	Filing id.

Body

Name	Type	Required	Description
`content_base64`	string	Yes	The image, base64 encoded. 3 MB at most.
`content_type`	`image/png`, `image/jpeg`, `image/webp`	Yes	The image type.
`name`	string	No	The file name.

Response

200

Name	Type	Required	Description
`id`	string	No	Filing id.
`object`	`filing`	No	Always `filing`.
`status`	`received`, `changes`, `approved`, `filed`, `declined`	No	Where the filing is.
`status_label`	string	No	The status in plain words.
`note`	string	No	From the attorney, when the status is `changes` or `declined`.
`mark`	string	No	The mark.
`owner`	string	No	The owner.
`basis`	`use`, `itu`	No	Filing basis.
`classes`	array of object	No	The classes filed.
`has_specimen`	boolean	No	True once a specimen is attached.
`signed_by`	string	No	Who signed.
`paid`	boolean	No	True once payment is recorded.
`serial`	string	No	USPTO serial number, once filed.
`filed_at`	string	No	When it was filed.
`uspto_url`	string	No	The USPTO's record, once filed.
`status_url`	string	No	The customer's status link. It contains the token.
`created_at`	string	No	When it was signed.

Errors

Status	When
`400`	Invalid input.
`404`	Not found, or the token is wrong.
`409`	Not allowed in this state.
`429`	Too many requests.

The body is the error shape.