Alpaca Documents API

openapi: 3.2.0
info:
  title: Alpaca Documents API
  contact:
    email: support@alpaca.markets
    name: Alpaca Support
    url: https://alpaca.markets/support
  version: '1.0'
  description: 'Operations tagged Documents across 3 of this provider''s published API definitions: alpaca-eu-broker-api-openapi.json, alpaca-us-broker-api-openapi.json, alpaca-documents-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: Sandbox endpoint
  url: https://broker-api.sandbox.eu.alpaca.markets
- description: Production endpoint
  url: https://broker-api.eu.alpaca.markets
- description: Sandbox endpoint
  url: https://broker-api.sandbox.alpaca.markets
- description: Production endpoint
  url: https://broker-api.alpaca.markets
security:
- BasicAuth: []
tags:
- name: Documents
paths:
  /v1/accounts/{account_id}/documents:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    get:
      description: 'This endpoint allows you to query all the account document based on an account ID. You can filter by date, or type of document.


        These account documents are tax statements, trade confirmations, etc, generated by the Alpaca system. They are distinct from the owner documents you upload and later access via the account object''s documents property.'
      operationId: getDocsForAccount
      parameters:
      - description: optional date value to filter the list (inclusive).
        in: query
        name: start
        schema:
          format: date
          type: string
      - description: optional date value to filter the list (inclusive).
        in: query
        name: end
        schema:
          format: date
          type: string
      - $ref: '#/components/parameters/AccountDocumentType'
      responses:
        '200':
          content:
            application/json:
              examples: {}
              schema:
                items:
                  $ref: '#/components/schemas/AccountDocument'
                type: array
          description: OK
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not found
      summary: Retrieve a List of Account Documents
      tags:
      - Documents
    servers:
    - description: Sandbox endpoint
      url: https://broker-api.sandbox.eu.alpaca.markets
    - description: Production endpoint
      url: https://broker-api.eu.alpaca.markets
  /v1/accounts/{account_id}/documents/{document_id}/download:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    - $ref: '#/components/parameters/DocumentID'
    get:
      description: 'This endpoint downloads an account document based on the document ID. The document will be in PDF format.


        The operation returns a pre-signed downloadable link as a redirect with HTTP status code 301 if one is found.


        You can retrieve a JSON version of a monthly statement by passing in the header accept: application/json header.


        These account documents are tax statements, trade confirmations, etc, generated by the Alpaca system. They are distinct from the owner documents you upload and later access via the account object''s documents property.'
      operationId: downloadDocFromAccount
      responses:
        '301':
          description: 'Redirect to the pre-signed download link for the account document PDF file.

            '
        '404':
          description: The document is not found.
      security:
      - BasicAuth: []
      summary: Download an Account Document
      tags:
      - Documents
    servers:
    - description: Sandbox endpoint
      url: https://broker-api.sandbox.eu.alpaca.markets
    - description: Production endpoint
      url: https://broker-api.eu.alpaca.markets
  /v1/accounts/{account_id}/documents/upload:
    parameters:
    - $ref: '#/components/parameters/AccountID'
    post:
      description: 'Upload documents for the primary account owner of an account.


        Documents are binary objects whose contents are encoded in base64. Each encoded content size is limited to 10MB if you use Alpaca for KYCaaS. If you perform your own KYC there are no document size limitations.


        As a convenience, documents of type w8ben may be uploaded as a JSON object using the content_data request property. The Alpaca system will then generate a formatted W-8 BEN document for subsequent downloads.


        Note that these owner documents are distinct from the account documents generated by Alpaca, such as tax statements and trade confirmations.'
      operationId: uploadDocToAccount
      requestBody:
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/OwnerDocumentUploadRequest'
              type: array
        required: true
      responses:
        '204':
          description: Success (No Content)
        '400':
          content:
            application/json:
              schema:
                type: string
          description: Bad Request. The body in the request is not valid.
        '404':
          content:
            application/json:
              schema:
                type: string
          description: Not Found. No account was found for this account_id
      summary: Upload Owner Documents for an Existing Account
      tags:
      - Documents
    servers:
    - description: Sandbox endpoint
      url: https://broker-api.sandbox.eu.alpaca.markets
    - description: Production endpoint
      url: https://broker-api.eu.alpaca.markets
  /v1/accounts/{account_id}/documents/w8ben/{document_id}/download:
    parameters:
    - description: The id of the related account
      in: path
      name: account_id
      required: true
      schema:
        type: string
    - description: The id of the W8BEN to download
      in: path
      name: document_id
      required: true
      schema:
        type: string
    get:
      description: 'This endpoint allows you to download a W-8 BEN document for the primary owner of an account based on the document_id passed as a path parameter. The returned document is in PDF format.


        For certain individuals, a W-8 BEN form should be submitted at onboarding. If the individual is not a registered U.S. taxpayer (not subject to a W-9), the W-8 BEN form may need to be submitted. The IRS explains which individuals this applies to and provides instructions on completing the form. Every three years, in addition to the calendar year it was signed, a new W-8 BEN form must be submitted.


        The form can be submitted in JSON, JSONC, PNG, JPEG or PDF. If submitting it in JSON, please see the W-8 BEN completed with the corresponding field names for the API here.


        Note: The dates collected on the form are in a slightly different format than how they need to be submitted via Accounts API. It is requested by the user on the form in MM-DD-YYYY, but should be submitted as YYYY-MM-DD.'
      operationId: get-v1-accounts-account_id-documents-w8ben-document_id-download
      responses:
        '301':
          description: Redirects to a presigned download link for the document PDF.
        '404':
          description: Document Not Found
      summary: Download the W8BEN document for the primary owner of an account
      tags:
      - Documents
    servers:
    - description: Sandbox endpoint
      url: https://broker-api.sandbox.eu.alpaca.markets
    - description: Production endpoint
      url: https://broker-api.eu.alpaca.markets
  /v1/documents/{document_id}:
    parameters:
    - $ref: '#/components/parameters/DocumentID'
    servers:
    - url: https://broker-api.sandbox.alpaca.markets
      description: Sandbox endpoint
    - url: https://broker-api.alpaca.markets
      description: Production endpoint
    get:
      security:
      - BasicAuth: []
      summary: Download a document file directly
      tags:
      - Documents
      description: The operation returns a pre-signed downloadable link as a redirect with HTTP status code 301 if one is found.
      responses:
        '301':
          description: 'Redirect to the pre-signed download link for the document PDF file.

            '
        '404':
          description: The document was not found.
      operationId: downloadDocumentById
