Account Set UpAccounting Integration

Vendors

Managing vendor data for invoice processing

Overview

A vendor represents an organization that provides goods or services to a company. Vendors issue invoices that flow through Ottimate’s AP automation workflow. Before you can create invoices in Ottimate, the associated vendor must exist in the system.

Key Characteristics:

  • Vendors are company-specific - each company maintains its own vendor list
  • Vendors must be synced from your ERP to enable invoice export
  • The erp_vendor_id links Ottimate vendors to your accounting system
  • Vendors are identified by id (Ottimate-assigned) or erp_vendor_id (your ERP’s ID)

Vendor Data Flow

Understanding when and how vendor data flows between systems:

ERP/Accounting System                    Ottimate
┌──────────────────────┐              ┌──────────────────────┐
│                      │              │                      │
│  Vendor Master List  │──── Sync ───▶│  Ottimate Vendors    │
│                      │              │                      │
│  - Vendor ID         │              │  - id (Ottimate)     │
│  - Vendor Name       │              │  - erp_vendor_id     │
│  - Payment Terms     │              │  - erp_vendor_name   │
│  - Contact Info      │              │  - net_terms         │
│                      │              │                      │
└──────────────────────┘              └──────────────────────┘
                                               │
                                               ▼
                                      ┌──────────────────────┐
                                      │  Invoice Created     │
                                      │  with vendor info    │
                                      └──────────────────────┘
                                               │
                                               ▼
                                      ┌──────────────────────┐
                                      │  Approved invoice    │
                                      │  exported to ERP     │
                                      │  using erp_vendor_id │
                                      └──────────────────────┘

Sync Patterns

Ottimate-Hosted ERP Integrations

When you use an Ottimate-hosted integration (e.g., QuickBooks, NetSuite, Sage), Ottimate automatically syncs vendors from your ERP:

  • Initial sync happens during onboarding
  • Ongoing sync keeps vendors updated automatically
  • No API calls needed - vendor management is handled by the integration

In this scenario, you primarily use the Vendors API to read vendor data for reference or validation.

Custom ERP Integrations

If you’re building a custom integration with an unsupported ERP, you’re responsible for syncing vendors:

  1. Extract vendor data from your ERP
  2. Transform to Ottimate’s vendor format
  3. Load via the Vendors API (POST /vendors or POST /vendors/bulk-create/)
  4. Maintain ongoing sync as vendors are added/updated in your ERP

Keep vendor data consistent between Ottimate and your ERP. Mismatched vendor names or IDs can cause issues during invoice export.

Vendor Fields

Required Fields

FieldTypeDescription
ottimate_company_idintegerThe company this vendor belongs to
erp_vendor_namestringVendor name (should match your ERP)
erp_vendor_idstringUnique vendor ID from your ERP/accounting system

Optional Fields

FieldTypeDescription
emailstringVendor contact email
phonestringVendor contact phone
net_termsstringPayment terms (e.g., “Net 30”, “Due on receipt”)

Response Fields

FieldTypeDescription
idintegerOttimate-assigned vendor ID (use as ottimate_vendor_id in invoice creation)
created_datedatetimeWhen the vendor was created in Ottimate

API Operations

List Vendors

Retrieve all vendors for a company:

$GET /v1/vendors?ottimate_company_id=123

Response:

1{
2  "version": "1.0.0",
3  "count": 100,
4  "page": 1,
5  "limit": 20,
6  "vendors": [
7    {
8      "id": 169860239,
9      "erp_vendor_name": "Sysco Foods Corp",
10      "erp_vendor_id": "SYS-001",
11      "ottimate_company_id": 123
12    },
13    {
14      "id": 169860240,
15      "erp_vendor_name": "US Foods Inc",
16      "erp_vendor_id": "USF-002",
17      "ottimate_company_id": 123
18    }
19  ]
20}

Get Single Vendor

Retrieve a specific vendor by Ottimate ID:

$GET /v1/vendors/169860239

Response:

1{
2  "version": "1.0.0",
3  "vendor": {
4    "id": "169860239",
5    "erp_vendor_name": "Sysco Foods Corp",
6    "erp_vendor_id": "SYS-001",
7    "ottimate_company_id": 123
8  }
9}

Create Single Vendor

Create a new vendor:

