apply-to-ramp

name	apply-to-ramp
description	Start a new Ramp financing application or help complete an existing application for an OAuth-authorized business. Use for application signup, progress, missing data, bank information, documents, follow-ups, and applicant or Ramp handoffs.

Ramp Financing Application Workflow

Use ramp applications create for the signup flow and the generated ramp applications operations for an OAuth-authorized business's existing application. The unified agent-tool OpenAPI document defines available operations, fields, accepted values, and OAuth scopes. Developer API responses are canonical for current workflow state, actor ownership, and validation.

Choose The Flow

Determine whether the human wants to start a new application or continue an existing one. Ask if the intent is unclear.

Use production by default. Only use sandbox when the human explicitly asks for a test application or test workflow. The command examples below use --env production; substitute --env sandbox for that explicitly requested test flow.

For a new application:

1. State that production starts a real signup and underwriting process. If the human requested a test, state that the workflow will use sandbox instead.

2. Inspect the current create schema and example:

   ramp applications schema --env production --agent
   ramp applications create --env production --example --agent
   

3. Assemble a payload using only facts supplied or explicitly confirmed by the human. The live schema is canonical for fields and validation. The example illustrates the payload shape; its values are not defaults.

4. Warn that if the applicant email already belongs to a Ramp account, a successful request sends sign-in or continuation instructions instead of creating a fresh application.

5. Show a human-readable summary that includes the selected environment and obtain explicit confirmation.

6. After confirmation, start the signup flow in that same environment:

   ramp applications create --env production \
     --json '<confirmed payload>' --wait_for_auth --agent
   

A successful request sends the applicant an email while the CLI waits for the localhost OAuth callback. Keep the command running while the applicant accepts the invite. If the callback succeeds, the CLI saves scoped credentials for the selected environment. Tell the applicant exactly how to continue:

• If they do not have a Ramp account, choose Create account, finish account creation, then choose Start application.
• If they already have a Ramp account, sign in if prompted, then choose Start application.
• Once those steps are complete, return to the agent to continue.

If the command reports authenticated: false, the application was still created. Run the returned scoped ramp auth login fallback, then continue with the existing-application workflow below.

For an existing Ramp email, this continues the associated application rather than creating a fresh one. Starting the application is not final submission. Do not enter the progress workflow unless a Developer API connection is authorized for the intended business and the human wants the agent to continue its existing application.

For an existing application, inspect the current authorization:

ramp auth status --env production --agent

Reuse the current token when it already includes applications:read, applications:write, and bank_accounts:read. Otherwise, authenticate the intended business with only the scopes needed for this workflow:

ramp auth login --env production \
  --auth-level business \
  --scope applications:read \
  --scope applications:write \
  --scope bank_accounts:read

Any sanctioned connection user may complete the business-scoped browser authorization. If Ramp presents a business chooser, tell them to select the intended application business. After authorization, read the current application and confirm that it is the intended business before making any change.

The scoped login replaces the token stored for that environment. A later unscoped ramp auth login restores access to the broader CLI tool set. After authorization, use the control loop below. Never call create to update or continue an application.

Safety Rules

