---
title: "Upload a new file"
method: POST
path: "/v1/org/{orgId}/file"
tags: ["file"]
---

# Upload a new file

`POST /v1/org/{orgId}/file`

## Path parameters

- `orgId` string, required

## Query parameters

- `entityId` string
- `entityType` string
- `fieldId` string
- `sensitive` string
- `uploadPersonId` string
- `uploadAt` string

## Response `201`

File created

- FileEntity
  - `id` string, required — globally unique id of file
  - `orgId` string, required — parent org id
  - `entityId` string, required — entity id that the file is attached to
  - `entityType` 'ACTION' | 'AGREEMENT' | 'AI_AGENT' | 'AI_AGENT_MEMORY' | 'AI_CHAT' | 'AI_CONFIG' | 'AI_CREDIT_LIMIT' | 'AI_CREDIT_USAGE' | 'AI_HINT' | 'AI_PROMPT' | 'APP' | 'APP_CONFIG' | 'APPROVAL_CHAIN' | 'APPROVAL_CHAIN_STAGE' | 'APPROVAL_DELEGATE' | 'APPROVAL_REQUEST' | 'ASSESSMENT' | 'BUDGET' | 'BUDGET_POOL' | 'BUNDLE' | 'CALENDAR' | 'CALENDAR_ENTRY' | 'CATEGORY' | 'CATEGORY_SORT' | 'CHANGE' | 'COMMENT' | 'COMP_BAND' | 'COMP_REVIEW' | 'CONTENT' | 'CUSTOMER' | 'DATA_VIEW' | 'EXCHANGE_RATE' | 'EMAIL_TEMPLATE' | 'EVENT' | 'FIELD' | 'FILE' | 'FORM' | 'FORM_DRAFT' | 'FORM_RESPONSE' | 'GEOCODE' | 'GROUP' | 'GROUP_ALLOCATION' | 'GROUP_TYPE' | 'GOAL' | 'GOAL_PROGRESS' | 'GOAL_TARGET' | 'GOAL_TYPE' | 'GUIDELINE' | 'JOB' | 'JOB_CODE' | 'JOB_LEVEL' | 'MEDIA' | 'MESSAGE' | 'MULTIPLIER' | 'ORG' | 'ORG_CONFIG' | 'PERSON' | 'PROFILE_TAB' | 'POLICY' | 'PROCESS' | 'PRODUCT' | 'QUERY_TOKEN' | 'QUESTION' | 'REPORT' | 'REPORT_CHART' | 'ROLE' | 'SCENARIO' | 'SIGNATURE' | 'SIGNATURE_REQUEST' | 'STOCK_GRANT' | 'STOCK_PRICE' | 'TABLE' | 'TABLE_ROW' | 'TASK_CONFIG' | 'TEMPLATE' | 'TASK' | 'TOKEN' | 'TIMEOFF' | 'TIMEOFF_BALANCE_ADJUSTMENT' | 'TIMEOFF_LEDGER_ENTRY' | 'TIMEOFF_POLICY' | 'TRANSCRIPT' | 'USER', required — entity type (should only be PERSON, USER, CONTENT, or ORG)
  - `fieldId` string — field that the file uses, if the file is tied to a field
  - `hash` string — SHA-256 hash of the contents of the file
  - `templateId` string — for files that were generated from a template, the template that was used
  - `formResponseId` string — for files that were generated from a form response, the form response that was used
  - `signatureStatus` 'PENDING' | 'SIGNED' — for files that contain a signature or signature request, information about the status of that signature. The presence of this does not automatically imply a SignatureRequest exists, because the file can be imported from another system
  - `signerUserIds` string[] — for files that were signed or attempted to sign in ChartHop, the list of users who signed or were requested to sign
  - `sensitive` 'GLOBAL' | 'ORG' | 'SENSITIVE' | 'PERSONAL' | 'MANAGER' | 'HIGH' | 'PRIVATE' — level of sensitivity of the file, if the file is not tied to a field
  - `filename` string, required — customer facing filename of file
  - `originalFilename` string, required — original filename of file
  - `type` string, required — mime type of file
  - `ext` string, required — extension of file
  - `bytes` integer, required — size of file in bytes
  - `createId` string — created by user id
  - `createBehalfId` string — created on behalf of user id
  - `createAttribution` Attribution
    - `principalUserId` string
    - `agentUserIds` string[]
    - `eventId` string
    - `aiChatId` string
    - `aiToolUseId` string
    - `channel` 'WEB' | 'MOBILE' | 'SLACK' | 'TEAMS' | 'MCP'
  - `createAt` string — created timestamp
  - `updateId` string — updated by user id
  - `updateBehalfId` string — last updated on behalf of user id
  - `updateAttribution` Attribution
    - `principalUserId` string
    - `agentUserIds` string[]
    - `eventId` string
    - `aiChatId` string
    - `aiToolUseId` string
    - `channel` 'WEB' | 'MOBILE' | 'SLACK' | 'TEAMS' | 'MCP'
  - `updateAt` string — updated timestamp
  - `deleteId` string — deleted by user id
  - `deleteBehalfId` string — deleted on behalf of user id
  - `deleteAttribution` Attribution
    - `principalUserId` string
    - `agentUserIds` string[]
    - `eventId` string
    - `aiChatId` string
    - `aiToolUseId` string
    - `channel` 'WEB' | 'MOBILE' | 'SLACK' | 'TEAMS' | 'MCP'
  - `deleteAt` string — deleted timestamp
  - `uploadPersonId` string — uploaded by person id
  - `uploadAt` string — timestamp that the file was uploaded
  - `pageCount` integer — number of pages (PDF), slides (PPTX), or sheets (XLSX/XLS) in the file. Null for formats without a page concept or when not yet computed.
  - `lineCount` integer — number of lines in the file, for line-oriented text formats (CSV, TXT, JSON, MD, HTML). Null for formats without a line concept or when not yet computed.
  - `metadata` object — Optional metadata about the file

## Other responses

- `400` — Invalid type or bad request
- `401` — Not authorized

---

[API](https://skmtc.net/charthop/apis/charthop-api.md) · [All operations](https://skmtc.net/charthop/apis/charthop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/charthop/charthop-api/revisions/50a1edd6b27e/schema)