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

# Metadata

> Attach your own key-value data to invites, invite recipients and the entities created from them, and the rules that data must follow.

To enhance integration flexibility, every client-facing entity incorporates a `metadata` JSON object that allows for user-defined fields at the time of creation. This metadata is persisted and returned to the client upon retrieval of the entity.

For instance, the POST `/v1/invites` endpoint enables clients to generate an invite for applicants. In the request body, clients can provide a `metadata` field for the invite itself and for each invite recipient.

When a subsequent GET `/v1/invites/:id` request retrieves the invite or its associated recipients, the system appends the respective `metadata` object to each entity, as demonstrated below.

![A sandbox POST /v1/invites request body with metadata on the invite and on its recipient](https://mintcdn.com/theguarantors-2e3c1083/I_TMYtCDA-gwmmQ0/images/metadata/create-invite-request.png?fit=max\&auto=format\&n=I_TMYtCDA-gwmmQ0\&q=85\&s=6f90aa75581ee72a6ac9f4fc7aae5fe8)

![The GET /v1/invites/:id response for the same invite, returning both metadata objects unchanged](https://mintcdn.com/theguarantors-2e3c1083/I_TMYtCDA-gwmmQ0/images/metadata/get-invite-response.png?fit=max\&auto=format\&n=I_TMYtCDA-gwmmQ0\&q=85\&s=f577ffe67b8e7adb3343f44fa1a46b83)

This capability enables clients to attach application-specific context to the entities we provide, such as internal identifiers, workflow status, or source attribution. This eliminates the need for extra API fields or custom integrations. Consequently, clients can more easily align our entities with their internal systems and maintain flexible, evolving workflows.

## Metadata Validation

To ensure system performance and data integrity, metadata fields are subject to the following validation rules:

* **Total Size**: The entire metadata JSON object must not exceed 16KB when serialized.
* **Number of Keys**: A maximum of 50 key-value pairs are allowed per metadata object.
* **Key Length**: Each key must not exceed 64 characters.
* **Value Types**: Values must be one of the following scalar types:
  * String
  * Number (integer or floating-point)
  * Boolean
  * `null`
* **Format**: The metadata must be a valid JSON object. Arrays, strings, or other JSON types are not permitted.
* **Nested Structures**: Nested objects and arrays are not allowed as values.

If any of these validation rules are violated, the API will return a 400 Bad Request error with a message indicating which validation rule was violated. See [Errors](https://docs.theguarantors.com/errors.md).

`metadata` objects are also the one place a request body can include keys that aren't documented for the endpoint. See [Unknown fields](https://docs.theguarantors.com/errors.md#unknown-fields).