• For the existing-application workflow, the OAuth connection must authorize the intended business. Confirm that the returned application belongs to that business before changing it.
• Never invent, estimate, default, or infer application facts.
• Request and handle only the minimum information required by the current API action. Do not collect application data speculatively.
• Treat identity work according to the current action's actor and the nature of the step. When an identity-document follow-up has actor=AGENT, the agent may transmit the exact file the applicant selects and explicitly authorizes for that follow-up. Do not choose the evidence, make an identity judgment, inspect unrelated contents, or imply that transmission verifies the person. When an identity action has actor=APPLICANT, explain the request and provide its Ramp link. Never ask the applicant to place full government ID numbers, OTPs, or bank credentials in chat, command arguments, filenames, or agent-readable notes.
• Do not repeat sensitive values in summaries, logs, filenames, or status updates. Mask values when confirming them, for example ***6789.
• Do not use --dry_run with a sensitive payload because dry-run output includes the request body.
• Never choose or infer an acknowledgement value. Transmit ownership_acknowledgement only after explicit human confirmation immediately before the request. Do not complete applicant-owned legal agreements or attestations.
• Never make identity attestations or complete applicant-driven identity verification, final review, or final application submission. Transmitting an explicitly authorized identity document for an actor=AGENT follow-up is allowed; Ramp remains responsible for evaluating it.
• If the agent runtime provides sanctioned access to the applicant's browser, email, or SMS and the applicant authorizes its use, the agent may assist with additional applicant-owned handoff steps through those channels. This is outside the Developer API workflow and is not officially supported; do not assume such access exists or weaken confirmation and privacy requirements.
• Never bypass applicant-owned flows or call underlying third-party links.
• Stop when an action has actor=RAMP; explain that Ramp is reviewing or processing the application.
• Treat ready_for_submission=true as readiness only. The applicant must review and submit the application in Ramp.
• When discussing a non-Ramp-owned action with a deep_link_url, offer to help complete everything the agent is permitted and able to handle, and also explain that the applicant can complete the step directly in Ramp using the link. Present this choice at the relevant intake or handoff point rather than interrupting unrelated agent work. If the link fails or may be stale, fetch the resource again and use the newly returned URL.

Control Loop

For an existing application, always begin with:

ramp applications progress --env production --agent

Inspect status, required_actions, optional_actions, and ready_for_submission.

Inspect the complete required-action list before acting:

1. If any action has actor=RAMP, do not mutate the application. Explain that Ramp owns the next step and stop.
2. Complete independently actionable actor=AGENT items one at a time through generated ramp applications operations. When an item requires applicant input, offer agent assistance and, when available, direct completion through its Ramp link. Re-fetch progress after every meaningful mutation and re-evaluate the entire action list before continuing.
3. After no independently actionable agent item remains, explain each actor=APPLICANT action using guidance and applicant_action. Include the current deep_link_url when present. If no link is returned, say that explicitly instead of inventing one.
4. Present relevant optional_actions separately and label them optional. Include every current deep_link_url they provide, even though optional actions do not block required work.

Do not stop merely because an applicant-owned item appears before an agent-owned item in the response. Optional applicant actions do not block required agent work.

Use page_key, section_key, followup_reasons, follow-up prompts, accepted_document_types, and command help generated from OpenAPI descriptions to determine what information is missing. Re-run progress after every meaningful PATCH, document change, bank-account change, or follow-up submission.

Continue until no independently actionable agent work remains, Ramp owns the next step, the applicant must act, the status is terminal (APPROVED, REJECTED, or WITHDRAWN), or there is no further actionable work.

Information Intake And Privacy

When information is missing, explain what is needed, why the current action needs it, and where the applicant can usually find it. Offer these intake options:

1. The applicant provides or confirms the specific value.
2. The applicant provides a relevant file and authorizes its use for the current application task.
3. The applicant optionally consolidates relevant files in a private local folder for the agent to inspect.
4. The applicant completes the step in Ramp when a current deep_link_url is available or the value should not enter agent context.

When multiple agent-owned sections need source material, proactively offer to set up the optional working folder instead of only asking the applicant to provide files. Explain that the agent can create a minimal intake checklist and organize intentionally provided source documents by section. Ask the applicant to choose or approve the location before creating anything, and continue without a folder if they decline.

Batch related, non-sensitive questions so the applicant can answer efficiently. Keep sensitive requests separate and ask only when the current action requires them.

If using an optional working folder:

• Ask before creating or reading it. Let the applicant choose the location.
• Recommend a private location outside source repositories and shared project folders. Check that it is not tracked by Git before writing anything.
• Offer to create a concise checklist from the current progress response, with one entry per missing section, suggested source documents, and completion status. Do not place application values or sensitive identifiers in it.
• Create only the folders or organizational files the applicant approves. Use clear section names such as formation, ownership, and financials; do not require a fixed layout.
• Use it only for files the applicant intentionally makes available. Do not scan parent directories or unrelated files.
• Keep a checklist of missing sections and relevant filenames, not a duplicate database of extracted application values.
• Do not copy, rename, or reorganize source files without permission.
• Do not write assembled request JSON, raw extracted PII, credentials, or OTPs to disk. Remove agent-created temporary extracts after use; never delete the applicant's source files.

