openapi: 3.0.0
info:
  title: User Uploads API
  version: 1.0.0
  description: >
    Retrieve manually uploaded documents.


    *   Retrieve documents manually uploaded through
    [Link](/workflows/document-processing).

    *   Retrieve [OCR data](/integrations/ocr/ocrolus#retrieving-ocr-data) and
    [authenticity information](/integrations/ocr/ocrolus#api) for uploaded
    documents.
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Username = api_key_id, Password = api_key_secret
  schemas:
    UserUpload:
      type: object
      example:
        id: 01320596-2c3d-189c-53e7-a8ce6d625b33
        account: 01856c65-43b6-8b5d-b32a-56b8fbda5c28
        document_type: proof-of-identity
        file_url: www.argyle.com/storagename
        file_name: my_drivers_license.pdf
        metadata:
          employment: null
          ocr_data: null
          ocr_authenticity: null
          ocr_authenticity_score: null
        processing:
          classification: unauthorized
          ocr: unauthorized
          authenticity: unauthorized
        created_at: '2024-07-08T13:43:49.864Z'
        updated_at: '2024-07-08T13:43:51.868Z'
      properties:
        id:
          type: string
          format: uuid
          description: Unique ID of the uploaded document.
        account:
          type: string
          format: uuid
          description: ID of the account associated with the uploaded document.
        document_type:
          type: string
          description: >
            The document
            [category](/workflows/document-processing#enabling-document-uploads)
            in Link the user selected, or the `document_type` provided when
            [uploading via the API](/api-reference/user-uploads#upload).


            If [OCR processing](/integrations/ocr/ocrolus) is enabled, this
            value is overwritten when the document is found to be a different
            type.


            Possible values:

            - `paystubs`

            - `W-2`

            - `1099`

            - `proof-of-identity`

            - `proof-of-address`

            - `miscellaneous`
        file_url:
          type: string
          description: >
            URL linking to the original uploaded document file.


            This static URL redirects to a download page that requires [Argyle
            authentication headers](/api-guide/overview#authentication).


            **Implementation requirements for client-side applications**


            1. Ensure your HTTP client or library (for example, Axios or Python
            requests) is configured to follow redirects.

            2. Append [Basic authentication
            headers](/api-guide/overview#authentication) for Argyle to the file
            download request.
        file_name:
          type: string
          description: File name of the uploaded document on the user's computer or phone.
        metadata:
          type: object
          description: Contains document OCR and authenticity information.
          properties:
            employment:
              type: object
              deprecated: true
              description: Contains document verification data.
            ocr_data:
              type: object
              description: |
                Contains [Ocrolus OCR](/integrations/ocr/ocrolus#api) data.

                Available for paystubs, W-2s, and 1099s when Ocrolus is enabled.
            ocr_authenticity:
              type: object
              description: >
                Contains [Ocrolus authenticity](/integrations/ocr/ocrolus#api)
                data.


                Includes individual instances of tampering or other
                authenticity-related edits made to the uploaded document that
                were detected.


                Available for paystubs, W-2s, and 1099s when Ocrolus is enabled.
            ocr_authenticity_score:
              type: integer
              description: >
                [Ocrolus authenticity
                score](/integrations/ocr/ocrolus#authenticity-scores).


                Single score that captures the likelihood the uploaded document
                is authentic, as determined by Ocrolus.


                Available for paystubs, W-2s, and 1099s when Ocrolus is enabled.
        processing:
          type: object
          description: Contains OCR processing statuses.
          properties:
            classification:
              type: string
              enum:
                - unauthorized
                - idle
                - in_progress
                - completed
                - failed
              description: |
                OCR classification processing status.

                - `unauthorized`: Classification permissions are not enabled.
                - `idle`: Processing has not started.
                - `in_progress`: Processing is in progress.
                - `completed`: Processing successfully completed.
                - `failed`: Processing failed.
            ocr:
              type: string
              enum:
                - unauthorized
                - idle
                - in_progress
                - completed
                - failed
              description: |
                Full OCR processing status.

                - `unauthorized`: Full OCR permissions are not enabled.
                - `idle`: Processing has not started.
                - `in_progress`: Processing is in progress.
                - `completed`: Processing successfully completed.
                - `failed`: Processing failed.
            authenticity:
              type: string
              enum:
                - unauthorized
                - idle
                - in_progress
                - completed
                - failed
              description: |
                OCR authenticity processing status.

                - `unauthorized`: Full OCR permissions are not enabled.
                Full OCR permissions are required for authenticity.
                - `idle`: Processing has not started.
                - `in_progress`: Processing is in progress.
                - `completed`: Processing successfully completed.
                - `failed`: Processing failed.
        created_at:
          type: string
          format: date-time
          description: >-
            Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when
            the uploaded document was submitted.
        updated_at:
          type: string
          format: date-time
          description: >-
            Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when
            the user upload object was last updated.
  responses:
    UserUploadResponse:
      description: A user upload object.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserUpload'
    UserUploadListResponse:
      description: A paginated list of user upload objects.
      content:
        application/json:
          schema:
            type: object
            properties:
              next:
                type: string
                format: uri
                nullable: true
                description: URL for the next page of results, if available.
              previous:
                type: string
                format: uri
                nullable: true
                description: URL for the previous page of results, if available.
              results:
                type: array
                items:
                  $ref: '#/components/schemas/UserUpload'
  parameters:
    AccountId:
      name: account
      in: query
      description: Filter by account ID.
      schema:
        type: string
        format: uuid
    UserId:
      name: user
      in: query
      description: Filter by user ID.
      schema:
        type: string
        format: uuid
    DocumentType:
      name: document_type
      in: query
      description: Filter by `document_type`.
      schema:
        type: string
        format: uuid
    Limit:
      name: limit
      in: query
      description: >
        Number of user upload objects returned [per
        page](/api-guide/overview#pagination). Default: 10. Maximum: 200.
      schema:
        type: integer
security:
  - basicAuth: []
paths:
  /v2/user-uploads/{id}:
    get:
      summary: Retrieve a user upload
      description: Retrieves a user upload object.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the user upload object to be retrieved.
      responses:
        '200':
          description: A user upload object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserUpload'
              example:
                id: 01320596-2c3d-189c-53e7-a8ce6d625b33
                account: 01856c65-43b6-8b5d-b32a-56b8fbda5c28
                document_type: paystubs
                file_url: www.argyle.com/storagename
                file_name: most_recent_paystub.pdf
                metadata:
                  employment: {}
                  ocr_data: {}
                  ocr_authenticity: {}
                  ocr_authenticity_score: null
                processing:
                  classification: unauthorized
                  ocr: unauthorized
                  authenticity: unauthorized
                created_at: '2024-07-08T13:43:49.864Z'
                updated_at: '2024-07-08T13:43:51.868Z'
  /v2/user-uploads:
    post:
      summary: Upload a document
      description: Upload a document via the API.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - user
                - document_type
                - upload
              properties:
                user:
                  type: string
                  format: uuid
                  description: ID of the user object.
                document_type:
                  type: string
                  enum:
                    - paystubs
                    - W-2
                    - 1099
                    - proof-of-identity
                    - proof-of-address
                    - miscellaneous
                  description: The type of document.
                upload:
                  type: string
                  format: binary
                  description: |
                    Link to the document to be uploaded.

                    Max of 1 document per POST request.
      responses:
        '200':
          $ref: '#/components/responses/UserUploadResponse'
    get:
      summary: List all user uploads
      description: Returns a paginated list of all user upload objects.
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/DocumentType'
        - $ref: '#/components/parameters/Limit'
        - in: query
          name: cursor
          schema:
            type: string
          description: >-
            The URL returned in `next` or `previous` used to retrieve another
            [page](/api-guide/overview#pagination) of results.
      responses:
        '200':
          $ref: '#/components/responses/UserUploadListResponse'