Supporting Documents
Upload a Customer's documents and attach them to transfers.
| Action | Description |
|---|---|
| List document types | Returns the document types you can upload and the file limits. |
| Upload a document | Uploads a file for a Customer. Returns a doc_ ID. |
| Delete a document | Deletes a document that hasn't been submitted for review. |
| Attach documents to a transfer | Attaches uploaded documents to an existing transfer. |
| List customer documents | Lists a Customer's uploaded documents. Filter by document_type or transfer_id. |
| List transfer documents | Lists the documents attached to a transfer. |
How It Works
- Upload a document. Harbor returns an
idthat starts withdoc_. - Attach it to a transfer:
- When you create the transfer, send the IDs in
compliance_document_ids. - On an existing transfer, call the attach endpoint.
- When you create the transfer, send the IDs in
A document can only be attached to transfers of the Customer it belongs to.
Document Types
Returns the document types you can upload and the file limits.
GET /api/v1/customers/document-types
{
"data": {
"document_types": [
{
"value": "INVOICE",
"label": "Invoice",
"transaction_scoped": true,
"requires_description": false
}
],
"limits": {
"allowed_extensions": ["pdf", "jpg", "jpeg", "png"],
"max_file_size_bytes": 8388608,
"min_image_size_bytes": 102400,
"max_description_length": 500,
"max_files_per_type_per_transfer": 8,
"max_documents_per_transfer": 20,
"expires_after_days": 7
}
}
}transaction_scoped: iftrue, the document can be attached to one transfer only.requires_description: iftrue,descriptionis required on upload.
Values: INVOICE, ID_DOCUMENT, PROOF_OF_ADDRESS, FORMATION_DOCUMENT, ORG_STRUCTURE, BENEFICIARY_OWNERS_IDENTITY_DOCUMENT, CONTRACT, AGREEMENT, BILL_OF_LADING_OR_TRANSPORT_DOCUMENTS, ADDITIONAL_DOCUMENTS.
File Requirements
| Limit | Value |
|---|---|
| File types | PDF, JPG, JPEG, PNG |
| File size | Up to 8 MB |
| Image size | At least 100 KB |
| Description | Up to 500 characters |
| Documents for each transfer | Up to 20 |
| Files of one type for each transfer | Up to 8 |
| Expiry | 7 days after upload |
Upload a Document
Uploads a file for a Customer. Returns a doc_ ID.
POST /api/v1/customers/{customer_uuid}/documents
Send multipart/form-data:
| Field | Required | Description |
|---|---|---|
file | Yes | The document. |
document_type | Yes | One of the values above. |
description | When the type is ADDITIONAL_DOCUMENTS | Up to 500 characters. |
curl --request POST \
--url https://harbor-sandbox.owlpay.com/api/v1/customers/cus_1234567890/documents \
--header 'X-API-KEY: {YOUR_API_KEY}' \
--form '[email protected]' \
--form 'document_type=INVOICE'{
"data": {
"id": "doc_ywmQkiIckmGqf7yAnx8Q81UgOq5wBNLRXGSj2rE4",
"document_type": "INVOICE",
"file_name": "invoice-2026-10.pdf",
"expires_at": "2026-11-26T03:22:32+00:00",
"is_expired": false,
"transfers": [],
...
}
}Attach to a Transfer
Attaches uploaded documents to a transfer, when you create it or afterwards.
When Creating the Transfer
Attaches documents as you create the transfer.
POST /api/v2/transfers
Add compliance_document_ids (up to 20 IDs) to Create a transfer (v2).
{
"on_behalf_of": "cus_1234567890",
"quote_id": "quote_...",
"application_transfer_uuid": "your-order-123",
"destination": {
"beneficiary_info": {
"...": "Fill according to quote requirements"
},
"payout_instrument": {
"address": "0x1234567890abcdef1234567890abcdef12345678"
},
"transfer_purpose": "SALARY",
"is_self_transfer": true
},
"compliance_document_ids": [
"doc_ywmQkiIckmGqf7yAnx8Q81UgOq5wBNLRXGSj2rE4"
]
}The request is rejected if a document has expired, belongs to another Customer, or is an invoice or bill of lading already attached to another transfer.
On an Existing Transfer
Attaches uploaded documents to an existing transfer.
POST /api/v2/transfers/{transfer_uuid}/documents
{
"compliance_document_ids": [
"doc_ywmQkiIckmGqf7yAnx8Q81UgOq5wBNLRXGSj2rE4"
]
}- Send 1 to 20 IDs. IDs already attached are ignored.
- Not allowed once the transfer has finished (completed, refunded, expired, cancelled).
- The response lists all documents attached to the transfer.
Errors
Validation errors return 422 with code 2005. For several IDs, the key shows the array position, for example compliance_document_ids.1.
| Cause | Message |
|---|---|
| Image under 100 KB | This image is too small to read. Upload a clearer scan or photo (at least 100 KB). |
| Document expired | This document has expired. Upload it again. |
| Document not found for the Customer | Document not found for this customer. |
| Delete after submission for review | This document has already been submitted for review and cannot be deleted. |
Notes
- Supporting documents are not RFI answers. To answer an RFI, see Transfer RFI or Onboarding RFI.
- Once a document is submitted for review, it can't be deleted.
See also Transfer RFI.
Updated about 5 hours ago