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

# Update a template

> Replaces the fields of an existing template. The payload and its validation are
identical to `POST /api/templates` — including the merge-field placeholders
documented there, whose available `value`s come from
`GET /api/board/{boardId}/merge-fields`. On top of the template permission, the
acting user must have access to the library folder the template sits in. A
template that does not exist — or belongs to another company — returns 404; an
archived one returns 403, since it is the caller's own and
`GET /api/templates/{id}` still returns it.




## OpenAPI

````yaml /openapi.yaml put /api/templates/{id}
openapi: 3.0.3
info:
  title: Aptly API
  version: '1.0'
  description: |
    The Aptly API lets external systems work with boards, contacts, inboxes,
    tasks, files, and other Aptly resources.

    Most endpoints accept an API key in the `x-token` header. Some endpoints
    also accept a delegate token or partner bearer token, as shown in each
    operation's security requirements, and explicitly public endpoints require
    no credential. API keys are scoped to a company and may be restricted to
    specific boards and read, insert, or update permissions; requests outside
    those restrictions receive a 403 `FORBIDDEN` response.
servers:
  - url: https://core-api.getaptly.com
    description: Production
security:
  - ApiKeyHeader: []
paths:
  /api/templates/{id}:
    put:
      tags:
        - Templates
      summary: Update a template
      description: >
        Replaces the fields of an existing template. The payload and its
        validation are

        identical to `POST /api/templates` — including the merge-field
        placeholders

        documented there, whose available `value`s come from

        `GET /api/board/{boardId}/merge-fields`. On top of the template
        permission, the

        acting user must have access to the library folder the template sits in.
        A

        template that does not exist — or belongs to another company — returns
        404; an

        archived one returns 403, since it is the caller's own and

        `GET /api/templates/{id}` still returns it.
      operationId: editTemplate
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Template ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateUpsert'
            examples:
              email:
                summary: Plain email template
                value:
                  companyId: '{{companyId}}'
                  userId: '{{userId}}'
                  name: Move-in welcome
                  description: Sent to new residents on move-in day
                  templateType: email
                  subject: Welcome to your new home
                  content: <p>Welcome!</p>
                  htmlBuilder: false
      responses:
        '200':
          description: Template updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Template'
        '400':
          description: Missing companyId, or an invalid payload.
        '401':
          description: Invalid or missing credential.
        '403':
          description: The acting user lacks the template permission or folder access.
        '404':
          description: Template not found.
      security:
        - ApiKeyHeader: []
        - DelegateToken: []
        - PartnerBearer: []
components:
  schemas:
    TemplateUpsert:
      type: object
      required:
        - name
        - description
        - templateType
        - subject
        - content
      properties:
        companyId:
          type: string
          description: >-
            Required with a partner token; resolved from an API key or delegate
            token.
        userId:
          type: string
          description: >-
            The acting user. Required with an API key or partner token; a
            delegate token supplies its own.
        name:
          type: string
        description:
          type: string
        templateType:
          type: string
          enum:
            - sms
            - email
            - form
            - eSignature
            - pdf
          description: >-
            Template kind. `blockDocument` is not accepted — it is an internal
            type for document blocks, not a user-facing template.
        subject:
          type: string
          description: >-
            Email subject, or the file name for a `pdf` template — in which case
            filename-illegal characters are stripped. Merge placeholders work
            here too, and are shape-checked the same way.
        content:
          type: string
          description: >-
            Template body. Merge placeholders take the form `{{value}}` or
            `{{value || fallback: text}}`, where `value` is an item's `value`
            from `GET /api/board/{boardId}/merge-fields` — for example
            `{{firstname}}`, `{{Locations["Rent"] || fallback: TBD}}`. They are
            checked for shape — an unclosed `{{`, an empty field name or a
            malformed bracket reference is rejected. Whether each field exists
            is not checked: an unknown one renders as its fallback at merge
            time.
        htmlBuilder:
          type: boolean
          enum:
            - false
          default: false
          description: >-
            Must be `false` or omitted. HTML-builder templates keep their markup
            in a builder-owned `builderData` format and can only be authored in
            the app.
        builderData:
          type: object
          description: Builder document, when one already exists.
        folderId:
          type: string
          description: >-
            Library folder the template belongs to — must be an existing,
            non-archived folder in the company. Governs who may edit the
            template.
        aptletUuid:
          type: string
          description: >-
            Board the template is scoped to. Must be an existing, non-archived
            board in the company.
        signature:
          type: string
        attachmentIds:
          type: array
          items:
            type: string
          description: Uploaded file ids to attach.
    Template:
      type: object
      properties:
        _id:
          type: string
          description: Template ID.
        companyId:
          type: string
          description: Company the template belongs to.
        name:
          type: string
          description: Template display name.
        templateType:
          type: string
          enum:
            - sms
            - email
            - form
            - eSignature
            - pdf
            - blockDocument
          description: Template category.
        archived:
          type: boolean
        createdAt:
          type: string
          format: date-time
        createdBy:
          type: string
          description: User ID of the creator.
        updatedAt:
          type: string
          format: date-time
      additionalProperties:
        description: >-
          Additional properties depend on the templateType (e.g. `subject`,
          `content` for email templates).
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-token
    DelegateToken:
      type: apiKey
      in: header
      name: Authorization
      description: 'Delegate token issued by the platform. Format: `DelegateToken <token>`'
    PartnerBearer:
      type: http
      scheme: bearer
      description: 'Partner token. Format: `Authorization: Bearer <token>`'

````