Vendors

Managing vendor data for invoice processing

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:

Extract vendor data from your ERP
Transform to Ottimate’s vendor format
Load via the Vendors API (POST /vendors or POST /vendors/bulk-create/)
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

Field	Type	Description
`ottimate_company_id`	integer	The company this vendor belongs to
`erp_vendor_name`	string	Vendor name (should match your ERP)
`erp_vendor_id`	string	Unique vendor ID from your ERP/accounting system

Optional Fields

Field	Type	Description
`email`	string	Vendor contact email
`phone`	string	Vendor contact phone
`net_terms`	string	Payment terms (e.g., “Net 30”, “Due on receipt”)

Response Fields

Field	Type	Description
`id`	integer	Ottimate-assigned vendor ID (use as `ottimate_vendor_id` in invoice creation)
`created_date`	datetime	When 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:

Format	Example	Calculation	Invoice Date	Due Date
`Net <days>`	Net 10	Days after invoice date	2024-12-01	2024-12-11
`n <days>`	n 10	Days after invoice date	2024-12-01	2024-12-11
`<days>`	10	Days after invoice date	2024-12-01	2024-12-11
`Due on receipt`	Due on receipt	Same as invoice date	2024-12-01	2024-12-01
`EOM <days>`	eom 10	Days after end of invoice month	2024-12-01	2025-01-10
`<days> next month`	Net 10 next month	Day of following month	2024-12-01	2025-01-10
`<day> of month`	10th of month	Next occurrence of that day	2024-12-01	2024-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.

Overview

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:

Extract vendor data from your ERP
Transform to Ottimate’s vendor format
Load via the Vendors API (POST /vendors or POST /vendors/bulk-create/)
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

Field	Type	Description
`ottimate_company_id`	integer	The company this vendor belongs to
`erp_vendor_name`	string	Vendor name (should match your ERP)
`erp_vendor_id`	string	Unique vendor ID from your ERP/accounting system

Optional Fields

Field	Type	Description
`email`	string	Vendor contact email
`phone`	string	Vendor contact phone
`net_terms`	string	Payment terms (e.g., “Net 30”, “Due on receipt”)

Response Fields

Field	Type	Description
`id`	integer	Ottimate-assigned vendor ID (use as `ottimate_vendor_id` in invoice creation)
`created_date`	datetime	When 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:

Format	Example	Calculation	Invoice Date	Due Date
`Net <days>`	Net 10	Days after invoice date	2024-12-01	2024-12-11
`n <days>`	n 10	Days after invoice date	2024-12-01	2024-12-11
`<days>`	10	Days after invoice date	2024-12-01	2024-12-11
`Due on receipt`	Due on receipt	Same as invoice date	2024-12-01	2024-12-01
`EOM <days>`	eom 10	Days after end of invoice month	2024-12-01	2025-01-10
`<days> next month`	Net 10 next month	Day of following month	2024-12-01	2025-01-10
`<day> of month`	10th of month	Next occurrence of that day	2024-12-01	2024-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.

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	}

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	}

$	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"
>	}

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	}

$	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"
>	}
>	]
>	}

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	}

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	}