> ## Documentation Index > Fetch the complete documentation index at: https://docs.tented.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create custom fields > Create one custom field (send a single object) or up to 50 in one request (send `{"items": [...]}`). Bulk creation is atomic — if any item collides, nothing is created. Limits and collisions: - A workspace can have at most **200 active custom fields**. Exceeding the cap returns `409` with `error_code: "field_definition_cap_exceeded"` plus `limit`, `current_active_count`, and `attempted_count`. - An `api_name` that duplicates another item in the request or an existing (active or archived) custom field returns `409` with `error_code: "field_definition_collision"` and a `conflicts` array describing each collision. To reuse an archived field's name, restore it instead via `PATCH /v1/contact-fields/{fieldDefinitionId}` with `status: "active"`. - Standard field names (`email`, `first_name`, `company`, …) are reserved and return `400`. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/contact-fields openapi: 3.1.0 info: title: Tented API version: 1.0.0 description: >- The Tented public API: generate, publish, and manage AI-built web pages (tents), and run the email platform — contacts, reusable emails, one-time blasts, and triggered flows. ## Authentication Authenticate every request with a workspace API key: `Authorization: Bearer `. Keys are created in **Workspace Settings → API Keys** and are scoped to a single workspace. ## Asynchronous work Tent generation, bulk creation, and email AI generation return `202 Accepted` immediately. Poll the corresponding status endpoint (`GET /v1/tents/{tentId}`, `GET /v1/bulk-jobs/{bulkJobId}`, `GET /v1/emails/{emailId}/generations/{generationId}`) — no more than every 10 seconds. ## Pagination Email listings use cursor pagination (`cursor`/`next_cursor`). Blast, flow, and member listings use page pagination (`page`/`limit` with a `pagination` object in the response). ## Conventions Request and response fields are snake_case, with two exceptions: analytics query parameters (`tentIdOrAlias`, `daysBack`) and segment rule trees (camelCase keys such as `listId` and `timeWindow`). contact: name: Tented Support email: support@tented.ai servers: - url: https://api.tented.ai description: Production security: - bearerAuth: [] tags: - name: Tents description: >- Create, edit, publish, and manage AI-generated pages, including asset uploads and bulk creation. - name: Analytics description: Traffic analytics for single tents and the whole workspace. - name: Contacts description: >- Batch create, update, and delete contacts. Up to 25 items per request with per-item results. - name: Emails description: >- Reusable email content: AI generation, direct HTML edits, plain-text control, and approval. - name: Email Blasts description: >- One-time sends to an audience: compose, schedule, track engagement, export recipients. - name: Triggered Flows description: >- Multi-step automations that enroll contacts on triggers and move them through a step graph. - name: Contact Imports - name: Contact Fields - name: Contact Lists - name: Email Templates - name: Tent Templates description: >- Reusable, AI-editable tent layouts. Create from HTML or an existing tent, iterate with AI, approve, and clone. Approved tent templates seed new tents. paths: /v1/contact-fields: post: tags: - Contact Fields summary: Create custom fields description: >- Create one custom field (send a single object) or up to 50 in one request (send `{"items": [...]}`). Bulk creation is atomic — if any item collides, nothing is created. Limits and collisions: - A workspace can have at most **200 active custom fields**. Exceeding the cap returns `409` with `error_code: "field_definition_cap_exceeded"` plus `limit`, `current_active_count`, and `attempted_count`. - An `api_name` that duplicates another item in the request or an existing (active or archived) custom field returns `409` with `error_code: "field_definition_collision"` and a `conflicts` array describing each collision. To reuse an archived field's name, restore it instead via `PATCH /v1/contact-fields/{fieldDefinitionId}` with `status: "active"`. - Standard field names (`email`, `first_name`, `company`, …) are reserved and return `400`. operationId: create-contact-fields requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/ContactFieldCreateItem' - type: object title: Bulk create properties: items: type: array items: $ref: '#/components/schemas/ContactFieldCreateItem' minItems: 1 maxItems: 50 description: Custom fields to create (1–50). Creation is atomic. required: - items responses: '201': description: >- Custom fields created. Always returns an `items` array, even for a single-object request. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/ContactFieldDefinition' description: The created custom field definitions. required: - items '400': description: >- Bad request — invalid request body, or an `api_name` uses a reserved standard field name. Validation failures include `details.issues` with per-field messages. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized — missing, malformed, revoked, or expired API key. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- Conflict — `api_name` collision (`error_code: "field_definition_collision"`, with a `conflicts` array) or the 200-active-field cap was exceeded (`error_code: "field_definition_cap_exceeded"`, with `limit`, `current_active_count`, `attempted_count`). content: application/json: schema: $ref: '#/components/schemas/ContactFieldWriteConflict' components: schemas: ContactFieldCreateItem: type: object title: Custom field properties: display_name: type: string minLength: 1 maxLength: 255 description: Human-readable label. api_name: type: string minLength: 1 maxLength: 255 pattern: ^[a-z][a-z0-9_]*$ description: >- Stable identifier: must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Standard field names (e.g. `email`, `first_name`) are reserved. Cannot be changed after creation. value_type: type: string enum: - string - number - boolean - date default: string description: Value type for the field. Cannot be changed after creation. is_editable: type: boolean default: true description: Whether values can be edited manually in the UI. description: type: - string - 'null' maxLength: 1000 description: Optional description of what the field stores. show_in_people_list_default: type: boolean default: false description: Whether the field appears as a column in the People list by default. required: - display_name - api_name description: A custom field to create. ContactFieldDefinition: type: object properties: type: type: string enum: - standard - custom description: >- `standard` for built-in contact fields (read-only, always active), `custom` for workspace custom fields. api_name: type: string description: >- Stable identifier used in API payloads, import mappings, and merge tags (e.g. `email`, `firstName`, or a custom field's snake_case name). display_name: type: string description: Human-readable label. value_type: type: string enum: - string - number - boolean - date - email - phone description: >- Value type. Standard fields may use `email`/`phone`; custom fields are `string`, `number`, `boolean`, or `date`. is_editable: type: boolean description: >- Whether values can be edited manually in the UI. Always `false` for standard fields. status: type: string enum: - active - archived description: Field status. Standard fields are always `active`. field_definition_id: type: string format: uuid description: >- Custom field definition ID — the path parameter for `PATCH /v1/contact-fields/{fieldDefinitionId}`. Custom fields only. description: type: - string - 'null' description: Optional description of what the field stores. Custom fields only. management_mode: type: string enum: - org_managed - integration_managed description: >- Who owns the field: `org_managed` (created in the UI or via this API — fully editable) or `integration_managed` (owned by a connected integration — name, description, and status are locked). Custom fields only. provenance_kind: type: string enum: - manual_ui - import_csv - integration description: How the field was created. Custom fields only. provenance_provider: type: - string - 'null' description: >- Integration provider that created the field, when applicable. Custom fields only. provenance_reference: type: - string - 'null' description: >- Provider-side reference for the field, when applicable. Custom fields only. created_by_user_id: type: - string - 'null' description: >- Who created the field. `tented-api` for fields created via this API. Custom fields only. created_from_import_session_id: type: - string - 'null' description: >- Import session the field was created from, when `provenance_kind` is `import_csv`. Custom fields only. show_in_people_list_default: type: boolean description: >- Whether the field appears as a column in the People list by default. Custom fields only. created_at: type: string format: date-time description: Creation time. Custom fields only. updated_at: type: string format: date-time description: Last update. Custom fields only. required: - type - api_name - display_name - value_type - is_editable - status description: >- A contact field definition. Standard fields include only the six required properties; custom fields include the full definition metadata. Error: type: object properties: error: type: string description: Human-readable error message. error_code: type: string description: >- Stable machine-readable error code (present on email, blast, flow, and related endpoints, e.g. `campaign_not_ready`, `generation_in_progress`). message: type: string description: Additional human-readable context (present on some tent endpoints). code: type: string description: >- Machine-readable code used by tent creation errors (e.g. `INVALID_PROMPT_INTENT`). details: type: object additionalProperties: true description: >- Additional error context. Validation errors include `issues`: an array of `{ path, message }` objects. limit: type: integer description: Plan limit that was hit (present on `429` publish-limit errors). current: type: integer description: >- Current usage against the limit (present on `429` publish-limit errors). required: - error description: >- Error response. All errors include `error`; the other fields vary by endpoint group. ContactFieldWriteConflict: type: object properties: error: type: string description: Human-readable error message. error_code: type: string enum: - field_definition_collision - field_definition_cap_exceeded description: >- `field_definition_collision`: an `api_name` duplicates another item in the request or an existing custom field. `field_definition_cap_exceeded`: the request would exceed the 200-active-custom-field cap. conflicts: type: array items: type: object properties: kind: type: string enum: - duplicate_in_request - active_custom - archived_custom description: >- `duplicate_in_request`: two items in the same request use this name. `active_custom`: an active custom field already uses it. `archived_custom`: an archived custom field uses it — restore that field instead. requested_api_name: type: string description: The `api_name` that collided. existing_field_definition_id: type: string format: uuid description: >- ID of the existing field, when the collision is with an existing field. existing_display_name: type: string description: >- Display name of the existing field, when the collision is with an existing field. required: - requested_api_name - kind description: One collision. description: >- Present on `field_definition_collision` errors: one entry per colliding `api_name`. limit: type: integer description: >- The active-custom-field cap (200). Present on `field_definition_cap_exceeded` errors. current_active_count: type: integer description: >- Active custom fields the workspace already has. Present on `field_definition_cap_exceeded` errors. attempted_count: type: integer description: >- Fields this request tried to create. Present on `field_definition_cap_exceeded` errors. required: - error - error_code description: '`409` response for custom-field creation conflicts.' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Workspace API key, e.g. `Authorization: Bearer tented_...`. Create keys in Workspace Settings → API Keys. ````