Argyle User Uploads API

openapi: 3.0.0
info:
  title: Argyle API Accounts User Uploads API
  version: '2.0'
  description: Accounts are payroll connections made through Link.
security:
- basicAuth: []
tags:
- name: User Uploads
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'
      tags:
      - User Uploads
  /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'
      tags:
      - User Uploads
    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'
      tags:
      - User Uploads
components:
  parameters:
    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
    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
    AccountId:
      name: account
      in: query
      description: Filter by account ID.
      schema:
        type: string
        format: uuid
  responses:
    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'
    UserUploadResponse:
      description: A user upload object.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserUpload'
  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.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Username = api_key_id, Password = api_key_secret