> ## Documentation Index
> Fetch the complete documentation index at: https://developer.uphold.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create file
> Create a new file.
export const RestEndpointSubjects = ({subjects = []}) => {
const subjectToIconMap = {
'client': 'browser',
'user:individual': 'user',
'user:business': 'briefcase'
};
if (subjects.length === 0) {
return null;
}
return <>
{subjects.map(subject =>
{subject}
)}
;
};
Uploading a file is a two step process. You start by creating a placeholder for the file and then using the `upload` details of the response to actually upload the file. Each file has a unique `id` which is used across the API when you need to reference it.
You can optionally include custom [entity metadata](../../entity-metadata) in the `metadata` field to store your own business data (e.g., descriptions, related entity IDs, processing metadata). If not provided during creation, you can add it later using [Set metadata](../metadata/set-metadata).
Below you will find examples in several programming languages to do the upload:
The following example uses [`file-type`](https://www.npmjs.com/package/file-type) package to determine the content-type of the file.
```js theme={null}
import { fileTypeFromFile } from 'file-type';
import fs from 'node:fs';
// Function to upload file.
// Takes `file` record from the response and `filePath` which points to the file on disk that needs to be uploaded.
const uploadFile = async (file, filePath) => {
const { url, formData } = file.upload;
// Add form data.
const form = new FormData();
for (const [key, value] of Object.entries(formData)) {
form.append(key, value);
}
// Add content type, determined by file-type package.
// This must match the `contentType` of the file record.
const { mime } = await fileTypeFromFile(filePath);
form.append('Content-Type', mime);
// Add file blob.
const blob = await fs.openAsBlob(filePath)
form.append('File', blob);
const response = await fetch(url, {
method: 'POST',
body: form,
});
if (!response.ok) {
throw new Error(`Failed to upload file: ${response.statusText}`);
}
console.log('File uploaded!')
};
```
## OpenAPI
````yaml _media/specs/core-openapi.mintlify.json post /core/files
openapi: 3.1.0
info:
version: 0.1.0
title: Core API
description: >-
The Core API provides essential building blocks that empower businesses to
embed financial services into their applications.
contact:
name: Uphold API Team
email: developers@uphold.com
url: https://developer.uphold.com
servers:
- url: https://api.enterprise.sandbox.uphold.com
description: Sandbox
- url: https://api.enterprise.uphold.com
description: Production
security:
- OAuth2: []
tags:
- name: Authentication
description: Authentication.
- name: Countries
description: Countries.
- name: Users
description: Users.
- name: KYC
description: Individual User's KYC.
- name: KYB
description: Business User's KYB.
- name: Capabilities
description: User capabilities.
- name: Terms of service
description: User terms of service.
- name: Files
description: Files.
- name: Assets
description: Assets, networks and rails.
- name: Accounts
description: Accounts.
- name: External accounts
description: External accounts.
- name: Transactions
description: Transactions.
- name: Portfolio
description: Portfolio.
- name: Statements
description: Statements.
- name: Metadata
description: Metadata.
- name: Webhooks
description: Webhooks.
paths:
/core/files:
post:
tags:
- Files
summary: Create file
description: Create a new file.
operationId: core.create-file
requestBody:
$ref: '#/components/requestBodies/create-file-request-body'
responses:
'201':
$ref: '#/components/responses/create-file-response'
'409':
$ref: '#/components/responses/create-file-conflict-response'
security:
- OAuth2:
- core.files:create
components:
requestBodies:
create-file-request-body:
content:
application/json:
schema:
type: object
properties:
category:
description: The category of the file.
type: string
enum:
- document
- image
- video
contentType:
description: The content type of the file.
type: string
maxLength: 100
metadata:
$ref: '#/components/schemas/metadata'
description: Additional data for the file.
required:
- category
- contentType
examples:
Create File:
value:
category: image
contentType: image/png
metadata:
externalId: 123
responses:
create-file-response:
description: File created.
content:
application/json:
schema:
type: object
properties:
file:
$ref: '#/components/schemas/file-for-upload'
errors:
description: >-
Additional contextual errors that occurred while processing
the request.
type: object
properties:
metadata:
allOf:
- $ref: '#/components/schemas/error'
- description: Error related to metadata processing.
required:
- file
examples:
File Created:
value:
file:
id: 38cce774-b225-41ed-a9fd-f9c9777a13de
status: pending
category: image
contentType: image/png
upload:
url: https://example.com/upload
formData:
X-Amz-Algorithm: AWS4-HMAC-SHA256
X-Amz-Credential: ASIE4FQORBNQHNQD5CG6/20240801/us-east-1/s3/aws4_request
X-Amz-Date: 20240801T102500Z
X-Amz-Security-Token: IQoJb3JpZ2luX2VjEIv//////////...JBr6h2HkzH/aFSArQcs=
X-Amz-Signature: >-
b4da8cf1a59327988a8108c965a4789fc8ba2d20f5bffda076106b2b254def29
Key: 4c13b6f5-987e-43df-bc12-042b58307a80
Policy: eyJjb25kaXRpb25zIjpbeyJidWN...TA6MjU6MDAuMjAyWiJ9
expiresAt: '2024-03-13T20:20:39.000Z'
File Created With Metadata Error:
value:
file:
id: 38cce774-b225-41ed-a9fd-f9c9777a13de
status: pending
category: image
contentType: image/png
upload:
url: https://example.com/upload
formData:
X-Amz-Algorithm: AWS4-HMAC-SHA256
X-Amz-Credential: ASIE4FQORBNQHNQD5CG6/20240801/us-east-1/s3/aws4_request
X-Amz-Date: 20240801T102500Z
X-Amz-Security-Token: IQoJb3JpZ2luX2VjEIv//////////...JBr6h2HkzH/aFSArQcs=
X-Amz-Signature: >-
b4da8cf1a59327988a8108c965a4789fc8ba2d20f5bffda076106b2b254def29
Key: 4c13b6f5-987e-43df-bc12-042b58307a80
Policy: eyJjb25kaXRpb25zIjpbeyJidWN...TA6MjU6MDAuMjAyWiJ9
expiresAt: '2024-03-13T20:20:39.000Z'
errors:
metadata:
code: content_too_large
message: >-
The entity metadata size is greater than maximum size
limit
details:
threshold:
unit: characters
limit: 1024
headers:
x-uphold-request-id:
description: >-
A unique identifier for the request that can be shared with Uphold
for troubleshooting purposes.
required: true
schema:
type: string
format: uuid
examples:
Request ID:
value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
create-file-conflict-response:
description: Business logic error.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
File Content Type Not Allowed:
value:
code: file_content_type_not_allowed
message: >-
The file content type is not allowed for the specified
category
Max Files Limit Exceeded:
value:
code: max_files_limit_exceeded
message: The maximum number of allowed files has been exceeded
headers:
x-uphold-request-id:
description: >-
A unique identifier for the request that can be shared with Uphold
for troubleshooting purposes.
required: true
schema:
type: string
format: uuid
examples:
Request ID:
value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
schemas:
metadata:
type: object
additionalProperties: true
minProperties: 1
file-for-upload:
allOf:
- $ref: '#/components/schemas/file-base'
- type: object
properties:
upload:
description: The upload information of the file.
type: object
properties:
url:
description: The pre-signed URL to upload the file to.
type: string
format: uri
formData:
description: The form data to include when uploading the file.
type: object
additionalProperties:
type: string
expiresAt:
description: The date and time when the upload URL expires.
type: string
format: date-time
required:
- url
- formData
- expiresAt
required:
- upload
error:
description: The error information.
allOf:
- $ref: '#/components/schemas/feedback'
file-base:
type: object
properties:
id:
description: The id of the file.
type: string
format: uuid
status:
description: The status of the file.
type: string
enum:
- pending
- uploaded
category:
description: The category of the file.
type: string
contentType:
description: The content type of the file.
type: string
required:
- id
- status
- category
- contentType
feedback:
description: A feedback message with a code and human-readable description.
type: object
properties:
code:
description: A short string with a brief explanation about the code reported.
type: string
message:
description: A human-readable message providing more details.
type: string
details:
description: Additional information about the feedback reported.
type: object
additionalProperties: true
required:
- code
- message
securitySchemes:
OAuth2:
type: oauth2
description: OAuth 2.0 authentication.
flows:
clientCredentials:
tokenUrl: /core/oauth2/token
scopes:
core.users:act-on-behalf-of: Grants access to act on behalf of a user
core.users:create: Grants access to create users
core.users:read: Grants access to view users
core.users:delete: Grants access to delete users
core.users.metadata:read: Grants access to view user metadata
core.users.metadata:write: Grants access to modify user metadata
core.kyc:read: Grants access to view KYC processes
core.kyc.profile:update: Grants access to update profile KYC process
core.kyc.address:update: Grants access to update address KYC process
core.kyc.email:update: Grants access to update email KYC process
core.kyc.phone:update: Grants access to update phone KYC process
core.kyc.identity:update: Grants access to update identity KYC process
core.kyc.proof-of-address:update: Grants access to update proof-of-address KYC process
core.kyc.customer-due-diligence:update: Grants access to update customer due diligence KYC process
core.kyc.enhanced-due-diligence:update: Grants access to update enhanced due diligence KYC process
core.kyc.crypto-risk-assessment:update: Grants access to update crypto risk assessment KYC process
core.kyc.self-categorization-statement:update: Grants access to update self-categorization statement KYC process
core.kyc.tax-details:update: Grants access to update tax details KYC process
core.capabilities:read: Grants access to view user capabilities
core.terms-of-service:read: Grants access to view terms of service
core.terms-of-service:accept: Grants access to accept terms of service
core.files:create: Grants access to create files
core.files:read: Grants access to view files
core.files.metadata:read: Grants access to view files metadata
core.files.metadata:write: Grants access to modify files metadata
core.accounts:create: Grants access to create accounts
core.accounts:read: Grants access to view accounts
core.accounts:update: Grants access to update accounts
core.accounts:archive: Grants access to archive accounts
core.accounts:deposit-method: >-
Grants access to deposit method needed for depositing into
accounts
core.accounts:use-test-helpers: Grants access to test helpers of accounts
core.accounts.metadata:read: Grants access to view accounts metadata
core.accounts.metadata:write: Grants access to modify accounts metadata
core.assets:use-test-helpers: Grants access to test helpers of assets
core.external-accounts:create: Grants access to create external accounts
core.external-accounts:read: Grants access to view external accounts
core.external-accounts:update: Grants access to update external accounts
core.external-accounts:delete: Grants access to delete external accounts
core.external-accounts.metadata:read: Grants access to view external accounts metadata
core.external-accounts.metadata:write: Grants access to modify external accounts metadata
core.transactions:create: Grants access to commit quotes
core.transactions:read: Grants access to view transactions
core.transactions.metadata:read: Grants access to view transactions metadata
core.transactions.metadata:write: Grants access to modify transactions metadata
core.transactions.requests-for-information:read: Grants access to view transactions requests for information
core.transactions.requests-for-information:update: Grants access to update transactions requests for information
core.portfolio:read: >-
Grants access to view portfolio overview, performance, and
historical balance
core.statements:read: Grants access to read statements
core.webhooks:management-link: Grants access to create webhook management links
````