Practice data minimization when reading files:

• Prefer the applicant directly providing or confirming a specific value over reading an entire document.
• When the execution environment supports human-populated secret variables or masked input, prefer passing the value through without printing, logging, or separately inspecting it. Do not imply blind handling when the CLI or API requires the agent to receive the value.
• When a file is necessary, inspect only the relevant file, pages, tables, or fields. Avoid displaying or summarizing unrelated contents.
• Treat authorization to read a file as limited to the stated application task.
• Ask the applicant to redact unrelated sensitive information when practical.
• If the API requires a value in a CLI request, be transparent that the agent must receive that value to transmit it. Do not claim blind handling. Offer an applicant-owned Ramp flow instead when available.

Common sources:

• EIN and legal name: IRS EIN confirmation letter, tax filings, or formation records.
• Incorporation date, state, and entity type: articles or certificate of incorporation or organization.
• Ownership and beneficial owners: cap table, ownership ledger, operating agreement, or formation records.
• Bank routing and account numbers: bank statement, check, or authenticated online banking. Prefer applicant entry when unnecessary account activity would otherwise be exposed.
• Balances and financial figures: recent bank statements, accounting system, balance sheet, or profit-and-loss statement.
• Addresses: current official records.
• Identity details and documents: use an applicant-owned Ramp flow when the current action assigns it to the applicant. For an agent-owned document follow-up, offer either direct applicant completion when available or transmission of an explicitly selected and authorized file.

This guidance is advisory. Dynamic API requirements and validation remain canonical. Do not turn these examples into static requirements.

Application Updates

Read the current application before requesting or applying updates:

ramp applications get --env production --agent
ramp tools schema applications edit --env production --agent
ramp applications edit --env production --help

Ask only for facts needed by the current required action. PATCH only fields supplied or explicitly confirmed by the human or an authoritative source. Preserve partial-update semantics by omitting every unknown field.

ramp applications edit --env production \
  --json '<source-backed partial object>' --agent
ramp applications progress --env production --agent

Present Developer API validation details as recoverable input issues. Ask the human to correct the specific rejected value; do not work around validation.

If progress still reports a section as incomplete after its apparent fields were supplied, re-read the application and the current generated schema descriptions, then report which requirement remains unresolved. Do not infer a hidden validation rule or repeatedly PATCH guessed values. The Developer API contract and current state remain canonical.

Follow-Ups

When progress reports follow-up work:

ramp applications followups --env production --agent

Inspect each follow-up's actor, type, status, is_complete, is_required, reason, prompt, description, applicant_action, deep_link_url, accepted_document_types, and selected_document_type.

• Skip follow-ups with is_complete=true.
• Treat status=REVISION_REQUESTED as a request to revise the existing response. Explain what changed using the current prompt and description; do not resend the prior response without checking it against the new request.
• If any follow-up has actor=RAMP, explain that Ramp owns the next step and stop.
• Otherwise, complete independently actionable actor=AGENT follow-ups before presenting applicant-owned follow-ups.
• Label incomplete follow-ups with is_required=false as optional. Do not let them delay submission when the API reports is_submission_ready=true.
• For actor=APPLICANT, explain the request and provide the current Ramp link after agent-owned work is complete. Do not call update-followup or upload for that follow-up.
• For an agent-owned document follow-up, selected_document_type selects a type; it does not upload a file. Prefer a listed accepted_document_types value when one matches. If the prompt or description requests a bespoke type, use that exact human-confirmed type even when it is not listed. Do not invent or generalize document types; Developer API validation remains canonical.
• If selected_document_type is already populated and matches the authorized file, do not update it again. Call update-followup only to set or change the selection.
• For sensitive or identity evidence, explain what will be transmitted and ask the applicant to select the document and explicitly authorize that exact file. Handle the decision case by case; prefer a direct applicant flow when the applicant does not want the file in agent context.

