---
title: "Create an embed session"
method: POST
path: "/v1/embeds"
tags: ["Headless Importer"]
---

# Create an embed session

`POST /v1/embeds`

Create an Importer embed session.

## Request body

- CreateEmbedRequest
  - `embed_client_id` string, required — The Importer client Id from the OneSchema dashboard.
  - `template_key` string, required — The key for the template that should be used in the import.
  - `embed_user_jwt` string, required — The JWT to be used for authentication.
  - `webhook_key` string — [Legacy] The key for the webhook that data should be sent to after import. This field should now be passed via the `import_config` parameter.
  - `event_webhook_keys` string[] — The keys of event webhooks which should listen to events in this embed session.
  - `dev_mode` boolean — Whether the Embed is initialized in developer mode.
  - `customization_key` string — An optional key for a customization made in OneSchema the importer should be styled with. If not provided, will use your default customization.
  - `customization_overrides` CustomizationOverrides
    - `primary_color` string
    - `background_primary_color` string
    - `background_secondary_color` string
    - `header_color` string
    - `footer_color` string
    - `border_color` string
    - `success_color` string
    - `warning_color` string
    - `error_color` string
    - `modal_fullscreen` boolean
    - `modal_mask_color` string
    - `modal_border_radius` string
    - `button_border_radius` string
    - `button_primary_fill_color` string
    - `button_primary_stroke_color` string
    - `button_primary_text_color` string
    - `button_secondary_fill_color` string
    - `button_secondary_stroke_color` string
    - `button_secondary_text_color` string
    - `button_tertiary_fill_color` string
    - `button_tertiary_stroke_color` string
    - `button_tertiary_text_color` string
    - `button_alert_fill_color` string
    - `button_alert_stroke_color` string
    - `button_alert_text_color` string
    - `font_url` string
    - `font_family` string
    - `font_color_primary` string
    - `font_color_secondary` string
    - `font_color_placeholder` string
    - `hide_logo` boolean
    - `illustration_url` string
    - `uploader_header_text` string
    - `uploader_subheader_text` string
    - `uploader_show_sidebar` boolean
    - `uploader_sidebar_details` string — "required" | "all"
    - `uploader_show_sidebar_banner` boolean
    - `uploader_sidebar_banner_text` string
    - `include_excel_template` boolean
    - `import_experience` string — "blockIfErrors" | "promptIfErrors" | "ignoreErrors"
    - `import_unmapped_columns` boolean
    - `mapping_strategy` string[] — "exact" | "fuzzy" | "historical"
    - `skip_mapping` string[] — "exact" | "fuzzy" | "historical"
    - `accept_code_hook_suggestions` boolean
    - `autofix_after_mapping` boolean
    - `file_size_limit` integer
  - `template_overrides` TemplateOverrides
    - `columns` TemplateColumnOverride[]
      - `key` string, required
      - `label` string
      - `data_type` string
      - `validation_options` object[]
      - `description` string
      - `is_custom` boolean
      - `is_required` boolean
      - `is_unique` boolean
      - `is_locked` boolean — Users will not be able to edit data mapped to this column on the Review & finalize step.
      - `is_multi_mappable` boolean — Users will be able to map multiple columns to this template column.
      - `is_hidden` boolean — This column will be hidden in the Review & finalize step.
      - `is_unmappable` boolean — Users will not be able to map to this column.
      - `letter_case` string
      - `min_char_limit` integer
      - `max_char_limit` integer
      - `delimiter` string
      - `must_exist` boolean
      - `default_value` string
      - `mapping_hints` string[]
  - `import_config` ImportConfig
    - `type` string — Type of OneSchema import that should be triggered for the embed
    - `key` string — Only applicable for "webhook" import type. Specifies the key for the importer webhook that should be called with import data.
    - `metadata_only` boolean — Only applicable for the "local" import type. Specifies whether the import should only include metadata.
    - `url` string — Only applicable for "file-upload" import type. This is the URL the importer data will be sent to.
    - `format` string — Only applicable for "file-upload" import type. This is the file format in which the importer data will be sent as. Either `csv` or `json`.
    - `headers` ImportConfigHeaders
    - `format_options` ImportConfigFormatOptions
      - `header_style` 'names' | 'keys' — Whether uploaded csv file should have the uploaded template column names as headers or template column keys.

## Response `200`

200

- EmbedCreatedResponse
  - `id` integer
  - `token` string
  - `status` string
  - `user_jwt` string

## Other responses

- `400` — 400

---

[API](https://skmtc.net/oneschema/apis/templates.md) · [All operations](https://skmtc.net/oneschema/apis/templates/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/oneschema/templates/versions/40674aa6d4d9/schema)