ramp-manage-vendors

Files (1)

• SKILL.md

SKILL.md (first lines)

## Non-Negotiables

- **Pass `--rationale` on every command** — it is a required field on these agent-tools (a non-empty string, max 1024 chars). With `--json`, supply it as a `"rationale"` key in the body. Omitting it returns `HTTP 422 (DEVELOPER_INVALID_SCHEMA)`, in both agent and human modes.
- Never attach a document to a `vendor_uuid` unless the user has confirmed the vendor and document category.
- If the vendor identity is uncertain, omit `--vendor_uuid` and let Ramp's matching/triage flow handle it.
- Always run `-n/--dry_run` before uploading when using a known `vendor_uuid`.
- Vendor document file contents must be base64-encoded.
- CLI request flags use snake_case, for example `--document_category` and `--file_content_base64`.
- Prefer `--agent` when checking bulk status so counts and per-document fields are easy to parse reliably.

## Workflow

### Mode 1: Attach one document to a known vendor

**Surface: CLI only.** This upload operation is not available through MCP.

Use this when the user gives both a file path and the target vendor UUID.

```bash
# 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 --rationale "Upload the vendor document"

# 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 --rationale "Upload the vendor document"
```

The upload response includes:

- `document_uuid`
- `vendor_uuid`
- `document_category`
- `original_filename`
- `document_url` (temporary download URL, when available)

### Mode 2: Upload one document into vendor matching/triage

**Surface: CLI only.** This upload operation is not available through MCP.

Use this when the user has a file but not a trustworthy vendor UUID yet.

```bash
ramp vendors attach-document \
  --filename "acme-contract.pdf" \
  --content_type "application/pdf" \
  --file_content_base64 "{base64_string}" \
  --document_category VENDOR_CONTRACT --rationale "Upload the vendor document"
```

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.

### Mode 3: Bulk upload many vendor documents

**Surface: CLI only.** This upload operation is not available through MCP.

`documents` is a complex array, so use `--json` for the request body.

```bash
ramp vendors bulk-upload \
  --dry_run \
  --json '{
    "rationale": "Bulk upload vendor documents",
    "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.

### Mode 4: Check bulk upload status

**Surface: CLI or MCP.** Use the CLI command below or the MCP bulk upload status tool.

Poll the batch until OCR/matching has finished or attention is needed:

```bash
ramp --agent vendors bulk-upload-status "{batch_id}" --rationale "Check OCR/matching progress for the user's document batch"
```

Useful filters:

```bash
# Only W-form documents
ramp --agent vendors bulk-upload-status "{batch_id}" --is_w_document --rationale "Check OCR status of W-form documents in the batch"

# Exclude W-form documents
ramp --agent vendors bulk-upload-status "{batch_id}" --no-is_w_document --rationale "Check OCR status of non-W-form documents in the batch"
```

Summarize these response fields for the user:

- `upload_job.status`, `upload_job.status_reason`, and `upload_job.is_terminal`
- `document_count`

From ramp-public/skills, MIT.

More from ramp-public/skills