Ramp: Create a new vendor
Ramp vendor.postVendorListResource: arguments, response, policy and SDK examples.
← Vendor operations · Get started
Operation ramp.post_vendor_list_resource
Provider route: POST /developer/v1/vendors. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/ramp with npm, or alter-sdk-ramp with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { RampIntegration } from "@alter-ai/ramp";
async function execute(input: Parameters<RampIntegration["vendor"]["postVendorListResource"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new RampIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.vendor.postVendorListResource(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_ramp import RampIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = RampIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.vendor.post_vendor_list_resource(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
body | Model | Required within parent | Expand Create a new vendor — request body — body |
Referenced models: Create a new vendor — request body — body
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand Create a new vendor — response body |
Referenced models: Create a new vendor — response body
Schemas
Section titled “Schemas”7 more schemas are linked from the tables above, on the schema pages.
Create a new vendor — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
accounting_vendor_remote_id | string | Optional | The accounting remote id of the vendor. At most one of `accounting_vendor_remote_id` or `vendor_tracking_category_option_id` should be provided. The referenced accounting vendor must not already be linked to another Ramp vendor. |
acting_user_id | JSON | Optional | |
acting_user_id (anyOf 1) | string | Alternative | Deprecated and ignored. This field is accepted for backward compatibility only. Use `requesting_user_id` to control the requestor on vendor detail requests. Default: null Format: uuid |
acting_user_id (anyOf 2) | null | Alternative | |
address | Model | Optional | Expand Create a new vendor — request body — body address The address of the vendor. |
business_vendor_contacts | Model | Required within parent | Expand Create a new vendor — request body — body business vendor contacts Detailed information about the vendor contact. |
country | JSON | Optional | |
country (anyOf 1) | string | Alternative | The country of the vendor. Defaults to US when omitted or null. |
country (anyOf 2) | null | Alternative | |
default_entity_id | JSON | Optional | |
default_entity_id (anyOf 1) | string | Alternative | Unique identifier of the default business entity to associate with this vendor. Must belong to the current business. If omitted, the vendor is created without a default entity. Default: null Format: uuid |
default_entity_id (anyOf 2) | null | Alternative | |
external_vendor_id | JSON | Optional | |
external_vendor_id (anyOf 1) | string | Alternative | Customer-defined external identifier for the vendor. This is independent of accounting system remote IDs. Default: null |
external_vendor_id (anyOf 2) | null | Alternative | |
name | string | Optional | Name of the new vendor to be created. Minimum length: 1 |
net_payment_terms | JSON | Optional | |
net_payment_terms (anyOf 1) | integer | Alternative | Number of days after receipt that payment is due. 0 means due on receipt. Null clears terms; omission may inherit terms from a parent vendor. Maximum: 3652058 Minimum: 0 |
net_payment_terms (anyOf 2) | null | Alternative | |
parent_vendor_id | JSON | Optional | |
parent_vendor_id (anyOf 1) | string | Alternative | Unique identifier of the parent vendor to associate with this vendor. Default: null Format: uuid |
parent_vendor_id (anyOf 2) | null | Alternative | |
request_payment_details | boolean | Optional | Whether to request payment details from the vendor (ACH bank account, international wire transfer, and check mailing address). Requires a contact email. Default: false |
request_tax_details | boolean | Optional | Whether to request tax information from the vendor (Tax Identification Number, federal tax classification, and tax address). Requires a contact email. Default: false |
requesting_user_id | JSON | Optional | |
requesting_user_id (anyOf 1) | string | Alternative | Unique identifier of the Ramp user to record as the requestor for any payment or tax details request created during vendor creation. Defaults to existing vendor creation behavior when omitted. Requires the token user to have admin or owner privileges. Default: null Format: uuid |
requesting_user_id (anyOf 2) | null | Alternative | |
state | JSON | Optional | |
state (anyOf 1) | string | Alternative | Optional vendor-level two-letter US state abbreviation, such as VA. Ignored for non-US vendor countries. Default: null |
state (anyOf 2) | null | Alternative | |
vendor_owner_id | JSON | Optional | |
vendor_owner_id (anyOf 1) | string | Alternative | Unique identifier of the user that will own this vendor. If omitted, the vendor will be created without an owner. Default: null Format: uuid |
vendor_owner_id (anyOf 2) | null | Alternative | |
vendor_tracking_category_option_id | string | Optional | Ramp unique identifier of the accounting vendor to link to this vendor. At most one of `accounting_vendor_remote_id` or `vendor_tracking_category_option_id` should be provided. The referenced accounting vendor must not already be linked to another Ramp vendor. Format: uuid |
Referenced models: Create a new vendor — request body — body business vendor contacts, Create a new vendor — request body — body address
Create a new vendor — request body — body business vendor contacts
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
email | string | Required within parent | |
first_name | string | Optional | |
last_name | string | Optional | |
phone | string | Optional |
Create a new vendor — request body — body address
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
address_line_1 | string | Required within parent | Primary address line of the vendor. |
address_line_2 | JSON | Optional | |
address_line_2 (anyOf 1) | string | Alternative | Secondary address line or suite number of the vendor. |
address_line_2 (anyOf 2) | null | Alternative | |
city | string | Required within parent | City of the vendor address. |
country | string | Required within parent | Country of the vendor address. |
pay_to_name | JSON | Optional | |
pay_to_name (anyOf 1) | string | Alternative | Recipient name printed on checks mailed to this address. Defaults to the vendor name. Pattern: \s*\S |
pay_to_name (anyOf 2) | null | Alternative | |
postal_code | string | Required within parent | Postal or ZIP code of the vendor address. |
state | JSON | Optional | |
state (anyOf 1) | string | Alternative | Address state/province abbreviation. For US addresses, use the two-letter state abbreviation, such as VA. Required for addresses in US, CA, and AU. Ignored for other countries. |
state (anyOf 2) | null | Alternative |
Create a new vendor — response body — address
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
address_line_1 | string | Required within parent | Primary address line of the vendor address. |
address_line_2 | string | Optional | Secondary address line of the vendor address. |
city | string | Required within parent | City of the vendor address. |
country | string | Required within parent | Country of the vendor address. |
postal_code | string | Required within parent | Postal or ZIP code of the vendor address. |
state | string | Optional | State or province of the vendor address. |
Create a new vendor — response body — addresses item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
address_line_1 | string | Required within parent | Primary address line of the vendor address. |
address_line_2 | string | Optional | Secondary address line of the vendor address. |
city | string | Required within parent | City of the vendor address. |
country | string | Required within parent | Country of the vendor address. |
id | string | Required within parent | Unique identifier of the vendor address. Format: uuid |
is_default | boolean | Required within parent | Whether this is the vendor's default address. Read only: true |
pay_to_name | string | Required within parent | Recipient name printed on checks mailed to this address. |
postal_code | string | Required within parent | Postal or ZIP code of the vendor address. |
state | string | Optional | State or province of the vendor address. |
Hold Bill — response body — amount
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
amount | JSON | Required within parent | |
amount (anyOf 1) | integer | Alternative | the amount of money represented in the smallest denomination of the currency. For example, when the currency is USD, then the amount is expressed in cents. |
amount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
currency_code | string | Required within parent | The type of currency, in ISO 4217 format. e.g. USD for US dollars Default: USD |
minor_unit_conversion_rate | JSON | Required within parent | |
minor_unit_conversion_rate (anyOf 1) | JSON | Alternative | |
minor_unit_conversion_rate (anyOf 1) (anyOf 1) | integer | Alternative | The conversion factor to convert from the integer amount to the actual currency value. Divide amount by this value to get the real currency amount. For USD, this is 100 (e.g., 12034 / 100 = 120.34 USD). See https://docs.ramp.com/developer-api/v1/monetary-values for more information. Read only: true |
minor_unit_conversion_rate (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
minor_unit_conversion_rate (anyOf 2) | null | Alternative |
Create a new vendor — response body — default payment method policy, update source
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
policy | JSON | Optional | |
policy (anyOf 1) | Model | Alternative | Expand Create a new vendor — response body — default payment method policy, update source policy value |
policy (anyOf 2) | null | Alternative | |
update_source | JSON | Optional | |
update_source (anyOf 1) | string | Alternative | Known values: AUTO, MANUAL |
update_source (anyOf 2) | null | Alternative |
Referenced models: Create a new vendor — response body — default payment method policy, update source policy value
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: ramp.post_vendor_list_resource. Catalog operation: post_vendor_list_resource. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Required provider scopes: ["vendors:write"]