# Add a specimen

Source: https://joinopenfile.com/docs/api/add-specimen
Index: https://joinopenfile.com/llms.txt

`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](https://joinopenfile.com/docs/authentication.md) for this application or filing.

In the MCP server this is `add_specimen`.

## Example

```bash
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](https://joinopenfile.com/docs/errors.md).