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

# Create or update a variant (upsert)



## OpenAPI

````yaml /api-reference/openapi.json patch /v1/signatures/{signature_id}/variants/{kind}
openapi: 3.0.1
info:
  title: Scribe Public API
  version: v1
  description: >-
    REST API to manage email signatures, teammates, smart fields, and marketing
    campaigns in your Scribe workspace. Every request uses JSON and is
    authenticated with a workspace API key. Endpoints are versioned under `/v1`,
    for example `https://api.scribe-mail.com/v1/signatures`.
  contact:
    name: Scribe Support
    url: https://help.scribe-mail.com/en
servers:
  - url: https://api.scribe-mail.com
    description: Production
security: []
tags:
  - name: Signatures
    description: >-
      Create, update, publish, and install email signature templates, and
      control which teammates each signature is assigned to.
  - name: Teammates
    description: >-
      Manage the people whose signatures Scribe deploys, and set their smart
      field values.
  - name: Emails
    description: >-
      Manage teammate email addresses, including the aliases that receive a
      signature.
  - name: Smart fields
    description: >-
      Define the dynamic fields, such as job title, phone number, or calendar
      link, that populate signatures.
  - name: Folders
    description: Organize signature templates into folders.
  - name: Assets
    description: >-
      Upload and manage the images and files used across signatures and
      campaigns.
  - name: Marketing campaigns
    description: >-
      Schedule, pause, and resume the promotional banners shown in your team's
      signatures.
  - name: Integrations
    description: >-
      List the directory, HRIS, and email integrations connected to your
      workspace.
  - name: Integration entities
    description: >-
      List the org units and groups from your connected integrations, used to
      target signatures.
  - name: Financial documents
    description: List the invoices and financial documents for your workspace.
paths:
  /v1/signatures/{signature_id}/variants/{kind}:
    parameters:
      - name: signature_id
        in: path
        required: true
        schema:
          type: string
      - name: kind
        in: path
        schema:
          type: string
          enum:
            - reply
            - internal
        required: true
    patch:
      tags:
        - Signatures
      summary: Create or update a variant (upsert)
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/signature_variant_update_params'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/signature_variant_response'
        '404':
          description: Unknown variant kind
        '409':
          description: Variants unavailable (no M365 signatures integration)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '422':
          description: Invalid content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validation_error_response'
      security:
        - ApiKey: []
