Upload vendor documents such as W-9/W-8 tax forms, contracts, COIs, payment instructions, and onboarding paperwork, then check bulk upload OCR and matching status. Use when: 'upload a W9', 'attach a vendor contract', 'bulk upload supplier docs', 'check vendor document status', 'upload a COI for a vendor'. Do NOT use for card transaction receipts (use receipt-compliance) or bill invoice attachments (use bills commands).
vendor_uuid unless the user has confirmed the vendor and document category.--vendor_uuid and let Ramp's matching/triage flow handle it.-n/--dry_run before uploading when using a known vendor_uuid.--document_category and --file_content_base64.--agent when checking bulk status so counts and per-document fields are easy to parse reliably.Use this when the user gives both a file path and the target vendor UUID.
# Base64 encode the file
base64 -i /path/to/acme-w9.pdf | tr -d '\n'
# Dry run first
ramp vendors attach-document \
--vendor_uuid "vnd_123" \
--filename "acme-w9.pdf" \
--content_type "application/pdf" \
--file_content_base64 "{base64_string}" \
--document_category W9 \
--dry_run
# If the request body is correct, upload for real
ramp vendors attach-document \
--vendor_uuid "vnd_123" \
--filename "acme-w9.pdf" \
--content_type "application/pdf" \
--file_content_base64 "{base64_string}" \
--document_category W9
The upload response includes:
document_uuidvendor_uuiddocument_categoryoriginal_filenamedocument_url (temporary download URL, when available)Use this when the user has a file but not a trustworthy vendor UUID yet.
ramp vendors attach-document \
--filename "acme-contract.pdf" \
--content_type "application/pdf" \
--file_content_base64 "{base64_string}" \
--document_category VENDOR_CONTRACT
If vendor_uuid is omitted in the response, tell the user the document was uploaded into the matching flow and may need review in Ramp.
documents is a complex array, so use --json for the request body.
ramp vendors bulk-upload \
--dry_run \
--json '{
"documents": [
{
"filename": "acme-w9.pdf",
"content_type": "application/pdf",
"file_content_base64": "{base64_w9}"
},
{
"filename": "acme-coi.pdf",
"content_type": "application/pdf",
"file_content_base64": "{base64_coi}"
}
],
"vendor_uuid": "vnd_123"
}'
If the dry run is correct, repeat without --dry_run. The response returns batch_id, upload_job_uuid, and document_count.
If the user does not have a single confirmed vendor UUID for all files, omit vendor_uuid so each document enters bulk triage.
Poll the batch until OCR/matching has finished or attention is needed:
ramp --agent vendors bulk-upload-status "batch_123"
Useful filters:
# Only W-form documents
ramp --agent vendors bulk-upload-status "batch_123" --is_w_document
# Exclude W-form documents
ramp --agent vendors bulk-upload-status "batch_123" --no-is_w_document
Summarize these response fields for the user:
upload_job.status, upload_job.status_reason, and upload_job.is_terminaldocument_countmatched_document_countunmatched_document_countdocuments_with_running_ocr_countdocuments_needing_attention_countreview_requiredFor each document that needs attention, include original_filename, document_category, needs_attention, matched vendor name/UUID if present, vendor_match_score, and W-form OCR details (is_likely_w8, is_likely_w9, tax_details) when available.
Use the narrowest category that matches the file:
| Document type | document_category |
|---|---|
| W-9 form | W9 |
| W-8 form | W8 |
| Vendor contract | VENDOR_CONTRACT |
| MSA | MSA |
| NDA | NDA |
| Statement of work | SOW |
| Certificate of insurance | CERTIFICATE_OF_INSURANCE |
| Payment instructions | PAYMENT_INSTRUCTIONS |
| Voided check | VOIDED_CHECK |
| Tax paperwork that is not clearly W-8/W-9/1099 | TAX_DOCUMENT |
| Anything else | OTHER |
If the category is ambiguous, ask the user before uploading. Do not guess between legal, tax, and payment document categories.
| Extension | content_type |
|---|---|
.pdf | application/pdf |
.png | image/png |
.jpg, .jpeg | image/jpeg |
.heic | image/heic |
.webp | image/webp |
For a single upload, confirm the filename, category, attachment target, and returned document_uuid:
Uploaded acme-w9.pdf as W9 and attached it to vendor vnd_123.
Document UUID: doc_456
For a bulk batch, lead with job progress and whether manual review is still required:
Batch batch_123
Status: SUCCEEDED - all documents processed
Matched: 8 / 10
Needs review: 2
Needs attention
acme-w9.pdf W9 Acme Corp (score 0.92)
wire-info.pdf PAYMENT_INSTRUCTIONS no vendor match
ramp bills attachments.| Issue | Fix |
|---|---|
ramp vendors bulk-upload rejects documents flags | Build the request body with --json; documents is a complex array. |
| Uploading a large base64 string hits shell argument limits | Split into smaller batches or put the JSON payload in a temp file and pass it through --json. |
vendor_uuid is unknown or uncertain | Omit it and use matching/triage mode instead of guessing. |
| Bulk status still shows running OCR jobs | Re-run ramp --agent vendors bulk-upload-status {batch_id} until upload_job.is_terminal is true. |
review_required is true or documents have needs_attention: true | Tell the user which files need review and why, instead of claiming the batch is fully done. |
document_url is present | Treat it as temporary and avoid storing it as a durable reference. |