Skip to navigation
API ReferencePayments

Create a new payments Vendor

Beta

Creates an accounting vendor that payments can be sent to.

There is no upsert. Ottimate matches the request against existing vendors in the company on name, ZIP code and street address, and returns 400 naming the existing vendor when it treats one as a duplicate. The response body of a successful create carries only the new vendor’s id; read the full record back with GET /v1/payments/vendor/{id}.

Send an Idempotency-Key header so a retried create cannot produce a second vendor.

Authentication

AuthorizationBearer
OAuth2 authentication flows. Auth server URLs will vary by environment

Headers

X-Api-KeystringRequired
API key for authentication
X-API-VersionstringOptional

API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.

Idempotency-KeystringOptionalformat: "^[A-Za-z0-9._\-+=/]{1,128}$"<=128 characters

Client-generated unique key (UUID/ULID recommended). JSON requests: the first 2xx response is cached for 24h and replayed on a same-key retry with a matching body; a different body returns 422. Non-JSON requests (e.g. file uploads): the key is single-use — any same-key retry returns 422 regardless of body. See Idempotency for full details.

Request

This endpoint expects an object.
ottimate_company_idstringRequired

The Ottimate company ID to create this vendor in, as a numeric string (digits only). Your API user must have access to the company, or the request returns 401.

namestringRequired
The vendor's business name.
erp_vendor_idstringRequired<=200 characters
The vendor's unique identifier in your ERP system.
emailstringRequiredformat: "email"
The vendor's primary email address.
phone_numberstringRequired
The vendor's primary phone number.
address_line_1stringRequired
The first line of the vendor's mailing address.
citystringRequired
The city of the vendor's mailing address.
statestringRequired<=2 characters

The two-letter state code of the vendor’s mailing address.

zipcodestringRequired5-10 characters
The ZIP code of the vendor's mailing address.
customer_account_numberstring or nullOptional<=256 characters
Your account number with the vendor.
invite_electronic_paymentsboolean or nullOptional
Whether Ottimate should invite this vendor to enroll in electronic payments.
estimated_monthly_volumeinteger or nullOptional>=0
Estimated monthly payment volume to this vendor in dollars.
contact_namestring or nullOptional
The vendor's primary contact name.
address_line_2stringOptional
The second line of the vendor's mailing address.
countrystring or nullOptional<=2 characters

The two-letter ISO country code of the vendor’s mailing address.

care_ofstring or nullOptional

The care-of name for the vendor’s mailing address.

admin_emailstringOptionalformat: "email"
The email address of the vendor's admin contact.
admin_phonestringOptional
The phone number of the vendor's admin contact.
admin_namestringOptional
The name of the vendor's admin contact.
metadataobjectOptional

Arbitrary key-value metadata to store on the vendor. Returned unchanged by GET /v1/payments/vendor/{id}.

Response

Vendor created
vendorobject

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
422
Unprocessable Entity Error