Uphold Files API

openapi: 3.2.0
info:
  version: 0.1.0
  title: Core Files 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: Files
  description: Files.
paths:
  /core/files:
    post:
      operationId: core.create-file
      summary: Create file
      description: Create a new file.
      tags:
      - Files
      x-uphold:
        security:
          OAuth2:
            subjects:
            - user:business
            - user:individual
      security:
      - OAuth2:
        - core.files:create
      parameters:
      - $ref: '#/components/parameters/x-on-behalf-of'
      - $ref: '#/components/parameters/x-uphold-user-ip'
      - $ref: '#/components/parameters/x-uphold-user-agent'
      - $ref: '#/components/parameters/x-uphold-user-origin'
      - $ref: '#/components/parameters/x-uphold-user-country'
      - $ref: '#/components/parameters/x-uphold-user-subdivision'
      - $ref: '#/components/parameters/x-uphold-user-city'
      requestBody:
        $ref: '#/components/requestBodies/create-file-request-body'
      responses:
        '201':
          $ref: '#/components/responses/create-file-response'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '409':
          $ref: '#/components/responses/create-file-conflict-response'
        '429':
          $ref: '#/components/responses/too-many-requests'
  /core/files/{fileId}:
    get:
      operationId: core.get-file
      summary: Get file
      description: Retrieve an existing file by id.
      tags:
      - Files
      x-uphold:
        security:
          OAuth2:
            subjects:
            - user:business
            - user:individual
      security:
      - OAuth2:
        - core.files:read
      parameters:
      - $ref: '#/components/parameters/file-id'
      - $ref: '#/components/parameters/x-on-behalf-of'
      - $ref: '#/components/parameters/x-uphold-user-ip'
      - $ref: '#/components/parameters/x-uphold-user-agent'
      - $ref: '#/components/parameters/x-uphold-user-origin'
      - $ref: '#/components/parameters/x-uphold-user-country'
      - $ref: '#/components/parameters/x-uphold-user-subdivision'
      - $ref: '#/components/parameters/x-uphold-user-city'
      responses:
        '200':
          $ref: '#/components/responses/get-file-response'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/get-file-not-found-response'
        '429':
          $ref: '#/components/responses/too-many-requests'
  /core/files/settings:
    get:
      operationId: core.list-files-settings
      summary: List files settings
      description: List files upload settings.
      tags:
      - Files
      x-uphold:
        security:
          OAuth2:
            subjects:
            - client
            - user:business
            - user:individual
      security:
      - OAuth2:
        - core.files:read
      parameters:
      - $ref: '#/components/parameters/list-files-settings-file-category-filter'
      - $ref: '#/components/parameters/x-uphold-user-ip'
      - $ref: '#/components/parameters/x-uphold-user-agent'
      - $ref: '#/components/parameters/x-uphold-user-origin'
      - $ref: '#/components/parameters/x-uphold-user-country'
      - $ref: '#/components/parameters/x-uphold-user-subdivision'
      - $ref: '#/components/parameters/x-uphold-user-city'
      responses:
        '200':
          $ref: '#/components/responses/get-files-settings-response'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too-many-requests'
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:
                description: Additional data for the file.
                $ref: '#/components/schemas/metadata'
            required:
            - category
            - contentType
          examples:
            Create File:
              value:
                category: image
                contentType: image/png
                metadata:
                  externalId: 123
  parameters:
    x-on-behalf-of:
      name: X-On-Behalf-Of
      description: The subject on whose behalf the operation is being performed.
      in: header
      schema:
        type: string
        pattern: ^(user|client)\s[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$
      examples:
        User Identifier:
          value: user cd21b26d-35d2-408a-9201-b8fdbef7a604
        Client Identifier:
          value: client 3fa85f64-5717-4562-b3fc-2c963f66afa6
    list-files-settings-file-category-filter:
      name: category
      in: query
      description: Filter settings by file category (e.g., image).
      explode: false
      schema:
        type: array
        maxItems: 3
        uniqueItems: true
        items:
          type: string
          enum:
          - document
          - image
          - video
      examples:
        Filter by Image:
          value:
          - image
    x-uphold-user-subdivision:
      name: X-Uphold-User-Subdivision
      description: Contains the code of the subdivision of the end user that is requesting the operation.
      in: header
      schema:
        $ref: '#/components/schemas/subdivision-code-for-request'
      examples:
        User Subdivision:
          value: US-CA
    x-uphold-user-ip:
      name: X-Uphold-User-Ip
      description: Contains the IP of the end user that is requesting the operation.
      in: header
      schema:
        oneOf:
        - title: IPv4
          type: string
          format: ipv4
        - title: IPv6
          type: string
          format: ipv6
      examples:
        User Ip:
          value: 47.174.97.164
    file-id:
      name: fileId
      description: The file id.
      in: path
      required: true
      schema:
        type: string
        format: uuid
      examples:
        File ID:
          value: 38cce774-b225-41ed-a9fd-f9c9777a13de
    x-uphold-user-country:
      name: X-Uphold-User-Country
      description: Contains the code of the country of the end user that is requesting the operation.
      in: header
      schema:
        $ref: '#/components/schemas/country-code-for-request'
      examples:
        User Country:
          value: US
    x-uphold-user-city:
      name: X-Uphold-User-City
      description: Contains the name of the city of the end user that is requesting the operation.
      in: header
      schema:
        $ref: '#/components/schemas/string-no-edge-spaces'
      examples:
        User City:
          value: San Francisco
    x-uphold-user-agent:
      name: X-Uphold-User-Agent
      description: Contains the user agent of the end user that is requesting the operation.
      in: header
      schema:
        $ref: '#/components/schemas/string-no-edge-spaces'
      examples:
        User Agent:
          value: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36
    x-uphold-user-origin:
      name: X-Uphold-User-Origin
      description: Contains the origin of the request made by the end user.
      in: header
      schema:
        $ref: '#/components/schemas/string-no-edge-spaces'
      examples:
        Origin:
          value: https://uphold.com
  responses:
    get-files-settings-response:
      description: File settings retrieved.
      content:
        application/json:
          schema:
            type: object
            properties:
              settings:
                $ref: '#/components/schemas/files-settings'
            required:
            - settings
          examples:
            Settings List Retrieved:
              value:
                settings:
                  document:
                    allowedContentTypes:
                    - application/pdf
                    - image/jpeg
                    - image/png
                    maxFileSize: 25000000
                    minFileSize: 1
                    expiresIn: 900
                  image:
                    allowedContentTypes:
                    - image/jpeg
                    - image/png
                    maxFileSize: 15000000
                    minFileSize: 1
                    expiresIn: 900
                  video:
                    allowedContentTypes:
                    - video/mp4
                    - video/mpeg
                    maxFileSize: 100000000
                    minFileSize: 1
                    expiresIn: 900
            Image Settings Retrieved:
              value:
                settings:
                  image:
                    allowedContentTypes:
                    - image/jpeg
                    - image/png
                    maxFileSize: 15000000
                    minFileSize: 1
                    expiresIn: 900
      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
    bad-request:
      description: Bad Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Invalid Request:
              value:
                code: request_invalid
                message: The request has missing or invalid parameters
                details:
                  context: <context>
                  violations:
                  - property: <property>
                    rule: required
                  - property: <property>
                    rule: type
                    ruleParams:
                      type: string
      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
    forbidden:
      description: Forbidden.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Token Insufficient Scopes:
              value:
                code: token_insufficient_scopes
                message: Authorization failed due to insufficient scopes
                details:
                  security:
                  - scheme: OAuth
                    schemeScopes:
                    - required:scope_1
                    - required:scope_2
                    tokenScopes:
                    - token:scope
      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-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
    get-file-response:
      description: File retrieved.
      content:
        application/json:
          schema:
            type: object
            properties:
              file:
                $ref: '#/components/schemas/file'
            required:
            - file
          examples:
            File Retrieved:
              value:
                file:
                  id: 38cce774-b225-41ed-a9fd-f9c9777a13de
                  status: uploaded
                  category: image
                  contentType: image/png
                  download:
                    url: https://example.com/download
                    expiresAt: '2024-03-13T20:20:39.000Z'
            Pending File Retrieved:
              value:
                file:
                  id: a4e71e7d-83f3-493e-ac0e-d84618ad394a
                  status: pending
                  category: image
                  contentType: image/png
      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
    get-file-not-found-response:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            File Not Found:
              value:
                code: entity_not_found
                message: The file cannot be found
                details:
                  entity: file
      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
    too-many-requests:
      description: Too Many Requests.
      headers:
        Retry-After:
          description: The number of seconds to wait before making a new request.
          schema:
            type: integer
            format: int32
          examples:
            Retry After:
              value: 60
        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
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Too Many Requests:
              value:
                code: too_many_requests
                message: Try again later
    unauthorized:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Token Expired:
              value:
                code: token_expired
                message: The access token has expired
            Token Invalid:
              value:
                code: token_invalid
                message: The access token is invalid
            Token Revoked:
              value:
                code: token_revoked
                message: The access token has been revoked
      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:
    files-settings:
      type: object
      additionalProperties:
        title: File category settings
        type: object
        properties:
          allowedContentTypes:
            description: The allowed content types.
            type: array
            items:
              type: string
          minFileSize:
            description: The minimum file size in bytes.
            type: integer
            format: int64
          maxFileSize:
            description: The maximum file size in bytes.
            type: integer
            format: int64
          expiresIn:
            description: The expiration time in seconds.
            type: integer
            format: int64
        required:
        - allowedContentTypes
        - minFileSize
        - maxFileSize
        - expiresIn
    metadata:
      type: object
      additionalProperties: true
      minProperties: 1
    subdivision-code-for-request:
      type: string
      pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$
    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
    country-code-for-request:
      type: string
      pattern: ^[A-Z]{2}$
    file:
      allOf:
      - $ref: '#/components/schemas/file-base'
      - type: object
        properties:
          download:
            description: The download information of the file.
            type: object
            properties:
              url:
                description: The pre-signed URL to download the file.
                type: string
                format: uri
              expiresAt:
                description: The date and time when the download URL expires.
                type: string
                format: date-time
            required:
            - url
            - expiresAt
    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'
    string-no-edge-spaces:
      type: string
      pattern: ^\S.*\S$|^\S$
    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