TallyPip
Start free

API reference

Vendor

Someone the business buys from. Bills and expenses can name a vendor.

The vendor object

object string
Always "vendor".
id id
The vendor's id (a UUID). Use it to fetch it, or to refer to it from other things.
name string
The display name: what invoices, bills and lists show.
company_name string or null
The company's name, when different.
title string or null
Mr., Ms., Dr.…
first_name string or null
First name of the person to deal with.
middle_name string or null
Middle name.
last_name string or null
Last name.
suffix string or null
Jr., Sr.…
email string or null
Email address (where invoices or remittances go).
cc string or null
More addresses copied on emails, separated by commas.
bcc string or null
Addresses blind-copied on emails.
phone string or null
Phone.
mobile string or null
Mobile.
fax string or null
Fax.
website string or null
Website.
address string or null
Billing address; lines separated by \n.
terms string or null
Usual payment terms: due_on_receipt, net_7, net_15, net_30 or net_60.
notes string or null
Private notes.
active boolean
False once it's made inactive in TallyPip (it's kept, with its history, but left out of pickers).
created_at timestamp
When it was added, in UTC.
currency string or null
Their currency when it isn't the business's (Multicurrency, like EUR): their bills are in it. Null otherwise.
print_on_check_name string or null
The name printed on checks, if different.
account_number string or null
The business's account number with this vendor.
track_1099 boolean
True if payments to them are tracked for 1099s (US contractors). Their tax ID is never sent through the API.
default_expense_account_id id or null
The expense category TallyPip suggests for their bills and expenses (an account).

Example

{
  "object": "vendor",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708102",
  "name": "Hillside Supply Co.",
  "company_name": "Hillside Supply Co.",
  "title": null,
  "first_name": null,
  "middle_name": null,
  "last_name": null,
  "suffix": null,
  "email": "billing@hillside.example",
  "cc": null,
  "bcc": null,
  "phone": null,
  "mobile": null,
  "fax": null,
  "website": null,
  "address": null,
  "terms": "net_15",
  "notes": null,
  "active": true,
  "created_at": "2026-10-06T14:30:00.000Z",
  "currency": null,
  "print_on_check_name": null,
  "account_number": "C-4471",
  "track_1099": false,
  "default_expense_account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708130"
}

List vendors

GET /api/v1/vendors

Vendors, newest first.

Key: any (Read only works).

Query

limit integer
How many, 1 to 100 (default 25).
starting_after id
The last id of the page before, for the next page (when has_more is true).
filters
email, name (exact, ignoring capitals)

Newest first. Answers a list: { object: "list", url, has_more, data }.

Request

curl https://tallypip.com/api/v1/vendors?limit=3 \
  -H "Authorization: Bearer tpk_your_key"

Answer: 200

{
  "object": "list",
  "url": "/api/v1/vendors",
  "has_more": false,
  "data": [
    {
      "object": "vendor",
      "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708102",
      "name": "Hillside Supply Co.",
      "company_name": "Hillside Supply Co.",
      "title": null,
      "first_name": null,
      "middle_name": null,
      "last_name": null,
      "suffix": null,
      "email": "billing@hillside.example",
      "cc": null,
      "bcc": null,
      "phone": null,
      "mobile": null,
      "fax": null,
      "website": null,
      "address": null,
      "terms": "net_15",
      "notes": null,
      "active": true,
      "created_at": "2026-10-06T14:30:00.000Z",
      "currency": null,
      "print_on_check_name": null,
      "account_number": "C-4471",
      "track_1099": false,
      "default_expense_account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708130"
    }
  ]
}

Try it

With your own key (Settings › Connected apps). It stays in this page only, and reading can't change anything.

Create a vendor

POST /api/v1/vendors

Add a vendor.

Key: Read and change.

Body (JSON)

name string
Required.
email, phone, address, … (as customers) string
Optional.
print_on_check_name, account_number string
Optional.
track_1099 boolean
Optional (US contractors).
default_expense_account_id id
Optional. An expense account from /accounts.

Answers 201 with the new vendor. Refused with 400 and the reason (nothing is saved); send an Idempotency-Key so a retry can't make it twice.

Request

curl https://tallypip.com/api/v1/vendors \
  -H "Authorization: Bearer tpk_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <a new id for each change>" \
  -d '{
    "name": "Hillside Supply Co.",
    "email": "billing@hillside.example",
    "terms": "net_15",
    "default_expense_account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708130"
  }'

Answer: 201

{
  "object": "vendor",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708102",
  "name": "Hillside Supply Co.",
  "company_name": "Hillside Supply Co.",
  "title": null,
  "first_name": null,
  "middle_name": null,
  "last_name": null,
  "suffix": null,
  "email": "billing@hillside.example",
  "cc": null,
  "bcc": null,
  "phone": null,
  "mobile": null,
  "fax": null,
  "website": null,
  "address": null,
  "terms": "net_15",
  "notes": null,
  "active": true,
  "created_at": "2026-10-06T14:30:00.000Z",
  "currency": null,
  "print_on_check_name": null,
  "account_number": "C-4471",
  "track_1099": false,
  "default_expense_account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708130"
}

Retrieve a vendor

GET /api/v1/vendors/{id}

One vendor.

Key: any (Read only works).

Request

curl https://tallypip.com/api/v1/vendors/3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708102 \
  -H "Authorization: Bearer tpk_your_key"

Answer: 200

{
  "object": "vendor",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708102",
  "name": "Hillside Supply Co.",
  "company_name": "Hillside Supply Co.",
  "title": null,
  "first_name": null,
  "middle_name": null,
  "last_name": null,
  "suffix": null,
  "email": "billing@hillside.example",
  "cc": null,
  "bcc": null,
  "phone": null,
  "mobile": null,
  "fax": null,
  "website": null,
  "address": null,
  "terms": "net_15",
  "notes": null,
  "active": true,
  "created_at": "2026-10-06T14:30:00.000Z",
  "currency": null,
  "print_on_check_name": null,
  "account_number": "C-4471",
  "track_1099": false,
  "default_expense_account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708130"
}

Try it

With your own key (Settings › Connected apps). It stays in this page only, and reading can't change anything.