components:
  schemas:
    signature_variant_update_params:
      type: object
      properties:
        variant:
          type: object
          properties:
            draft_content:
              $ref: '#/components/schemas/signature_content'
            activated:
              type: boolean
              description: >-
                Use a distinct variant on this kind of email. Setting true
                creates the variant if it does not exist yet.
            hidden:
              type: boolean
              description: Hide any signature on this kind of email.
            show_marketing_campaigns:
              type: boolean
              description: Append marketing campaigns on this kind of email.
          additionalProperties: false
      required:
        - variant
      additionalProperties: false
    signature_variant_response:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/signature_variant'
      required:
        - data
      additionalProperties: false
    error_response:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            code:
              type: string
            message:
              type: string
          required:
            - type
            - code
            - message
          additionalProperties: false
        remediation:
          type: object
          description: >-
            Optional dashboard hand-off: where to send the user to unblock the
            request (e.g. connect an integration). Present on some 403/409
            responses.
          properties:
            action:
              type: string
              enum:
                - connect_integration
                - manage_in_dashboard
                - upgrade_plan
            dashboard_url:
              type: string
              format: uri
            message:
              type: string
          required:
            - action
            - dashboard_url
            - message
          additionalProperties: false
      required:
        - error
      additionalProperties: false
    validation_error_response:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            code:
              type: string
            message:
              type: string
          required:
            - type
            - code
            - message
          additionalProperties: false
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              code:
                type: string
              message:
                type: string
              allowed:
                type: array
                description: >-
                  For an enum/const violation: the permitted values for this
                  field. Present only when the list is small enough to inline;
                  for large enums (e.g. icon) see the content schema.
                items: {}
              missing:
                type: array
                description: 'For a missing-required violation: the absent property names.'
                items:
                  type: string
            required:
              - field
              - code
              - message
            additionalProperties: false
      required:
        - error
        - details
      additionalProperties: false
    signature_content:
      description: >-
        A signature or marketing-campaign content block tree (the frontend
        ILayoutBlock): a `stack` root whose `children` recurse into the other
        block types. Strict-validated on write. An invalid tree is rejected with
        422 and the offending field pinpointed. Send null to clear.
      nullable: true
      allOf:
        - $ref: '#/components/schemas/signature_content_stack'
    signature_variant:
      type: object
      properties:
        kind:
          type: string
          enum:
            - reply
            - internal
          description: >-
            Which variant: shown on reply emails (reply) or same-domain/internal
            emails (internal).
        exists:
          type: boolean
          description: >-
            Whether a distinct variant signature has been created. When false,
            replies/internal emails use the primary signature.
        id:
          type: string
          nullable: true
          description: >-
            UUID of the variant signature template (null when it does not exist
            yet).
        activated:
          type: boolean
          description: >-
            Whether the distinct variant is in effect (vs. falling back to the
            primary signature).
        hidden:
          type: boolean
          description: When true, no signature is shown on this kind of email at all.
        show_marketing_campaigns:
          type: boolean
          description: Whether marketing campaigns are appended to this kind of email.
        content:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            The variant's published block tree, returned verbatim. See
            signature_content for the write shape.
        draft_content:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            The variant's unpublished draft block tree, returned verbatim. See
            signature_content for the write shape.
        last_published_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
      required:
        - kind
        - exists
        - id
        - activated
        - hidden
        - show_marketing_campaigns
        - content
        - draft_content
        - last_published_at
        - created_at
        - updated_at
      additionalProperties: false
    signature_content_stack:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        role:
          $ref: '#/components/schemas/signature_content_role'
        visible:
          type: boolean
        type:
          enum:
            - stack
        blockStyle:
          $ref: '#/components/schemas/signature_content_blockStyle'
        children:
          type: array
          items:
            $ref: '#/components/schemas/signature_content_block'
      required:
        - id
        - role
        - visible
        - type
        - blockStyle
        - children
      additionalProperties: false
    signature_content_role:
      type: string
      enum:
        - name
        - profilePicture
        - logo
        - gif
        - phoneNumber
        - email
        - website
        - address
        - jobPosition
        - socials
        - banner
        - disclaimer
        - numbers
        - signOff
        - attribute
        - browser_store
        - food_delivery
        - game_store
        - live_streaming
        - online_store
        - podcast
        - product_hunt
        - reading_app
        - store_app
        - tv_streaming
        - y_combinator
      nullable: true
    signature_content_blockStyle:
      type: object
      additionalProperties: false
      properties:
        marginBottom:
          type: number
        marginRight:
          type: number
        marginLeft:
          type: number
        marginTop:
          type: number
        paddingLeft:
          type: number
        paddingRight:
          type: number
        paddingTop:
          type: number
        paddingBottom:
          type: number
        alignItems:
          type: string
          enum:
            - flex-start
            - flex-end
            - center
        justifyContent:
          type: string
          enum:
            - flex-start
            - flex-end
            - center
        backgroundColor:
          type: string
        direction:
          type: string
          enum:
            - row
            - column
        gap:
          type: number
        width:
          anyOf:
            - type: number
            - type: string
              enum:
                - fill
                - fit
    signature_content_block:
      oneOf:
        - $ref: '#/components/schemas/signature_content_stack'
        - $ref: '#/components/schemas/signature_content_text'
        - $ref: '#/components/schemas/signature_content_image'
        - $ref: '#/components/schemas/signature_content_icon'
        - $ref: '#/components/schemas/signature_content_list'
        - $ref: '#/components/schemas/signature_content_listItem'
        - $ref: '#/components/schemas/signature_content_listItemLabel'
        - $ref: '#/components/schemas/signature_content_socialList'
        - $ref: '#/components/schemas/signature_content_socialListItem'
        - $ref: '#/components/schemas/signature_content_button'
        - $ref: '#/components/schemas/signature_content_divider'
        - $ref: '#/components/schemas/signature_content_marketing'
      discriminator:
        propertyName: type
        mapping:
          stack:
            $ref: '#/components/schemas/signature_content_stack'
          text:
            $ref: '#/components/schemas/signature_content_text'
          image:
            $ref: '#/components/schemas/signature_content_image'
          icon:
            $ref: '#/components/schemas/signature_content_icon'
          list:
            $ref: '#/components/schemas/signature_content_list'
          listItem:
            $ref: '#/components/schemas/signature_content_listItem'
          listItemLabel:
            $ref: '#/components/schemas/signature_content_listItemLabel'
          socialList:
            $ref: '#/components/schemas/signature_content_socialList'
          socialListItem:
            $ref: '#/components/schemas/signature_content_socialListItem'
          button:
            $ref: '#/components/schemas/signature_content_button'
          divider:
            $ref: '#/components/schemas/signature_content_divider'
          marketing:
            $ref: '#/components/schemas/signature_content_marketing'
    signature_content_text:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        role:
          $ref: '#/components/schemas/signature_content_role'
        visible:
          type: boolean
        type:
          enum:
            - text
        blockStyle:
          $ref: '#/components/schemas/signature_content_blockStyle'
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/signature_content_token'
        textAlign:
          type: string
          enum:
            - left
            - center
            - right
      required:
        - id
        - role
        - visible
        - type
        - blockStyle
        - tokens
      additionalProperties: false
    signature_content_image:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        role:
          $ref: '#/components/schemas/signature_content_role'
        visible:
          type: boolean
        type:
          enum:
            - image
        blockStyle:
          $ref: '#/components/schemas/signature_content_blockStyle'
        assetUuid:
          type: string
          nullable: true
        assetKey:
          type: string
        smartFieldUuid:
          type: string
          nullable: true
        width:
          type: number
        height:
          type: number
        borderRadius:
          type: string
          enum:
            - square
            - smallRadius
            - mediumRadius
            - rounded
        href:
          $ref: '#/components/schemas/signature_content_href'
        alt:
          type: string
      required:
        - id
        - role
        - visible
        - type
        - blockStyle
        - assetUuid
        - smartFieldUuid
        - width
        - height
        - borderRadius
        - href
      additionalProperties: false
    signature_content_icon:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        role:
          $ref: '#/components/schemas/signature_content_role'
        visible:
          type: boolean
        type:
          enum:
            - icon
        blockStyle:
          $ref: '#/components/schemas/signature_content_blockStyle'
        icon:
          $ref: '#/components/schemas/signature_content_iconName'
        href:
          $ref: '#/components/schemas/signature_content_href'
        alt:
          type: string
        iconStyle:
          $ref: '#/components/schemas/signature_content_iconStyle'
      required:
        - id
        - role
        - visible
        - type
        - blockStyle
        - icon
        - href
        - iconStyle
      additionalProperties: false
    signature_content_list:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        role:
          $ref: '#/components/schemas/signature_content_role'
        visible:
          type: boolean
        type:
          enum:
            - list
        blockStyle:
          $ref: '#/components/schemas/signature_content_blockStyle'
        children:
          type: array
          items:
            $ref: '#/components/schemas/signature_content_listItem'
        itemsPerRow:
          type: number
        separator:
          type: string
          nullable: true
        separatorColor:
          type: string
        gap:
          type: number
        alignContent:
          type: boolean
      required:
        - id
        - role
        - visible
        - type
        - blockStyle
        - children
        - itemsPerRow
        - separator
        - separatorColor
        - gap
        - alignContent
      additionalProperties: false
    signature_content_listItem:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        role:
          $ref: '#/components/schemas/signature_content_role'
        visible:
          type: boolean
        type:
          enum:
            - listItem
        blockStyle:
          $ref: '#/components/schemas/signature_content_blockStyle'
        gap:
          type: number
        label:
          $ref: '#/components/schemas/signature_content_listItemLabel'
        value:
          $ref: '#/components/schemas/signature_content_text'
      required:
        - id
        - role
        - visible
        - type
        - blockStyle
        - gap
        - label
        - value
      additionalProperties: false
    signature_content_listItemLabel:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        role:
          $ref: '#/components/schemas/signature_content_role'
        visible:
          type: boolean
        type:
          enum:
            - listItemLabel
        variant:
          type: string
          enum:
            - icon
            - text
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/signature_content_token'
        textAlign:
          type: string
          enum:
            - left
            - center
            - right
        verticalAlign:
          type: string
          enum:
            - top
            - middle
            - bottom
        icon:
          $ref: '#/components/schemas/signature_content_iconName'
        iconStyle:
          $ref: '#/components/schemas/signature_content_iconStyle'
        alt:
          type: string
      required:
        - id
        - role
        - visible
        - type
        - variant
        - tokens
        - verticalAlign
        - icon
        - iconStyle
      additionalProperties: false
    signature_content_socialList:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        role:
          $ref: '#/components/schemas/signature_content_role'
        visible:
          type: boolean
        type:
          enum:
            - socialList
        blockStyle:
          $ref: '#/components/schemas/signature_content_blockStyle'
        children:
          type: array
          items:
            $ref: '#/components/schemas/signature_content_socialListItem'
        gap:
          type: number
        separator:
          type: string
          nullable: true
      required:
        - id
        - role
        - visible
        - type
        - blockStyle
        - children
        - gap
        - separator
      additionalProperties: false
    signature_content_socialListItem:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        role:
          $ref: '#/components/schemas/signature_content_role'
        visible:
          type: boolean
        type:
          enum:
            - socialListItem
        icon:
          $ref: '#/components/schemas/signature_content_iconName'
        href:
          $ref: '#/components/schemas/signature_content_href'
        alt:
          type: string
        iconStyle:
          $ref: '#/components/schemas/signature_content_iconStyle'
        label:
          type: string
        variant:
          type: string
          enum:
            - icon
            - text
        labelStyle:
          $ref: '#/components/schemas/signature_content_textStyle'
      required:
        - id
        - role
        - visible
        - type
        - icon
        - href
        - iconStyle
        - label
        - variant
        - labelStyle
      additionalProperties: false
    signature_content_button:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        role:
          $ref: '#/components/schemas/signature_content_role'
        visible:
          type: boolean
        type:
          enum:
            - button
        blockStyle:
          $ref: '#/components/schemas/signature_content_blockStyle'
        text:
          type: string
        href:
          $ref: '#/components/schemas/signature_content_href'
        buttonStyle:
          $ref: '#/components/schemas/signature_content_buttonStyle'
      required:
        - id
        - role
        - visible
        - type
        - blockStyle
        - text
        - href
        - buttonStyle
      additionalProperties: false
    signature_content_divider:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        role:
          $ref: '#/components/schemas/signature_content_role'
        visible:
          type: boolean
        type:
          enum:
            - divider
        blockStyle:
          $ref: '#/components/schemas/signature_content_blockStyle'
        color:
          type: string
        thickness:
          type: number
        width:
          anyOf:
            - type: number
            - enum:
                - fill
        height:
          type: number
      required:
        - id
        - role
        - visible
        - type
        - blockStyle
        - color
        - thickness
      additionalProperties: false
    signature_content_marketing:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        role:
          $ref: '#/components/schemas/signature_content_role'
        visible:
          type: boolean
        type:
          enum:
            - marketing
        blockStyle:
          $ref: '#/components/schemas/signature_content_marketingBlockStyle'
      required:
        - id
        - role
        - visible
        - type
        - blockStyle
      additionalProperties: false
    signature_content_token:
      oneOf:
        - $ref: '#/components/schemas/signature_content_textToken'
        - $ref: '#/components/schemas/signature_content_newlineToken'
      discriminator:
        propertyName: type
        mapping:
          textToken:
            $ref: '#/components/schemas/signature_content_textToken'
          newlineToken:
            $ref: '#/components/schemas/signature_content_newlineToken'
    signature_content_href:
      type: object
      additionalProperties: false
      properties:
        text:
          type: string
          nullable: true
        smartFieldUuid:
          type: string
          nullable: true
      required:
        - text
        - smartFieldUuid
      nullable: true
    signature_content_iconName:
      type: string
      enum:
        - 500px
        - airbnb
        - amazon
        - android
        - angellist
        - app-store
        - app-store-ios
        - apple
        - apple-pay
        - bandcamp
        - behance
        - bitbucket
        - bitcoin
        - blogger-b
        - bluesky
        - book-open-solid
        - btc
        - buy-me-a-coffee
        - cargonet
        - cellphone
        - codepen
        - crunchbase
        - depop
        - discogs
        - discord
        - dribbble
        - dropbox
        - ebay
        - ello
        - ethereum
        - etsy
        - evernote
        - facebook-f
        - facebook-messenger
        - figma
        - flickr
        - flipboard
        - foursquare
        - github-alt
        - gondola
        - goodreads-g
        - google-drive
        - google-g
        - google-meet
        - google-play
        - hacker-news
        - houzz
        - hubspot
        - imdb
        - instagram
        - invision
        - itunes-note
        - junco
        - kickstarter-k
        - kofi
        - line
        - linkedin-in
        - linux
        - mastodon
        - medium-m
        - meetup
        - mixcloud
        - monero
        - napster
        - npm
        - orcid
        - patreon
        - paypal
        - pinterest-p
        - product-hunt
        - question-solid
        - quora
        - reddit-alien
        - researchgate
        - salesforce
        - scribe-address
        - scribe-email
        - scribe-phone
        - scribe-website
        - scribe-website-2
        - shopify
        - shpock
        - skype
        - slack
        - slideshare
        - snapchat-ghost
        - soundcloud
        - spotify
        - stack-overflow
        - steam-symbol
        - telegram-plane
        - threads
        - tiktok
        - tripadvisor
        - tumblr
        - twitch
        - twitter
        - unity
        - viber
        - vimeo-v
        - vinted
        - vk
        - weixin
        - whatsapp
        - wikipedia-w
        - www
        - x-twitter
        - xing
        - y-combinator
        - yammer
        - yelp
        - youtube
        - zillow
        - zoom
    signature_content_iconStyle:
      type: object
      additionalProperties: false
      required:
        - size
        - color
        - backgroundColor
        - shape
      properties:
        size:
          type: number
        color:
          type: string
        backgroundColor:
          type: string
        shape:
          $ref: '#/components/schemas/signature_content_iconShape'
    signature_content_textStyle:
      type: object
      additionalProperties: false
      required:
        - fontSize
        - color
        - fontFamily
        - lineHeight
        - fontWeight
      properties:
        fontSize:
          type: number
          description: Font size in pixels.
        color:
          type: string
        fontFamily:
          type: string
          enum:
            - helvetica
            - arial
            - arial_black
            - arial_narrow
            - tahoma
            - georgia
            - times
            - garamond
            - verdana
            - lucida
            - trebuchet
        lineHeight:
          type: number
          description: >-
            Line box height in PIXELS (≈1.3× fontSize, e.g. fontSize 14 → 18).
            NOT a CSS multiplier: a value like 1.3 renders as line-height: 1.3px
            and collapses every line.
          minimum: 4
        fontWeight:
          type: integer
          enum:
            - 400
            - 700
        fontStyle:
          type: string
          enum:
            - normal
            - italic
        textDecoration:
          type: string
          enum:
            - none
            - line-through
            - underline
        textTransform:
          type: string
          enum:
            - none
            - uppercase
    signature_content_buttonStyle:
      type: object
      additionalProperties: false
      required:
        - fontSize
        - color
        - fontFamily
        - lineHeight
        - fontWeight
        - backgroundColor
        - height
        - borderRadius
        - borderStyle
        - borderWidth
        - borderColor
        - width
      properties:
        fontSize:
          type: number
          description: Font size in pixels.
        color:
          type: string
        fontFamily:
          type: string
          enum:
            - helvetica
            - arial
            - arial_black
            - arial_narrow
            - tahoma
            - georgia
            - times
            - garamond
            - verdana
            - lucida
            - trebuchet
        lineHeight:
          type: number
          description: >-
            Line box height in PIXELS (≈1.3× fontSize, e.g. fontSize 14 → 18).
            NOT a CSS multiplier: a value like 1.3 renders as line-height: 1.3px
            and collapses every line.
          minimum: 4
        fontWeight:
          type: integer
          enum:
            - 400
            - 700
        fontStyle:
          type: string
          enum:
            - normal
            - italic
        textDecoration:
          type: string
          enum:
            - none
            - line-through
            - underline
        textTransform:
          type: string
          enum:
            - none
            - uppercase
        backgroundColor:
          type: string
        height:
          type: number
        borderRadius:
          type: number
        borderStyle:
          type: string
          enum:
            - solid
            - none
        borderWidth:
          type: number
        borderColor:
          type: string
        width:
          type: number
    signature_content_marketingBlockStyle:
      type: object
      additionalProperties: false
      properties:
        marginBottom:
          type: number
        marginRight:
          type: number
        marginLeft:
          type: number
        marginTop:
          type: number
        paddingLeft:
          type: number
        paddingRight:
          type: number
        paddingTop:
          type: number
        paddingBottom:
          type: number
        alignItems:
          type: string
          enum:
            - flex-start
            - flex-end
            - center
        justifyContent:
          type: string
          enum:
            - flex-start
            - flex-end
            - center
        backgroundColor:
          type: string
        direction:
          type: string
          enum:
            - row
            - column
        gap:
          type: number
    signature_content_textToken:
      type: object
      additionalProperties: false
      required:
        - id
        - type
        - value
        - smartFieldUuid
        - textStyle
        - href
      properties:
        id:
          type: string
        type:
          enum:
            - textToken
        value:
          type: string
          nullable: true
        smartFieldUuid:
          type: string
          nullable: true
        textStyle:
          $ref: '#/components/schemas/signature_content_textStyle'
        href:
          $ref: '#/components/schemas/signature_content_href'
    signature_content_newlineToken:
      type: object
      additionalProperties: false
      required:
        - id
        - type
      properties:
        id:
          type: string
        type:
          enum:
            - newlineToken
    signature_content_iconShape:
      type: string
      enum:
        - normal
        - plain-square
        - plain-circle
        - stroke-square
        - stroke-circle
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer

````