$POST /v1/vendors
$Content-Type: application/json
$
${
>  "ottimate_company_id": 123,
>  "erp_vendor_name": "New Food Supplier Inc",
>  "erp_vendor_id": "NFS-001",
>  "email": "orders@newfoodsupplier.com",
>  "phone": "+1-555-123-4567",
>  "net_terms": "Net 30"
>}

Response (201 Created):

1{
2  "version": "1.0.0",
3  "id": "169860250",
4  "erp_vendor_name": "New Food Supplier Inc",
5  "erp_vendor_id": "NFS-001",
6  "ottimate_company_id": 123,
7  "email": "orders@newfoodsupplier.com",
8  "phone": "+1-555-123-4567",
9  "net_terms": "Net 30",
10  "created_date": "2024-12-05T10:30:00Z"
11}

Bulk Create/Update Vendors

Create or update multiple vendors in a single request. This endpoint uses upsert behavior - existing vendors (matched by erp_vendor_id) are updated, new vendors are created.

$POST /v1/vendors/bulk-create/
$Content-Type: application/json
$
${
>  "ottimate_company_id": 123,
>  "vendors": [
>    {
>      "erp_vendor_name": "Local Produce Co",
>      "erp_vendor_id": "LPC-001"
>    },
>    {
>      "erp_vendor_name": "Premium Meats LLC",
>      "erp_vendor_id": "PML-001"
>    },
>    {
>      "erp_vendor_name": "Sysco Foods Corp (Updated)",
>      "erp_vendor_id": "SYS-001"
>    }
>  ]
>}

Response (201 Created):

1{
2  "version": "1.0.0",
3  "success_count": 3,
4  "created_count": 2,
5  "updated_count": 1,
6  "error_count": 0,
7  "created": [
8    {
9      "id": "169860251",
10      "erp_vendor_name": "Local Produce Co"
11    },
12    {
13      "id": "169860252",
14      "erp_vendor_name": "Premium Meats LLC"
15    }
16  ],
17  "updated": [
18    {
19      "id": "169860239",
20      "erp_vendor_name": "Sysco Foods Corp (Updated)"
21    }
22  ],
23  "errors": []
24}

Partial Failure Response (207 Multi-Status):

If some vendors fail validation, you’ll receive a 207 response:

1{
2  "version": "1.0.0",
3  "success_count": 1,
4  "created_count": 1,
5  "updated_count": 0,
6  "error_count": 1,
7  "created": [
8    {
9      "id": "169860253",
10      "erp_vendor_name": "Seafood Distributors"
11    }
12  ],
13  "updated": [],
14  "errors": [
15    {
16      "index": 1,
17      "erp_vendor_id": null,
18      "error": "erp_vendor_id is required",
19      "type": "validation_error"
20    }
21  ]
22}

Net Terms

The net_terms field defines payment terms negotiated with the vendor. When provided, Ottimate automatically calculates invoice due dates.

Accepted Formats:

FormatExampleCalculationInvoice DateDue Date
Net <days>Net 10Days after invoice date2024-12-012024-12-11
n <days>n 10Days after invoice date2024-12-012024-12-11
<days>10Days after invoice date2024-12-012024-12-11
Due on receiptDue on receiptSame as invoice date2024-12-012024-12-01
EOM <days>eom 10Days after end of invoice month2024-12-012025-01-10
<days> next monthNet 10 next monthDay of following month2024-12-012025-01-10
<day> of month10th of monthNext occurrence of that day2024-12-012024-12-10

Net terms are optional. If not provided, invoice due dates must be set manually or calculated by your integration.

Best Practices

  • Sync vendors before invoices - Ensure vendors exist in Ottimate before creating invoices that reference them.
  • Use bulk-create for efficiency - When syncing multiple vendors, use the bulk endpoint to reduce API calls.
  • Match ERP identifiers exactly - The erp_vendor_id must match your ERP’s vendor ID for successful invoice export.
  • Keep names consistent - Use the same vendor name in Ottimate as in your ERP to avoid confusion during reconciliation.
  • Cache vendor mappings - Fetch and cache the vendor list at integration startup to avoid repeated API calls.
  • Handle partial failures - When using bulk-create, check the errors array and handle failed vendors appropriately.
  • Set net_terms for automation - Providing payment terms enables automatic due date calculation.