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

# Metadata

> Enhance your Posta API objects with custom metadata

Metadata allows you to attach custom key-value pairs to Posta API objects, enabling better organization, filtering, and integration with your internal systems.

## Using metadata

When creating or updating Posta objects, you can include key-value pairs of custom metadata. This feature is particularly useful for:

* Categorizing objects
* Tracking internal identifiers
* Adding custom flags
* Linking to external systems

### Metadata structure

Metadata in the Posta API is structured as an array of key-value pairs:

```json theme={null}
"metadata": [
  {
    "key": "<string>",
    "value": "<string>"
  },
  {
    "key": "<string>",
    "value": "<string>"
  }
]
```

### Metadata examples

Here are some examples of how you might use metadata:

```json theme={null}
"metadata": [
  {
    "key": "campaign",
    "value": "winter2024"
  },
  {
    "key": "salesforceId",
    "value": "0063i00000JrMehAAF"
  },
  {
    "key": "costCenter",
    "value": "servicing"
  },
  {
    "key": "highPriority",
    "value": ""
  },
  {
    "key": "compliance",
    "value": "PHI"
  }
]
```

<Note>
  You can specify a key without a value, as shown in the "highPriority" example above. This can be useful for boolean-like flags where the presence of the key indicates `true`.
</Note>

## Metadata limitations

* You can attach up to 20 metadata key-value pairs to an object.
* Each metadata key must be less than 64 characters long.
* Metadata values must be less than 512 characters.
* Metadata does not support nested objects.
* Empty string values are allowed and can be useful for flag-like metadata.

## Best practices

1. Use consistent key names across your integration for easier querying and organization.
2. Consider prefixing keys to avoid conflicts (e.g., `internalId` instead of `id`).
3. Use metadata for filtering and organization, not for storing sensitive data.
4. Leverage empty values for boolean-like flags.
5. Document your metadata schema within your organization to ensure consistent usage.
6. Keep metadata concise and relevant to maintain performance.

<Info>
  Metadata is searchable and can be used to organize and filter your Posta objects efficiently. However, it's not intended for storing sensitive information.
</Info>

## Working with metadata

While the specific endpoints for working with metadata may vary depending on the object type, here are general principles for interacting with metadata:

### Adding metadata

When creating or updating an object, include the metadata array in your request body:

<Accordion title="Adding metadata example">
  ```json theme={null}
  POST /letters
  {
    "content": { ... },
    "metadata": [
      {
        "key": "orderId",
        "value": "ORD-12345"
      },
      {
        "key": "rush",
        "value": ""
      }
    ]
  }
  ```
</Accordion>

### Retrieving metadata

When you fetch an object, its metadata will be included in the response.

<Accordion title="Retrieving metadata example">
  ```json theme={null}
  GET /letters/{letterId}
  {
    "id": "ltr_123abc",
    "content": { ... },
    "metadata": [
      {
        "key": "orderId",
        "value": "ORD-12345"
      },
      {
        "key": "rush",
        "value": ""
      }
    ]
  }
  ```
</Accordion>

### Updating metadata

You can update metadata on existing objects using the update endpoints. This will replace the entire metadata array.

<Accordion title="Updating metadata example">
  ```json theme={null}
  PUT /letters/{letterId}
  {
    "metadata": [
      {
        "key": "orderId",
        "value": "ORD-12345"
      },
      {
        "key": "status",
        "value": "processed"
      }
    ]
  }
  ```
</Accordion>

### Filtering with metadata

Many list endpoints support filtering objects based on metadata. See each endpoint's documentation for details.

<Tip>
  Remember to refer to the specific API endpoint documentation for detailed information on how to interact with metadata for each object type.
</Tip>

<Warning>
  Avoid using metadata for data that changes frequently, as this can impact performance. For frequently changing data, consider using a dedicated field or a separate system.
</Warning>