> ## Documentation Index > Fetch the complete documentation index at: https://docs.roofkit.ai/llms.txt > Use this file to discover all available pages before exploring further. # Import object records > Imports CSV into a custom object. Create-field mappings also need data_objects.schema.manage. Contacts and Reports reject import. **Required scopes:** `data_objects.import` ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/v1/objects/{object_id}/import openapi: 3.1.0 info: title: RoofKit Partner API version: 1.0.0 summary: REST JSON API for external RoofKit partner integrations. contact: name: RoofKit Engineering description: > RoofKit Partner API v1 authenticates requests with workspace API keys. API keys bind each request to exactly one workspace; Partner API paths do not accept roofer_id, workspace_id, or tenant identifiers. Authenticated endpoints are limited to 60 requests per minute per API key, method, and route template; invalid authentication attempts are limited separately at 20 requests per minute per client and endpoint. Date-time parameters and fields accept ISO 8601 with Z or a ±HH:MM offset, for example 2026-09-07T04:00:00Z or 2026-09-07T00:00:00-04:00. Both name the same instant and return the same result. Encode + as %2B in a query string. Responses return UTC. A date-time without an offset, for example 2026-09-07T04:00:00, is deprecated. Until the sunset on 2027-01-10T00:00:00Z it is read as UTC, and the response carries a `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594). From the sunset, Z or a ±HH:MM offset is required. A date-time without an offset then returns 400 with the `VALIDATION_ERROR` code, and the response carries no `Deprecation` or `Sunset` header. Each API key holds only the scopes that a workspace owner or admin chose when the key was created, and its scopes never change. Each operation lists the scopes it requires in `x-required-scopes`. A new key in Settings starts on the Read-only preset: `leads.read`, `analytics.read`, `reports.read`, and `data_objects.read`. A Read-only key can call every read operation except exports, Sales Visualizer reads, and trashed Data Objects, and it cannot call any write operation. A call that needs a scope the key does not hold returns 403 `FORBIDDEN`, and `error.details.required_scope` names a missing scope. servers: - url: https://api.roofkit.ai description: Canonical RoofKit Partner API origin security: - ApiKeyBearer: [] tags: - name: Foundation description: Authentication and contract foundation endpoints. - name: Leads description: Partner CRM lead sync endpoints. - name: Attribution description: >- Partner marketing attribution, campaign analytics, and event ingestion endpoints. - name: Pipeline description: Partner-readable lead pipeline metadata. - name: Reports description: Partner report import, listing, fetch, export, and download endpoints. - name: Visualizer description: >- Partner Sales Visualizer creation, generation, hosted photo upload links, image reads, session history, and share-link endpoints. - name: Estimates description: Partner Budget Estimate creation and reads for the key-bound workspace. - name: Objects description: >- Partner Data Objects discovery, schema, records, relations, views, and admin endpoints. paths: /api/v1/objects/{object_id}/import: post: tags: - Objects summary: Import object records description: >- Imports CSV into a custom object. Create-field mappings also need data_objects.schema.manage. Contacts and Reports reject import. operationId: Import object records parameters: - $ref: '#/components/parameters/ObjectId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ObjectImportWrite' responses: '200': description: Import completed. headers: Idempotency-Replayed: $ref: '#/components/headers/IdempotencyReplayed' content: application/json: schema: $ref: '#/components/schemas/ObjectImportResponse' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: parameters: ObjectId: name: object_id in: path required: true description: Object id, system key such as system:leads, or slug from discovery. x-docs-test-value: system:leads schema: type: string minLength: 1 maxLength: 200 IdempotencyKey: name: Idempotency-Key in: header required: true description: >- A unique value for each new request, such as a UUID. Send the same value to retry a request safely. The same key and payload replay the first response with `Idempotency-Replayed: true`. schema: type: string minLength: 1 maxLength: 160 schemas: ObjectImportWrite: type: object additionalProperties: false required: - file_name - csv_content - mappings properties: file_name: type: string maxLength: 200 csv_content: type: string mappings: type: array items: type: object additionalProperties: true required: - csv_column - action properties: csv_column: type: string action: type: string enum: - field - create_field - ignore field_id: type: string label: type: string field_type: type: string ObjectImportResponse: type: object additionalProperties: false required: - job_id - created_count - rejected_rows properties: job_id: type: string created_count: type: integer rejected_rows: type: array items: type: object additionalProperties: true ErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - message - request_id properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string request_id: type: string details: type: object additionalProperties: true ErrorCode: type: string enum: - UNAUTHORIZED - FORBIDDEN - RATE_LIMITED - VALIDATION_ERROR - NOT_FOUND - CONFLICT - INSUFFICIENT_CREDITS - INTERNAL_ERROR headers: IdempotencyReplayed: description: Present and true when a stored successful write response was replayed. schema: type: string enum: - 'true' RateLimitLimit: description: Maximum requests allowed in the current window. schema: type: string RateLimitRemaining: description: Requests remaining in the current window. schema: type: string RateLimitReset: description: ISO timestamp when the current rate-limit window resets. schema: type: string format: date-time RetryAfter: description: Seconds until the caller should retry. schema: type: string responses: ValidationError: description: Request payload, query, or required header is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Missing, malformed, revoked, deleted, or unknown API key. headers: WWW-Authenticate: schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: >- The API key lacks a required scope, or the workspace is not active. A scope failure names a missing scope in `details.required_scope`. When the key lookup refuses the call, `details.missing_scopes` lists every required scope that the key does not hold. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_scope: summary: A Read-only key calls a write operation value: error: code: FORBIDDEN message: 'API key does not include the required scope: leads.write.' request_id: req_123 details: required_scope: leads.write missing_scopes: - leads.write NotFound: description: Resource not found in the key-bound workspace. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Conflict: description: Request conflicts with idempotency or external event identity. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' RateLimited: description: Rate limit exceeded for this key and endpoint or invalid-auth bucket. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalError: description: Internal authentication or server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ApiKeyBearer: type: http scheme: bearer bearerFormat: RoofKit API key description: 'Use `Authorization: Bearer rk_live_...`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.