> ## Documentation Index
> Fetch the complete documentation index at: https://developer.karmacheck.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate secure document upload URLs

> Generates short-lived URLs that can be used to upload one or more secure documents to the KarmaCheck system. This API call is step 1 of 3 when adding a document to the system and linking it to a case.

The returned URLs expire after 1 hour. If an attempt to use an expired URL occurs, the server responds with a 403 HTTP status code.



## OpenAPI

````yaml /background-check-api/api-reference/openapi.json post /document/secure/upload
openapi: 3.1.0
info:
  title: KarmaCheck API
  description: >-
    All requests to the KarmaCheck API require a JSON Web Token (JWT) in the
    Authorization header. For an overview of the API and its authentication
    method, refer to the following topics:


    - [API basics](docs/overview/apis/api-overview.md)

    - [Authentication](docs/overview/apis/authentication.md)

    - [Environments](docs/overview/apis/environments.md)

    - [Status codes and errors](docs/overview/apis/errors.md)
  version: '1.0'
  contact:
    name: KarmaCheck
    email: customersuccess@karmacheck.com
servers:
  - description: Stage
    url: https://api-stage.karmacheck.io
  - description: Prod
    url: https://api.karmacheck.io
security:
  - JWT: []
tags:
  - name: Authentication
  - name: Cases
  - name: Candidate onboarding
  - name: Secure documents
  - name: Packages
  - name: Services
  - name: Users
  - name: Companies
  - name: Partner integrations
paths:
  /document/secure/upload:
    post:
      tags:
        - Secure documents
      summary: Generate secure document upload URLs
      description: >-
        Generates short-lived URLs that can be used to upload one or more secure
        documents to the KarmaCheck system. This API call is step 1 of 3 when
        adding a document to the system and linking it to a case.


        The returned URLs expire after 1 hour. If an attempt to use an expired
        URL occurs, the server responds with a 403 HTTP status code.
      operationId: post-document-secure-upload
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentFiles'
            examples:
              Example 1:
                value:
                  files:
                    - documentTypeId: candidate-disclosures-and-authorizations
                      mimeType: application/pdf
        description: ''
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - list
                properties:
                  list:
                    type: array
                    items:
                      type: object
                      required:
                        - url
                        - fileKey
                      properties:
                        url:
                          type: string
                          format: uri
                          description: >-
                            The URL to upload the document to. This expires
                            after 1 hour.
                        fileKey:
                          type: string
                          description: >-
                            The identifier used to reference the file in
                            KarmaCheck's storage system. This must be included
                            in the [Create secure document
                            records](karma-api-openapi.yaml/paths/~1document~1secure~1create/post)
                            call.
              examples:
                Example 1:
                  value:
                    list:
                      - url: >-
                          https://s3.amazonaws.com/dev.private.storage-bin.karmacheck.io/b92fef93-437f-4a05-adb7-182357b8a1f0?AWSAccessKeyId=ASIATUZWO5YBCYMY73ZZ&Content-Type=image%2Fjpeg&Expires=1710031824&Signature=x0e6I7GZFOJLUe%2FTkRmDjoNmNvc%3D&X-Amzn-Trace-Id=Root%3D1-65ecf5c0-4c1e58d24ba6707d02d69e20%3BParent%3D3898fdce19660298%3BSampled%3D0%3BLineage%3De3b20767%3A0&x-amz-security-token=FwoGZXIvYXdzEBEaDLO5SgCTmUgIMZ7bNyK5AUBiY%2B5i0%2B8%2Fcg8Y0XFmpfLWBqhmstkdrK3uF79EMlgDjWpX%2FqgRisuvbPzFFOZ9K1dgSorlUAPgTYIXKGdadO3ZsdsVTaL4kAZDX5qQNa%2FnP%2BFB9SVgqa6F4%2FIaBzA1aDiqs7w%2Ft7tGounuPV42O86V6ig3cuBHcx9%2BUOcd9mbJ2GGytKjDrZ7PBfIJimKy0tMFaFaTSCVIPcMVyqUe1%2BGFTHtc8686WQFpIW34Ff06SzPZmfQTVRcFKKXrs68GMi2QMcUwY0v194kGFN3WaGw1sqIqab3xJLwKXQGR4GbQUwiQHMK6Ws7cg4Hesx4%3D
                        fileKey: b92fef93-437f-4a05-adb7-182357b8a1f0
        '400':
          description: |-
            Bad Request

            - An invalid or unsupported document type was provided.
            - An invalid or unsupported MIME type was provided.
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
components:
  schemas:
    DocumentFiles:
      title: DocumentFiles
      type: object
      required:
        - files
      properties:
        files:
          type: array
          description: >-
            An array that enables the generation of upload URLs for multiple
            files at once. Note that the order matters. Make sure to upload the
            first file to the first URL, and so on.
          items:
            type: object
            required:
              - documentTypeId
              - mimeType
            properties:
              documentTypeId:
                type: string
                description: |-
                  The ID for the type of document to be uploaded.

                  Allowed value: `candidate-disclosures-and-authorizations`
              mimeType:
                type: string
                description: >-
                  The MIME type of the file to be uploaded. See [Get secure
                  document MIME
                  types](karma-api-openapi.yaml/paths/~1document~1secure~1mimetypes/get)
                  for details.
  securitySchemes:
    JWT:
      type: http
      scheme: bearer

````