---
title: "Storing custom data in PDF annotations"
canonical_url: "https://www.nutrient.io/guides/ios/annotations/custom-data-in-annotations/"
md_url: "https://www.nutrient.io/guides/ios/annotations/custom-data-in-annotations.md"
last_updated: "2026-05-23T00:08:18.099Z"
description: "Learn how to store and manage custom data in PDF annotations using the iOS SDK, enhancing your document workflows with low-code solutions."
---

# Store custom data in iOS PDF annotations

When adding an annotation to a document, Nutrient allows storing of additional data that you can specify for each annotation. This data is persistently stored along with the annotation if the annotation is stored in one of the following formats:

1. Embedded in the PDF

2. [Instant JSON](https://www.nutrient.io/guides/ios/importing-exporting/instant-json.md)

3. [XFDF](https://www.nutrient.io/guides/ios/importing-exporting/xfdf-support.md)

4. `NSCoding`-based serialization of [`Annotation`](https://www.nutrient.io/api/ios/documentation/pspdfkit/annotation)

Nutrient automatically handles the serialization of the custom data attached to an annotation for these formats.

## Storing custom data

[Nutrient iOS SDK 8.3](https://www.nutrient.io/blog/pspdfkit-ios-8-3/) added the [`customData`](https://www.nutrient.io/api/ios/documentation/pspdfkit/annotation/customdata) property to [`Annotation`](https://www.nutrient.io/api/ios/documentation/pspdfkit/annotation). This property allows you to store an arbitrary JSON-compliant dictionary in an annotation, like so:

### SWIFT

```swift

let restaurantInfo: [String: Any] = [
    "name": "Grill House",
    "locations": ["Vienna", "Paris", "New York"],
    "rating": 5,
    "verified": true
]

// The `customData` property is available on all subclasses of `Annotation`.
annotation.customData = restaurantInfo

```

### OBJECTIVE-C

```objc

NSDictionary<NSString *, id> *restaurantInfo = @{
    @"name": @"Grill House",
    @"locations": @[@"Vienna", @"Paris", @"New York"],
    @"rating": @5,
    @"verified": @YES
};

// The `customData` property is available on all subclasses of `Annotation`.
annotation.customData = restaurantInfo

```

This dictionary is saved to the annotation provider that the annotation belongs to when the document is saved. Nutrient does not use this property internally for any reason; you have complete control over its contents.

In addition, the dictionary can only have `String` keys, and all its values must be serializable to JSON — that is, they must be of the type `String`, `NSNumber`, `Dictionary`, `Array`, or `NSNull`. The numbers should not be `NaN` or infinity. If calling [`JSONSerialization.isValidJSONObject(_:)`](https://developer.apple.com/documentation/foundation/jsonserialization/1418461-isvalidjsonobject) on the dictionary does not return `true`, setting it to [`customData`](https://www.nutrient.io/api/ios/documentation/pspdfkit/annotation/customdata) will result in an exception being raised.

In addition to Nutrient’s automated handling of `customData` when stored to the locations mentioned above, `customData` is also serialized when using [`NSKeyedArchiver`](https://developer.apple.com/documentation/foundation/nskeyedarchiver) or [`Annotation.generateInstantJSON()`](https://www.nutrient.io/api/ios/documentation/pspdfkit/annotation/generateinstantjson()).
---

## Related pages

- [Configure annotation presets on iOS](/guides/ios/annotations/changing-default-values-for-color-and-text-size-of-annotations.md)
- [Customizing PDF annotation appearance streams](/guides/ios/annotations/appearance-streams.md)
- [Hiding annotations on iOS](/guides/ios/annotations/disable-rendered-annotation-types.md)
- [Creating a fixed-sized annotation on iOS](/guides/ios/annotations/fixed-size-annotations.md)
- [Customizing note icons on iOS](/guides/ios/annotations/customize-annotation-rendering.md)
- [Customizing color presets on iOS](/guides/ios/annotations/customizing-presets.md)