components:
  parameters:
    AccountDocumentType:
      description: The type of the account document
      in: query
      name: type
      required: false
      schema:
        enum:
        - account_application
        - account_statement
        - crypto_account_statement
        - options_application
        - tax_statement
        - trade_confirmation_json
        - trade_confirmation
        example: account_statement
        type: string
    AccountID:
      description: Account identifier.
      in: path
      name: account_id
      required: true
      schema:
        format: uuid
        type: string
    DocumentID:
      description: Document identifier.
      in: path
      name: document_id
      required: true
      schema:
        format: uuid
        type: string
  schemas:
    OwnerDocumentType:
      description: The type of the owner document
      enum:
      - account_approval_letter
      - address_verification
      - cip_result
      - company_formation
      - date_of_birth_verification
      - entity_operating_document
      - entity_registration
      - hio_declaration_form
      - identity_verification
      - limited_trading_authorization
      - pep_declaration_form
      - tax_id_verification
      - w8ben
      - w9
      example: identity_verification
      type: string
    OwnerDocumentUploadRequest:
      description: The request to upload a document for an owner of the account
      example:
        content: /9j/Cg==
        document_sub_type: passport
        document_type: identity_verification
        mime_type: image/jpeg
      examples:
      - content: /9j/Cg==
        document_sub_type: passport
        document_type: identity_verification
        mime_type: image/jpeg
      properties:
        content:
          contentEncoding: base64
          description: The base64 string encoding of the document contents. This property is required unless content_data is provided.
          example: /9j/Cg==
          type: string
        content_data:
          $ref: '#/components/schemas/W8benDocument'
        document_sub_type:
          description: The specific type of document, e.g. passport. This is a free-form property.
          example: passport
          type: string
        document_type:
          $ref: '#/components/schemas/OwnerDocumentType'
        mime_type:
          description: 'This field is required if content is specified. ENUM: application/pdf, image/png, or image/jpeg. If document_type is w8ben then application/json is also accepted'
          example: image/jpeg
          type: string
      required:
      - document_type
      - content
      title: OwnerDocumentUploadRequest
      type: object
    AccountDocument:
      description: A document associated with an account
      example:
        date: '2019-09-30'
        id: 0d18ae51-3c94-4511-b209-101e1666416b
        sub_type: 1099-Comp
        type: account_statement
      properties:
        date:
          format: date
          type: string
        id:
          format: uuid
          type: string
        name:
          type: string
        sub_type:
          description: The sub-type of the document. This is a free-form property.
          type: string
        type:
          $ref: '#/components/schemas/AccountDocumentType'
      required:
      - id
      - type
      - date
      type: object
    AccountDocumentType:
      description: 'The type of the account document

        '
      enum:
      - account_application
      - account_statement
      - crypto_account_statement
      - options_application
      - tax_statement
      - trade_confirmation_json
      - trade_confirmation
      example: account_application
      type: string
    W8benDocument:
      description: Use this property (instead of the content property) to upload W-8 BEN data in JSON format.
      examples:
      - additional_conditions: None
        country_citizen: Australia
        date: '2021-06-14'
        date_of_birth: '1970-01-01'
        foreign_tax_id: 123 456 789
        ftin_not_required: false
        full_name: John Doe
        income_type: interest
        ip_address: 127.0.0.1
        mailing_address_city_state: Adelaide, South Australia
        mailing_address_country: Australia
        mailing_address_street: 51 Main St
        paragraph_number: '15'
        percent_rate_withholding: 5
        permanent_address_city_state: Adelaide, South Australia
        permanent_address_country: Australia
        permanent_address_street: 20 Main St
        reference_number: abc123
        residency: Australia
        revision: 10-2021
        signer_full_name: Mr. Signing User
        tax_id_ssn: 123-00-456
        timestamp: '2021-06-14T09:31:05Z'
      properties:
        additional_conditions:
          description: Any additional conditions to specify
          type: string
        country_citizen:
          description: The country that the applicant is a citizen of
          type: string
        date:
          description: date signed
          format: date
          type: string
        date_of_birth:
          description: date of birth of applicant
          format: date
          type: string
        foreign_tax_id:
          description: Applicant's tax id in their home country
          type: string
        ftin_not_required:
          description: Required if foreign_tax_id and tax_id_ssn are empty.
          type: boolean
        full_name:
          description: Full name of applicant
          type: string
        income_type:
          description: Income type of applicant
          type: string
        ip_address:
          description: IP address of applicant when signed
          type: string
        mailing_address_city_state:
          description: Mailing city/state of applicant
          type: string
        mailing_address_country:
          description: Mailing country for applicant
          type: string
        mailing_address_street:
          description: Mailing street address for applicant
          type: string
        paragraph_number:
          type: string
        percent_rate_withholding:
          type: integer
        permanent_address_city_state:
          description: Permanent city/state of applicant
          type: string
        permanent_address_country:
          description: Permanent country of residence of applicant
          type: string
        permanent_address_street:
          description: Permanent street address of applicant
          type: string
        reference_number:
          type: string
        residency:
          description: Country of residency of applicant
          type: string
        revision:
          description: Revision of the W8BEN form
          type: string
        signer_full_name:
          description: Full name of signing user
          type: string
        tax_id_ssn:
          description: TaxID/SSN of applicant
          type: string
        timestamp:
          description: Timestamp when form data was gathered
          format: time
          type: string
      required:
      - country_citizen
      - date
      - date_of_birth
      - full_name
      - ip_address
      - permanent_address_city_state
      - permanent_address_country
      - permanent_address_street
      - revision
      - timestamp
      - signer_full_name
      type: object
  securitySchemes:
    BasicAuth:
      scheme: basic
      type: http
x-refined-from:
- alpaca-eu-broker-api-openapi.json
- alpaca-us-broker-api-openapi.json
- alpaca-documents-api-openapi.yml
x-readme:
  explorer-enabled: true
  proxy-enabled: false