Text or agent-confirmable follow-up:

ramp applications update-followup <followup_id> --env production \
  --json '{"response_text":"<human-provided response>"}' --agent

Agent-owned document follow-up:

# Only when selected_document_type must be set or changed:
ramp applications update-followup <followup_id> --env production \
  --json '{"selected_document_type":"<confirmed type>"}' --agent

Upload the authorized file after confirming the current selection:

ramp applications upload --env production \
  --file <path> --purpose FOLLOWUP --followup_id <followup_id> --agent
ramp applications progress --env production --agent

For an agent-owned bank-linking follow-up, first inspect the current application and linked accounts. If the applicant's Ramp checking preference is not clear, ask whether they want to open a Ramp checking account. Separately ask whether they want to link any external accounts; they may link multiple accounts through Plaid or add multiple manual accounts. Add each manual account using only applicant-confirmed details through applications edit. Re-fetch follow-ups and progress after each account. Only after the applicant explicitly confirms that there are no more accounts to link, send:

ramp applications update-followup <followup_id> --env production \
  --json '{"no_more_accounts_to_link":true}' --agent

Do not use this flag to bypass Plaid or another applicant-owned linking flow.

Fetch follow-ups again. Submit the follow-up package only when the response says is_submission_ready=true:

ramp applications submit --env production --agent
ramp applications progress --env production --agent

Follow-up submission is not final application submission.

Documents And Bank Accounts

List documents before deleting one so its ID and association are confirmed:

ramp applications documents --env production --page_size 100 --agent
ramp applications delete-document <document_id> --env production --agent
ramp applications progress --env production --agent

For bank documents, use the declared purpose and include the required manual_bank_account_id. For follow-up documents, use purpose=FOLLOWUP and the matching followup_id.

Paginate document and bank-account lists until pagination.next_cursor is null:

ramp applications accounts --env production --page_size 100 --agent

Agent output normalizes a next-page URL to the value accepted by these commands. Pass each returned pagination.next_cursor through --start until it is null:

ramp applications documents --env production \
  --page_size 100 --start '<pagination.next_cursor>' --agent
ramp applications accounts --env production \
  --page_size 100 --start '<pagination.next_cursor>' --agent

Never fabricate or modify the returned cursor.

For every account whose connection_provider is manual, count the active application documents whose purpose is BANK_STATEMENT and whose manual_bank_account_id matches that account. The standard statement path is complete once a manual account has three active bank statements. Three is the completion threshold for this path, not an upload maximum.

Upload only the number of missing statements:

ramp applications upload --env production --file <statement_path> \
  --purpose BANK_STATEMENT --manual_bank_account_id <account_id> --agent

Repeat the list-and-count step after each upload and stop once the account has three active statements. Then refresh application progress. Do not upload extra statements merely because the API accepts more than three. If the applicant is offered an alternative bank-document path in Ramp, hand off with the current deep_link_url. The Developer API does not expose eligibility for that path, so do not infer eligibility or select alternative documents on the applicant's behalf.

Bank linking has multiple valid outcomes:

• Read the current application and inspect open_ramp_checking_account. If the applicant's preference is absent or unclear, ask whether they want to open a Ramp checking account before sending that field.
• Inspect connection_provider across the current linked accounts. An existing Ramp checking account may already satisfy the bank requirement.
• Ramp checking and external accounts are not mutually exclusive. The applicant may choose Ramp checking, one or more external accounts, or both.
• Reuse an existing applicant-confirmed manual account when one is present. Use --connection_provider manual only as a focused lookup after inspecting the current account set.
• Add each human-provided manual account through applications edit, re-reading accounts and progress after each addition.
• Plaid or another applicant-only linking flow must be handed to the human with the current deep_link_url. The applicant may repeat that flow to link multiple accounts when Ramp permits it.

Never ask for or store bank credentials.

Do not duplicate static validation rules in conversation. Use command help and Developer API errors for the current field contract.