Documents #

The documents endpoint allows you to view and download any documents that fit the parameters passed. Types of documents generated from Alpaca can be Account Monthly Statements and Trade Confirmations.


The Document Object #

Sample Object #

{
  "id": "11d5a814-9a71-4161-82a5-18e8ee0bed17",
  "name": "",
  "type": "trade_confirmation",
  "sub_type": "",
  "date": "2022-02-16"
}

Attributes #

Attribute Type Notes
id string/UUID The UUID of the document
name string The title of the document (if applicable)
type ENUM.DocumentType
sub_type string ENUM: either empty string "", 1099-Comp, 1042-S, or 480.6
date string/date format: “2020-01-01”

ENUM.DocumentType #

Value Description
account_statement Document is an account statement
trade_confirmation Document is a confirmation that a trade has completed
tax_statement Document is a generated tax statement

For accounts with older documents the following legacy values might also be seen

Value
tax_1099_b_details
tax_1099_b_form
tax_1099_div_details
tax_1099_div_form
tax_1099_int_details
tax_1099_int_form
tax_w8

Uploading a Document #

POST /v1/accounts/{account_id}/documents/upload

Upload one or more (up to 10) documents to be attached to 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.

Request #

Sample Request #

[
  {
    "document_type": "cip_result",
    "content": "JVBERi0K",
    "mime_type": "application/pdf"
  },
  {
    "document_type": "identity_verification",
    "document_sub_type": "passport",
    "content": "/9j/Cg==",
    "mime_type": "image/jpeg"
  }
]
Path Parameters #
Attribute Type Required Notes
account_id string/UUID
Required
The id for the related Account

Parameters #

The main payload body is an array of data representing the documents to upload.

Note These are not the same as the Document object and it is not an error that the field names are different.

Attribute Type Required Notes
document_type ENUM.UploadDocumentType
Required
document_sub_type ENUM.UploadDocumentSubType
Optional
content string
Optional
A string containing Base64 encoded data to upload. This field is Required if document_type is anything other than w8ben or if it is w8ben and content_type is not specified.
content_data W8BenDocumentUpload
Optional
This field is Required if content is not specified. It is also only available when document_type is w8ben
mime_type string
Optional
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

ENUM.UploadDocumentType #

Value Notes
identity_verification
address_verification
date_of_birth_verification
tax_id_verification
account_approval_letter
limited_trading_authorization
w8ben
w9

ENUM.UploadDocumentSubType #

Value
Account Application
Form W-8BEN
passport

Response #

202 - Accepted

Error Codes #

400 - Bad Request

The body in the request is not valid

404 - Not Found

No account was for this account_id


W8BenDocumentUpload Type #

This type represents the fields needed to upload a W-8 BEN document via the Upload documents route

It has been separated out into its own section in favour of readability.

For more information on W8Ben and international accounts please see the section here on international accounts

Attributes #

Attribute Type Notes
country_citizen string
date string/Date YYYY-MM-DD format
date_of_birth string/Date YYYY-MM-DD format
full_name string
ip_address string
permanent_address_city_state string
permanent_address_city_country string
permanent_address_city_street string
revision string
signer_full_name string
timestamp string/timestamp
additional_conditions string/null
capacity_acting string/null
foreign_tax_id string/null
income_type string/null
mailing_address_city_state string/null
mailing_address_country string/null
mailing_address_street string/null
paragraph_number string/null
percent_rate_withholding number/null
reference_number string/null
residency string/null
tax_id_ssn string/null
ftin_not_required bool/null

Retrieving Documents for One Account #

GET /v1/accounts/{account_id}/documents

This endpoint allows you to query all the documents that belong to a certain account. You can filter by date, or type of document.

Request #

Path Parameters #
Attribute Type Required Notes
account_id string/UUID
Required
The id for the related Account

Query Parameters #

Attribute Type Requirement Notes
start string/date
Optional
format: 2020-01-01
end string/date
Optional
format: 2020-01-01
type string
Optional
ENUM: account_statement or trade_confirmation

Response #

Returns an array of document models.

Error Codes #

401 - Not Authorized: Invalid Credentials

Downloading a Document #

GET /v1/accounts/{account_id}/documents/{document_id}/download

This endpoint allows you to download a document identified by the document_id passed as a path parameter. The returned document is in PDF format.

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

Request #

Path Parameters #
Attribute Type Required Notes
account_id string/UUID
Required
The id for the related Account
document_id string/UUID
Required
The id for the Document you wish to download

Response #

301 - Redirects to a presigned download link for the document PDF.

Errors #

404 - Document Not Found

Downloading the W8Ben #

GET /v1/accounts/{account_id}/documents/w8ben/{document_id}/download

This endpoint allows you to download a W8ben identified by the document_id passed as a path parameter. The returned document is in PDF format.

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

Request #

Path Parameters #
Attribute Type Required Notes
account_id string/UUID
Required
The id for the related Account
document_id string/UUID
Required
The id for the W8Ben you wish to download

Response #

301 - Redirects to a presigned download link for the document PDF.

Errors #

404 - Document Not Found

Retrieving a Document by ID #

GET /v1/accounts/{account_id}/documents/{document_id}

This endpoint allows you to call for a specific document and returns the document model.

Request #

Path Parameters #
Attribute Type Required Notes
account_id string/UUID
Required
The id for the related Account
document_id string/UUID
Required
The id for the Document you wish to retrieve

Response #

Returns the document model.

Errors #

404 - Document Not Found

 

Edit Edit this page