> ## Documentation Index > Fetch the complete documentation index at: https://developer.dromo.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a new headless import ## OpenAPI ````yaml /api-reference/openapi.json post /headless/imports/ openapi: 3.1.0 info: title: Dromo description: >- Dromo's APIs provide convenient programmatic access to your uploads and schemas. You can use them to create powerful automated workflows. termsOfService: https://dromo.io/legal/terms contact: name: Dromo email: contact@dromo.io version: '1.0' servers: - url: https://app.dromo.io/api/v1 security: - api_key: [] tags: - name: uploads description: Viewing completed imports - name: import-schemas description: Creating and viewing import schemas - name: headless description: Creating and viewing headless imports - name: sftp-credentials description: Managing SFTP server credentials - name: sftp-connectors description: Managing SFTP automated import connectors paths: /headless/imports/: post: tags: - headless summary: Create a new headless import operationId: createHeadlessImport requestBody: content: application/json: schema: type: object properties: schema_id: type: string description: >- ID of a saved schema. Mutually exclusive with `fields` — provide `schema_id` or `fields`, not both. When provided alongside `settings` or `hooks`, those values are merged on top of the saved schema for this import only. example: 94187d21-9820-420f-b08c-a80cbbf52604 fields: $ref: '#/components/schemas/SchemaFields' settings: $ref: '#/components/schemas/SchemaSettings' hooks: $ref: '#/components/schemas/SchemaHooks' original_filename: oneOf: - type: string description: >- Name of the file being imported (exclude if using initial_data) example: user.csv - type: 'null' initial_data: oneOf: - type: array description: >- Complete JSON data to be imported, max size 15MB (exclude if using a file) example: - first_name: Zeph last_name: paul.zeph@gmail.com - type: 'null' import_metadata: $ref: '#/components/schemas/ImportMetaData' example: fields: - key: first_name type: string label: First Name validators: [] - key: last_name type: string label: Last Name validators: [] initial_data: - first_name: Zeph last_name: paul.zeph@gmail.com hooks: rowHooks: - >- (record, mode) => { return { row: { first_name: { value: "Updated from row hook" } } }; } responses: '201': description: Import successfully initialized content: application/json: schema: $ref: '#/components/schemas/HeadlessImportFull' '404': description: No schema found with that id security: - api_key: [] components: schemas: SchemaFields: type: array description: >- Inline schema field definitions. Required when `schema_id` is omitted; mutually exclusive with `schema_id`. Accepts the same field definitions as a saved schema. items: type: object properties: key: type: string type: oneOf: - type: string - type: array label: type: string description: type: string alternateMatches: type: array items: type: string validators: type: array items: type: object invalidValueMessage: type: string readOnly: type: boolean hidden: type: boolean requireMapping: type: boolean manyToOne: type: boolean required: - key - type - label additionalProperties: false example: - key: first_name type: string label: First Name validators: [] - key: last_name type: string label: Last Name validators: [] SchemaSettings: type: object description: >- Import settings. When used with `schema_id`, merged on top of the saved schema (provided keys overwrite; omitted keys are unchanged). When used without `schema_id`, defines settings for the inline schema. properties: importIdentifier: type: string title: type: string allowInvalidSubmit: type: boolean invalidDataBehavior: type: string enum: - BLOCK_SUBMIT - INCLUDE_INVALID_ROWS - REMOVE_INVALID_ROWS - INCLUDE_INVALID_ROWS_AND_VALUES backendSync: type: boolean backendSyncMode: type: string enum: - DISABLED - FULL_DATA - MAPPINGS_ONLY manualInputDisabled: type: boolean manualInputOnly: type: boolean allowCustomFields: type: boolean passThroughUnmappedColumns: type: boolean maxRecords: oneOf: - type: integer - type: 'null' developmentMode: type: boolean displayEncoding: type: boolean styleOverrides: type: object maxFileSize: type: integer webhookUrl: oneOf: - type: string - type: 'null' needsReviewWebhookUrl: oneOf: - type: string - type: 'null' initialData: oneOf: - type: array - type: 'null' additionalProperties: false example: importIdentifier: contacts-import invalidDataBehavior: BLOCK_SUBMIT SchemaHooks: type: object description: >- Import hooks. When used with `schema_id`, merged on top of the saved schema. When used without `schema_id`, defines hooks for the inline schema. properties: rowHooks: type: array items: type: string bulkRowHooks: type: array items: type: string rowDeleteHooks: type: array items: type: string beforeFinishCallback: type: string columnHooks: type: array items: type: object properties: fieldName: type: string callback: type: string required: - fieldName - callback additionalProperties: false stepHooks: type: array items: type: object properties: type: type: string enum: - UPLOAD_STEP - REVIEW_STEP - REVIEW_STEP_POST_HOOKS callback: type: string required: - type - callback additionalProperties: false additionalProperties: false example: rowHooks: - >- (record, mode) => { return { row: { first_name: { value: "Updated from row hook" } } }; } ImportMetaData: oneOf: - type: object properties: user: oneOf: - type: object properties: id: type: string name: type: string email: type: string companyId: type: string companyName: type: string required: - id additionalProperties: false - type: 'null' - type: 'null' example: user: id: jeff_id name: Jeff email: jeff@dromo.io companyName: Dromo companyId: dromo_id HeadlessImportFull: allOf: - $ref: '#/components/schemas/HeadlessImport' - type: object properties: upload: type: string example: >- https://dromo-headless-imports-prod.s3.us-west-2.amazonaws.com/test-key-123?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20230227%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230227T160315Z&X-Amz-Expires=1800&X-Amz-SignedHeaders=host&X-Amz-Signature=example1234567890abcdef1234567890abcdef1234567890abcdef12345678 readOnly: true review_url: type: string example: >- https://app.dromo.io/headless/94187d21-9820-420f-b08c-a80cbbf52604/ readOnly: true result_metadata: oneOf: - type: object - type: 'null' example: null readOnly: true import_errors: oneOf: - type: array items: type: object - type: 'null' example: null readOnly: true HeadlessImport: type: object properties: id: type: string example: 94187d21-9820-420f-b08c-a80cbbf52604 readOnly: true schema_id: type: string example: 94187d21-9820-420f-b08c-a80cbbf52604 status: type: string enum: - AWAITING_UPLOAD - RUNNING - SUCCESSFUL - FAILED - NEEDS_REVIEW example: AWAITING_UPLOAD readOnly: true original_filename: type: string example: user_data.csv created_date: type: string format: date-time readOnly: true modified_date: type: string format: date-time readOnly: true securitySchemes: api_key: type: apiKey name: X-Dromo-License-Key in: header description: >- This backend API key is different than your frontend license key. Please use the "Backend" license key from your [Dromo Dashboard](https://dashboard.dromo.io/). ````