Skip to main content
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
The GET /v1/invites/:id response for the same invite, returning both metadata objects unchanged
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. metadata objects are also the one place a request body can include keys that aren’t documented for the endpoint. See Unknown fields.