Supporting Documents

Upload a Customer's documents and attach them to transfers.

ActionDescription
List document typesReturns the document types you can upload and the file limits.
Upload a documentUploads a file for a Customer. Returns a doc_ ID.
Delete a documentDeletes a document that hasn't been submitted for review.
Attach documents to a transferAttaches uploaded documents to an existing transfer.
List customer documentsLists a Customer's uploaded documents. Filter by document_type or transfer_id.
List transfer documentsLists the documents attached to a transfer.

How It Works

  1. Upload a document. Harbor returns an id that starts with doc_.
  2. 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.

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: if true, the document can be attached to one transfer only.
  • requires_description: if true, description is 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

LimitValue
File typesPDF, JPG, JPEG, PNG
File sizeUp to 8 MB
Image sizeAt least 100 KB
DescriptionUp to 500 characters
Documents for each transferUp to 20
Files of one type for each transferUp to 8
Expiry7 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:

FieldRequiredDescription
fileYesThe document.
document_typeYesOne of the values above.
descriptionWhen the type is ADDITIONAL_DOCUMENTSUp 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.

CauseMessage
Image under 100 KBThis image is too small to read. Upload a clearer scan or photo (at least 100 KB).
Document expiredThis document has expired. Upload it again.
Document not found for the CustomerDocument not found for this customer.
Delete after submission for reviewThis 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.


Did this page help you?