# Import objects

Import multiple objects in batch. Properties are keyed by slug. Automatically routes based on size: small batches complete synchronously and return 200 with the final `ImportJob`; large batches start an async job, return 202 with `status: processing` and a `Location` header, and can be polled via `GET /v2/prism/{teamId}/imports/{jobId}`.

**Endpoint:** `POST /v2/prism/{teamId}/{objectType}/import`  
**Operation ID:** `importObjects`  
**Server:** `https://developers.micro.so`  
**Security:** `[{"apiKey":[]}]`

## Parameters

```json
[
  {
    "name": "teamId",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  {
    "name": "objectType",
    "in": "path",
    "required": true,
    "schema": {
      "$ref": "#/components/schemas/ImportObjectType"
    }
  },
  {
    "$ref": "#/components/parameters/IdempotencyKey"
  }
]
```

## Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ImportRequest"
      }
    }
  }
}
```

## Responses

```json
{
  "200": {
    "description": "Import complete (sync path for small batches). `status` is `complete`, `job_id` is null, and per-row outcomes are inlined under `results`.",
    "headers": {
      "x-request-id": {
        "$ref": "#/components/headers/XRequestId"
      },
      "idempotent-replay": {
        "$ref": "#/components/headers/IdempotentReplay"
      }
    },
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ImportJob"
        }
      }
    }
  },
  "202": {
    "description": "Import accepted for async processing. Poll `GET /v2/prism/{teamId}/imports/{job_id}` (also available via the `Location` header) until `status` is `complete` or `failed`.",
    "headers": {
      "x-request-id": {
        "$ref": "#/components/headers/XRequestId"
      },
      "idempotent-replay": {
        "$ref": "#/components/headers/IdempotentReplay"
      },
      "Location": {
        "$ref": "#/components/headers/Location"
      }
    },
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ImportJob"
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "409": {
    "$ref": "#/components/responses/Conflict"
  },
  "500": {
    "$ref": "#/components/responses/InternalError"
  }
}
```

## Referenced components

```json
{
  "securitySchemes": {
    "apiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "x-api-key",
      "description": "Public API key generated from Micro settings. Sent as the `x-api-key` header and validated by AWS API Gateway in front of the service."
    }
  },
  "schemas": {
    "ImportObjectType": {
      "type": "string",
      "enum": [
        "comment",
        "identity",
        "organization",
        "contact",
        "action",
        "document",
        "engagement",
        "deal"
      ]
    },
    "ImportRequest": {
      "type": "object",
      "required": [
        "objects"
      ],
      "properties": {
        "objects": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/PrismObjectProperties"
          },
          "description": "Array of objects to import with property values keyed by slug"
        },
        "options": {
          "type": "object",
          "properties": {
            "dedupe_by": {
              "description": "Property slug to deduplicate on. A single-element array is also accepted; compound (multi-slug) dedupe is not supported yet and is rejected with guidance.",
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "caseInsensitive": {
              "type": "boolean",
              "default": true,
              "description": "Whether deduplication should be case insensitive"
            },
            "list_id": {
              "type": "string",
              "format": "uuid",
              "description": "App/CRM ID for context (optional)"
            },
            "create_missing_options": {
              "type": "boolean",
              "default": false,
              "description": "When true, unknown values for select/multiselect properties are created as new options instead of failing the import"
            },
            "update_existing": {
              "type": "boolean",
              "default": false,
              "description": "Patch a deduplicated record with the supplied properties instead of skipping it."
            },
            "require_list_stage": {
              "type": "boolean",
              "default": false,
              "description": "Require app_stage for every row in the selected list. app_stage is a reserved list-scoped alias for native status."
            },
            "crm_id": {
              "type": "string",
              "format": "uuid",
              "deprecated": true,
              "description": "Deprecated alias for list_id."
            }
          },
          "additionalProperties": false
        }
      }
    },
    "ImportJob": {
      "type": "object",
      "description": "Status snapshot of an import job. Same shape used by the POST /import response and by GET /imports/{jobId}.",
      "required": [
        "job_id",
        "status",
        "total"
      ],
      "properties": {
        "job_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Null for sync imports (results inlined). Set for async imports."
        },
        "status": {
          "type": "string",
          "enum": [
            "complete",
            "processing",
            "failed"
          ]
        },
        "total": {
          "type": "integer",
          "description": "Total number of rows in the import."
        },
        "processed": {
          "type": "integer",
          "description": "Rows that have been attempted (succeeded + failed)."
        },
        "succeeded": {
          "type": "integer"
        },
        "failed": {
          "type": "integer"
        },
        "results": {
          "type": "array",
          "description": "Per-row outcomes. Always present for sync imports; populated for async imports once the job reaches `complete`.",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid"
              },
              "created": {
                "type": "boolean"
              },
              "existing": {
                "type": "boolean",
                "description": "True if the row matched an existing record via the dedupe key."
              },
              "updated": {
                "type": "boolean",
                "description": "True if a matching record was updated."
              },
              "input_index": {
                "type": "integer",
                "minimum": 0,
                "description": "Zero-based position of this row in the request."
              },
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "error": {
          "type": "object",
          "description": "Set when status=failed; describes the job-level failure (not per-row).",
          "properties": {
            "code": {
              "type": "string"
            },
            "message": {
              "type": "string"
            }
          }
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "expires_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "PrismObjectProperties": {
      "type": "object",
      "properties": {
        "extended": {
          "type": "object",
          "minProperties": 1
        },
        "default": {
          "type": "object",
          "description": "Properties keyed by property slug. Values can be strings, numbers, booleans, arrays, or null. For select/multiselect properties, values may be option slugs or option UUIDs on write; option slugs are returned on read.",
          "minProperties": 1,
          "additionalProperties": {}
        },
        "list": {
          "type": "object",
          "minProperties": 1,
          "patternProperties": {
            "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$": {
              "type": "object",
              "description": "Properties keyed by property slug",
              "minProperties": 1,
              "additionalProperties": {}
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false,
      "anyOf": [
        {
          "required": [
            "default"
          ]
        },
        {
          "required": [
            "list"
          ]
        }
      ]
    },
    "Error": {
      "type": "object",
      "description": "Canonical JSON error envelope for every non-2xx v2 API response. `error.code` is the machine-readable error code, `error.message` is the human-readable summary, and `error.request_id` identifies the request for support. When supplied, `error.errors` contains field-level validation issues.",
      "required": [
        "error"
      ],
      "properties": {
        "error": {
          "type": "object",
          "required": [
            "code",
            "message",
            "request_id"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Stable machine-readable code. Branch on this, not on the HTTP status, to handle specific failure modes.",
              "example": "invalid_request"
            },
            "message": {
              "type": "string",
              "description": "Human-readable summary suitable for logs. Not localized; do not display verbatim to end users."
            },
            "request_id": {
              "type": [
                "string",
                "null"
              ],
              "description": "Echo of the x-request-id response header. Include in support requests."
            },
            "errors": {
              "type": "array",
              "description": "Optional structured field-level validation issues when the server provides them.",
              "items": {
                "type": "object",
                "properties": {
                  "field": {
                    "type": "string",
                    "description": "JSON path of the offending property (e.g. \".body.default.email\")."
                  },
                  "message": {
                    "type": "string"
                  },
                  "code": {
                    "type": "string",
                    "description": "Validator-specific code (e.g. \"required.openapi.validation\")."
                  }
                },
                "required": [
                  "message"
                ]
              }
            },
            "details": {
              "type": "object",
              "description": "Optional bag of error-specific context. Shape varies by code; clients should treat fields as opaque unless documented."
            }
          }
        }
      }
    }
  },
  "parameters": {
    "IdempotencyKey": {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "A unique key (UUID or any opaque string up to 255 chars) for an authenticated POST, PUT, or PATCH request. The server retains the initial claim for 24 hours and replays a completed non-5xx response only when the method, path, and request body all match. Reusing a non-expired key with a different method, path, or body returns 409 `idempotency_key_mismatch`; reusing it after expiry returns 409 `idempotency_key_stale`, so use a new key. Replays include the `idempotent-replay: true` response header.",
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 255
      }
    }
  },
  "headers": {
    "XRequestId": {
      "description": "Correlation ID. Echoed from the request `x-request-id` header when supplied, otherwise generated. Include in support requests.",
      "schema": {
        "type": "string"
      }
    },
    "IdempotentReplay": {
      "description": "Present and set to `true` when this response is a cached replay of an earlier request with the same `Idempotency-Key`. Absent on first execution.",
      "schema": {
        "type": "string",
        "enum": [
          "true"
        ]
      }
    },
    "Location": {
      "description": "URL of the resource created or whose status can be polled.",
      "schema": {
        "type": "string"
      }
    }
  },
  "responses": {
    "BadRequest": {
      "description": "Request validation failed. Inspect `error.errors` for field-level details.",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/XRequestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "Unauthorized": {
      "description": "Missing or invalid credentials. API Gateway maps a missing or invalid `x-api-key` to HTTP 401 with this envelope (including `request_id`). A 403 here means the key was accepted but the caller is not permitted.",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/XRequestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "Forbidden": {
      "description": "Authenticated but not permitted to perform this action.",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/XRequestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "Conflict": {
      "description": "Request conflicts with current state (e.g., duplicate or stale write).",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/XRequestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "InternalError": {
      "description": "Unexpected server error. Retry with backoff; report `request_id` if persistent.",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/XRequestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```