> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Trademarks

> Add trademarks with optional external docketing references

<Snippet file="portfolios/access.mdx" />

See [portfolio limits and references](/guides/portfolios) for current caps and
`external_ref` semantics.

## Request

Requires an `Idempotency-Key` header and exactly one of these request shapes,
with **1–100 entries per request**:

```json theme={null}
{ "trademark_ids": ["tm_01900000-0000-7000-8000-000000000001"] }
```

```json theme={null}
{
  "items": [
    {
      "trademark_id": "tm_01900000-0000-7000-8000-000000000001",
      "external_ref": "ACME-2024-001"
    }
  ]
}
```

Use real `tm_` IDs returned by Signa. Plain `trademark_ids` silently deduplicates
repeated IDs and creates new memberships without a reference. The `items` shape
rejects repeated trademark IDs or references with 400 `validation_error`.

## Response

Unknown trademark IDs are counted under `not_found`; existing memberships are
counted under `already_in_portfolio`. The result also includes `added`.

## External References

`external_ref` is your reference for this membership: optional, trimmed, 1–255
characters, case-sensitive, and unique within the portfolio. You can attach a
reference to an existing membership that has none. Once set, it is immutable:
remove the membership and re-add it to bind a different reference. Reusing a
reference for another mark, or changing an existing reference, returns
409 `external_ref_conflict` and rolls back the entire batch.

## Errors

Exceeding the organization's distinct managed-marks cap returns
409 `resource_quota_exceeded` with `quota_scope: "managed_marks"`; the entire batch
is rolled back. Adding an already-managed mark to another folder does not consume
another managed-mark slot. Concurrent updates can return retryable
503 `service_unavailable`; retry the same request with the same idempotency key.