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