Vendors
The companies you buy from. Bank details are never returned - see Conventions.
The object#
| Field | Type | Description |
|---|---|---|
| name | string(30) | Last name, for an individual vendor. The display name uses companyname when that is set, otherwise the personal name fields. |
| idread-only | integer | NolaPro id. |
| orderfromname | string(30) | Contact name on the Order From address block - where purchase orders go when ordering differs from the payment address. |
| paytermsid | integer | Paytermsid. Id only - the table this points at is not identifiable from the column name, so there is no human key to send instead. |
| paynone | integer | 1 puts the vendor on payment hold: payment runs set to skip held vendors exclude their bills, and bill lists mark the vendor with *. |
| defaultglacctid | integer | Reference to glaccounts, by id. Write either this or defaultglacct. |
| defaultglacct | string(20) | Code for the referenced glaccount, instead of the id. |
| defaultbilldescription | string(50) | Description pre-filled on new bills entered for this vendor. |
| customeraccount | string(20) | Your account number with this vendor, printed on payments. |
| cancel | boolean | Cancelled. Always a boolean on the wire, whatever integer width the column uses (D23). |
| entrydateread-only | string | When the record was created. |
| lastchangedateread-only | string | Last modification. Drives modifiedsince. |
| companyname | string(100) | Company name. When set it is the vendor’s display name; otherwise the salutation/first/middle/name/suffix fields are used. |
| address1 | string(100) | Street address. |
| address2 | string(100) | Second address line. |
| mailstop | string(20) | Mail stop line printed with the payment address. |
| city | string(50) | City of the payment address. |
| state | string(20) | State of the payment address. |
| zip | string(15) | Postal code. |
| country | string(20) | Country of the payment address. |
| phone1 | string(20) | Primary phone. |
| phone1comment | string(20) | Label describing what phone1 reaches (Office, Mobile, ...). |
| phone2 | string(20) | Additional phone number. |
| phone2comment | string(20) | Label describing what phone2 reaches (Office, Mobile, ...). |
| phone3 | string(20) | Additional phone number. |
| phone3comment | string(20) | Label describing what phone3 reaches (Office, Mobile, ...). |
| phone4 | string(20) | Additional phone number. |
| phone4comment | string(20) | Label describing what phone4 reaches (Office, Mobile, ...). |
| email1 | string(255) | Primary email address. |
| email1comment | string(20) | Label describing what email1 is for. |
| email2 | string(255) | Secondary email. |
| email2comment | string(20) | Label describing what email2 is for. |
| website | string(100) | Vendor’s website URL. |
| orderfrom_companyname | string(100) | Company name on the Order From address, when purchase orders go to a different address than payments. |
| orderfrom_address1 | string(100) | Street address line 1 of the Order From address. |
| orderfrom_address2 | string(100) | Street address line 2 of the Order From address. |
| orderfrom_mailstop | string(20) | Mail stop line of the Order From address. |
| orderfrom_city | string(50) | City of the Order From address. |
| orderfrom_state | string(20) | State of the Order From address. |
| orderfrom_zip | string(15) | ZIP/postal code of the Order From address. |
| orderfrom_country | string(20) | Country of the Order From address. |
| imageread-only | string(64) | Filename of the picture uploaded on the vendor screen. Managed by the file upload, so it cannot be written through the API. |
| default_cost_per_hourmoney | string(6dp) | Stored as decimal(12,6). |
| vendor_code | string(50) | Vendor number, shown as Vendor Code on the vendor screens. Auto-assigned from the company’s next-vendor-code counter when left blank. |
| vendor_lead_time | integer | Lead time in days. New purchase orders default their due date this many days out. |
| carrierserviceid | integer | Default carrier service (ship method) for this vendor’s purchase orders. |
| carrierservice | string(100) | Code for the referenced carrierservice, instead of the id. |
| noreturns | integer | 1 blocks RMA returns to this vendor. |
| percent_commissionnumber | string(4dp) | Numeric string, 4 decimal places. Not money - do not apply currency rounding. |
| flat_commissionmoney | string(4dp) | Stored as decimal(12,4). |
| parent_vendorid | integer | Parent vendor, when this record is a location or division of a larger vendor. |
| parent_vendor | string(30) | Vendor code of the parent vendor. Send this or parent_vendorid, not both unless they agree. |
| taxgroupid | integer | Tax group applied to this vendor’s purchases. |
| taxgroup | string(20) | Code for the referenced taxgroup, instead of the id. |
| vendorcode | string(30) | Older short vendor code, appended to the display name in parentheses. |
| salutation | string(20) | Salutation for an individual vendor (Mr., Ms., ...). |
| first_name | string(50) | First name, for an individual vendor. |
| middle_name | string(50) | Middle name, for an individual vendor. |
| name_suffix | string(20) | Name suffix for an individual vendor (Jr., III, ...). |
| vendortypeid | integer | Reference to vendortypes, by id. Write either this or vendortype. |
| vendortype | string(100) | Code for the referenced vendortype, instead of the id. |
| default_retainermoney | string(3dp) | Stored as decimal(6,3). |
| currency | string(10) | Currency the vendor bills in. Bills and purchase orders for the vendor default to it. |
| gets1099 | integer | 1 when the vendor receives a 1099 at year end. |
| basevendorid | integer | Reference to vendors, by id. Write either this or basevendor. |
| basevendor | string(30) | Vendor code of the base vendor. Send this or basevendorid, not both unless they agree. |
| buyeruserid | integer | Buyeruserid. Id only. |
| buyeruser | string(50) | Login name of the buyer. Send this or buyeruserid, not both unless they agree. |
| default_checkacctid | integer | Checking account payments to this vendor default to. |
| default_checkacct | string(30) | Name of the default bank account. Send this or default_checkacctid, not both unless they agree. |
| default_paymethod | integer | Default payment method for bills: 1 = cash, 2 = check, 3 = credit card, 4 = ACH/EFT; 0 when none is set. |
| lead | boolean | True when the record is a prospective vendor entered as a lead (Leads feature) rather than an active vendor. |
| orderfrom_email | string(255) | Email address purchase orders are sent to. |
| orderfrom_fax | string(20) | Fax number for sending purchase orders. |
| orderfrom_phone | string(20) | Phone number of the ordering contact. |
| paytoname | string(150) | Pay To name printed on checks, when different from the vendor name. |
| taskstatusid | integer | Reference to taskstatuses, by id. Write either this or taskstatus. |
| taskstatus | string(100) | Task status name. Send this or taskstatusid, not both unless they agree. |
| timezoneid | integer | Reference to timezones, by id. Write either this or timezone. |
| timezone | string(64) | IANA time zone name. Send this or timezoneid, not both unless they agree. |
| insuranceemail | string(50) | Email address of the vendor’s insurance contact, used for certificate-of-insurance tracking. |
| insuranceemailcomment | string(50) | Label describing the insurance email contact. |
| insurancephone | string(20) | Phone number of the vendor’s insurance contact. |
| insurancephonecomment | string(50) | Label describing the insurance phone contact. |
| paytoemail | string(255) | Email address payment remittances are sent to. |
| excludefrompaymentreport | boolean | True leaves the vendor off payment reports. |
| insurancefax | string(20) | Fax number of the vendor’s insurance contact. |
| insurancefaxcomment | string(50) | Label describing the insurance fax contact. |
| addressverifiedread-only | string(32) | Hash of the address as it stood when it last passed the AvaTax/USPS address check; when it no longer matches the current address the address counts as unverified. Maintained by the verification flow, so it cannot be written through the API. |
| displaynameread-only | string(255) | STORED GENERATED in the database. Read-only - MySQL computes it, and a value sent here is silently discarded. |
| displaynamenocoderead-only | string(255) | STORED GENERATED in the database. Read-only - MySQL computes it, and a value sent here is silently discarded. |
| externalid | string(100) | Your own key. Scoped to your company. |
Endpoints#
Create many.
Requires scope vendors:write.
| Name | In | Type | Notes |
|---|---|---|---|
| Idempotency-Key | header | string | Makes the write safely retryable. Any unique string per logical operation; a UUID is fine.
The failure this prevents is specific: the request succeeds, the response is lost to a timeout, you retry, and the customer is billed twice. With a key, the retry returns the original response - same status, same body, same id - and creates nothing.
The body is part of the key's identity. Reusing a key with a different body is a bug on your side, not a retry, and answers 409 idempotency_replay rather than silently handing back the old response. Keys are remembered for 24 hours. |
| Field | Type | Description |
|---|---|---|
| name | string(30) | Last name, for an individual vendor. The display name uses companyname when that is set, otherwise the personal name fields. |
| idread-only | integer | NolaPro id. |
| orderfromname | string(30) | Contact name on the Order From address block - where purchase orders go when ordering differs from the payment address. |
| paytermsid | integer | Paytermsid. Id only - the table this points at is not identifiable from the column name, so there is no human key to send instead. |
| paynone | integer | 1 puts the vendor on payment hold: payment runs set to skip held vendors exclude their bills, and bill lists mark the vendor with *. |
| defaultglacctid | integer | Reference to glaccounts, by id. Write either this or defaultglacct. |
| defaultglacct | string(20) | Code for the referenced glaccount, instead of the id. |
| defaultbilldescription | string(50) | Description pre-filled on new bills entered for this vendor. |
| customeraccount | string(20) | Your account number with this vendor, printed on payments. |
| cancel | boolean | Cancelled. Always a boolean on the wire, whatever integer width the column uses (D23). |
| entrydateread-only | string | When the record was created. |
| lastchangedateread-only | string | Last modification. Drives modifiedsince. |
| companyname | string(100) | Company name. When set it is the vendor’s display name; otherwise the salutation/first/middle/name/suffix fields are used. |
| address1 | string(100) | Street address. |
| address2 | string(100) | Second address line. |
| mailstop | string(20) | Mail stop line printed with the payment address. |
| city | string(50) | City of the payment address. |
| state | string(20) | State of the payment address. |
| zip | string(15) | Postal code. |
| country | string(20) | Country of the payment address. |
| phone1 | string(20) | Primary phone. |
| phone1comment | string(20) | Label describing what phone1 reaches (Office, Mobile, ...). |
| phone2 | string(20) | Additional phone number. |
| phone2comment | string(20) | Label describing what phone2 reaches (Office, Mobile, ...). |
| phone3 | string(20) | Additional phone number. |
| phone3comment | string(20) | Label describing what phone3 reaches (Office, Mobile, ...). |
| phone4 | string(20) | Additional phone number. |
| phone4comment | string(20) | Label describing what phone4 reaches (Office, Mobile, ...). |
| email1 | string(255) | Primary email address. |
| email1comment | string(20) | Label describing what email1 is for. |
| email2 | string(255) | Secondary email. |
| email2comment | string(20) | Label describing what email2 is for. |
| website | string(100) | Vendor’s website URL. |
| orderfrom_companyname | string(100) | Company name on the Order From address, when purchase orders go to a different address than payments. |
| orderfrom_address1 | string(100) | Street address line 1 of the Order From address. |
| orderfrom_address2 | string(100) | Street address line 2 of the Order From address. |
| orderfrom_mailstop | string(20) | Mail stop line of the Order From address. |
| orderfrom_city | string(50) | City of the Order From address. |
| orderfrom_state | string(20) | State of the Order From address. |
| orderfrom_zip | string(15) | ZIP/postal code of the Order From address. |
| orderfrom_country | string(20) | Country of the Order From address. |
| imageread-only | string(64) | Filename of the picture uploaded on the vendor screen. Managed by the file upload, so it cannot be written through the API. |
| default_cost_per_hourmoney | string(6dp) | Stored as decimal(12,6). |
| vendor_code | string(50) | Vendor number, shown as Vendor Code on the vendor screens. Auto-assigned from the company’s next-vendor-code counter when left blank. |
| vendor_lead_time | integer | Lead time in days. New purchase orders default their due date this many days out. |
| carrierserviceid | integer | Default carrier service (ship method) for this vendor’s purchase orders. |
| carrierservice | string(100) | Code for the referenced carrierservice, instead of the id. |
| noreturns | integer | 1 blocks RMA returns to this vendor. |
| percent_commissionnumber | string(4dp) | Numeric string, 4 decimal places. Not money - do not apply currency rounding. |
| flat_commissionmoney | string(4dp) | Stored as decimal(12,4). |
| parent_vendorid | integer | Parent vendor, when this record is a location or division of a larger vendor. |
| parent_vendor | string(30) | Vendor code of the parent vendor. Send this or parent_vendorid, not both unless they agree. |
| taxgroupid | integer | Tax group applied to this vendor’s purchases. |
| taxgroup | string(20) | Code for the referenced taxgroup, instead of the id. |
| vendorcode | string(30) | Older short vendor code, appended to the display name in parentheses. |
| salutation | string(20) | Salutation for an individual vendor (Mr., Ms., ...). |
| first_name | string(50) | First name, for an individual vendor. |
| middle_name | string(50) | Middle name, for an individual vendor. |
| name_suffix | string(20) | Name suffix for an individual vendor (Jr., III, ...). |
| vendortypeid | integer | Reference to vendortypes, by id. Write either this or vendortype. |
| vendortype | string(100) | Code for the referenced vendortype, instead of the id. |
| default_retainermoney | string(3dp) | Stored as decimal(6,3). |
| currency | string(10) | Currency the vendor bills in. Bills and purchase orders for the vendor default to it. |
| gets1099 | integer | 1 when the vendor receives a 1099 at year end. |
| basevendorid | integer | Reference to vendors, by id. Write either this or basevendor. |
| basevendor | string(30) | Vendor code of the base vendor. Send this or basevendorid, not both unless they agree. |
| buyeruserid | integer | Buyeruserid. Id only. |
| buyeruser | string(50) | Login name of the buyer. Send this or buyeruserid, not both unless they agree. |
| default_checkacctid | integer | Checking account payments to this vendor default to. |
| default_checkacct | string(30) | Name of the default bank account. Send this or default_checkacctid, not both unless they agree. |
| default_paymethod | integer | Default payment method for bills: 1 = cash, 2 = check, 3 = credit card, 4 = ACH/EFT; 0 when none is set. |
| lead | boolean | True when the record is a prospective vendor entered as a lead (Leads feature) rather than an active vendor. |
| orderfrom_email | string(255) | Email address purchase orders are sent to. |
| orderfrom_fax | string(20) | Fax number for sending purchase orders. |
| orderfrom_phone | string(20) | Phone number of the ordering contact. |
| paytoname | string(150) | Pay To name printed on checks, when different from the vendor name. |
| taskstatusid | integer | Reference to taskstatuses, by id. Write either this or taskstatus. |
| taskstatus | string(100) | Task status name. Send this or taskstatusid, not both unless they agree. |
| timezoneid | integer | Reference to timezones, by id. Write either this or timezone. |
| timezone | string(64) | IANA time zone name. Send this or timezoneid, not both unless they agree. |
| insuranceemail | string(50) | Email address of the vendor’s insurance contact, used for certificate-of-insurance tracking. |
| insuranceemailcomment | string(50) | Label describing the insurance email contact. |
| insurancephone | string(20) | Phone number of the vendor’s insurance contact. |
| insurancephonecomment | string(50) | Label describing the insurance phone contact. |
| paytoemail | string(255) | Email address payment remittances are sent to. |
| excludefrompaymentreport | boolean | True leaves the vendor off payment reports. |
| insurancefax | string(20) | Fax number of the vendor’s insurance contact. |
| insurancefaxcomment | string(50) | Label describing the insurance fax contact. |
| addressverifiedread-only | string(32) | Hash of the address as it stood when it last passed the AvaTax/USPS address check; when it no longer matches the current address the address counts as unverified. Maintained by the verification flow, so it cannot be written through the API. |
| displaynameread-only | string(255) | STORED GENERATED in the database. Read-only - MySQL computes it, and a value sent here is silently discarded. |
| displaynamenocoderead-only | string(255) | STORED GENERATED in the database. Read-only - MySQL computes it, and a value sent here is silently discarded. |
| externalid | string(100) | Your own key. Scoped to your company. |
curl -X POST \ 'https://acme.nolapro.com/!/api/v2/vendors/batch' \ -H 'Authorization: Bearer $NP_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: your-unique-key' \ -d '[ { "name": "Example name", "orderfromname": "Example orderfromname", "paytermsid": 104, "paynone": 1, "defaultglacctid": 104, "defaultglacct": "Example defaultglacct" } ]'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/vendors/batch'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => json_encode([ [ 'name' => 'Example name', 'orderfromname' => 'Example orderfromname', 'paytermsid' => 104, 'paynone' => 1, 'defaultglacctid' => 104, 'defaultglacct' => 'Example defaultglacct', ], ]), ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.post( "https://acme.nolapro.com/!/api/v2/vendors/batch", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, json=[ { "name": "Example name", "orderfromname": "Example orderfromname", "paytermsid": 104, "paynone": 1, "defaultglacctid": 104, "defaultglacct": "Example defaultglacct", }, ], ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/vendors/batch', { method: 'POST', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, body: JSON.stringify([ { name: "Example name", orderfromname: "Example orderfromname", paytermsid: 104, paynone: 1, defaultglacctid: 104, defaultglacct: "Example defaultglacct", }, ]), } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var body = new[] { new { name = "Example name", orderfromname = "Example orderfromname", paytermsid = 104, paynone = 1, defaultglacctid = 104, defaultglacct = "Example defaultglacct", }, }; var req = new HttpRequestMessage(HttpMethod.Post, "https://acme.nolapro.com/!/api/v2/vendors/batch") { Content = JsonContent.Create(body), }; req.Headers.Add("Idempotency-Key", "your-unique-key"); var res = await http.SendAsync(req); res.EnsureSuccessStatusCode();
List vendors.
Requires scope vendors:read.
| Name | In | Type | Notes |
|---|---|---|---|
| name | query | string | name. Partial match, case-insensitive. |
| vendorcode | query | string | Partial match, case insensitive. |
| cancel | query | string | Defaults to false. Pass true or any. |
| modifiedsince | query | string | RFC 3339 UTC timestamp. Returns only records changed since then, including cancelled ones - so cancel defaults to any rather than false when this is used. The response carries _meta.synced_through; store it and send it back next time. |
| externalid | query | string | Exact match on your own key. |
| include | query | string | Comma-separated extras to embed. Only custom_fields is available: the extra fields this install has defined on the record. Off by default, and an unrecognised value is refused rather than ignored. See Conventions. |
| Status | Code | Meaning |
|---|---|---|
| 403 | insufficient_scope | Token lacks read scope. |
curl \ 'https://acme.nolapro.com/!/api/v2/vendors' \ -H 'Authorization: Bearer $NP_TOKEN'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/vendors'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.get( "https://acme.nolapro.com/!/api/v2/vendors", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/vendors', { method: 'GET', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var res = await http.GetAsync( "https://acme.nolapro.com/!/api/v2/vendors"); res.EnsureSuccessStatusCode();
Create.
Requires scope vendors:write.
| Name | In | Type | Notes |
|---|---|---|---|
| Idempotency-Key | header | string | Makes the write safely retryable. Any unique string per logical operation; a UUID is fine.
The failure this prevents is specific: the request succeeds, the response is lost to a timeout, you retry, and the customer is billed twice. With a key, the retry returns the original response - same status, same body, same id - and creates nothing.
The body is part of the key's identity. Reusing a key with a different body is a bug on your side, not a retry, and answers 409 idempotency_replay rather than silently handing back the old response. Keys are remembered for 24 hours. |
| Field | Type | Description |
|---|---|---|
| name | string(30) | Last name, for an individual vendor. The display name uses companyname when that is set, otherwise the personal name fields. |
| idread-only | integer | NolaPro id. |
| orderfromname | string(30) | Contact name on the Order From address block - where purchase orders go when ordering differs from the payment address. |
| paytermsid | integer | Paytermsid. Id only - the table this points at is not identifiable from the column name, so there is no human key to send instead. |
| paynone | integer | 1 puts the vendor on payment hold: payment runs set to skip held vendors exclude their bills, and bill lists mark the vendor with *. |
| defaultglacctid | integer | Reference to glaccounts, by id. Write either this or defaultglacct. |
| defaultglacct | string(20) | Code for the referenced glaccount, instead of the id. |
| defaultbilldescription | string(50) | Description pre-filled on new bills entered for this vendor. |
| customeraccount | string(20) | Your account number with this vendor, printed on payments. |
| cancel | boolean | Cancelled. Always a boolean on the wire, whatever integer width the column uses (D23). |
| entrydateread-only | string | When the record was created. |
| lastchangedateread-only | string | Last modification. Drives modifiedsince. |
| companyname | string(100) | Company name. When set it is the vendor’s display name; otherwise the salutation/first/middle/name/suffix fields are used. |
| address1 | string(100) | Street address. |
| address2 | string(100) | Second address line. |
| mailstop | string(20) | Mail stop line printed with the payment address. |
| city | string(50) | City of the payment address. |
| state | string(20) | State of the payment address. |
| zip | string(15) | Postal code. |
| country | string(20) | Country of the payment address. |
| phone1 | string(20) | Primary phone. |
| phone1comment | string(20) | Label describing what phone1 reaches (Office, Mobile, ...). |
| phone2 | string(20) | Additional phone number. |
| phone2comment | string(20) | Label describing what phone2 reaches (Office, Mobile, ...). |
| phone3 | string(20) | Additional phone number. |
| phone3comment | string(20) | Label describing what phone3 reaches (Office, Mobile, ...). |
| phone4 | string(20) | Additional phone number. |
| phone4comment | string(20) | Label describing what phone4 reaches (Office, Mobile, ...). |
| email1 | string(255) | Primary email address. |
| email1comment | string(20) | Label describing what email1 is for. |
| email2 | string(255) | Secondary email. |
| email2comment | string(20) | Label describing what email2 is for. |
| website | string(100) | Vendor’s website URL. |
| orderfrom_companyname | string(100) | Company name on the Order From address, when purchase orders go to a different address than payments. |
| orderfrom_address1 | string(100) | Street address line 1 of the Order From address. |
| orderfrom_address2 | string(100) | Street address line 2 of the Order From address. |
| orderfrom_mailstop | string(20) | Mail stop line of the Order From address. |
| orderfrom_city | string(50) | City of the Order From address. |
| orderfrom_state | string(20) | State of the Order From address. |
| orderfrom_zip | string(15) | ZIP/postal code of the Order From address. |
| orderfrom_country | string(20) | Country of the Order From address. |
| imageread-only | string(64) | Filename of the picture uploaded on the vendor screen. Managed by the file upload, so it cannot be written through the API. |
| default_cost_per_hourmoney | string(6dp) | Stored as decimal(12,6). |
| vendor_code | string(50) | Vendor number, shown as Vendor Code on the vendor screens. Auto-assigned from the company’s next-vendor-code counter when left blank. |
| vendor_lead_time | integer | Lead time in days. New purchase orders default their due date this many days out. |
| carrierserviceid | integer | Default carrier service (ship method) for this vendor’s purchase orders. |
| carrierservice | string(100) | Code for the referenced carrierservice, instead of the id. |
| noreturns | integer | 1 blocks RMA returns to this vendor. |
| percent_commissionnumber | string(4dp) | Numeric string, 4 decimal places. Not money - do not apply currency rounding. |
| flat_commissionmoney | string(4dp) | Stored as decimal(12,4). |
| parent_vendorid | integer | Parent vendor, when this record is a location or division of a larger vendor. |
| parent_vendor | string(30) | Vendor code of the parent vendor. Send this or parent_vendorid, not both unless they agree. |
| taxgroupid | integer | Tax group applied to this vendor’s purchases. |
| taxgroup | string(20) | Code for the referenced taxgroup, instead of the id. |
| vendorcode | string(30) | Older short vendor code, appended to the display name in parentheses. |
| salutation | string(20) | Salutation for an individual vendor (Mr., Ms., ...). |
| first_name | string(50) | First name, for an individual vendor. |
| middle_name | string(50) | Middle name, for an individual vendor. |
| name_suffix | string(20) | Name suffix for an individual vendor (Jr., III, ...). |
| vendortypeid | integer | Reference to vendortypes, by id. Write either this or vendortype. |
| vendortype | string(100) | Code for the referenced vendortype, instead of the id. |
| default_retainermoney | string(3dp) | Stored as decimal(6,3). |
| currency | string(10) | Currency the vendor bills in. Bills and purchase orders for the vendor default to it. |
| gets1099 | integer | 1 when the vendor receives a 1099 at year end. |
| basevendorid | integer | Reference to vendors, by id. Write either this or basevendor. |
| basevendor | string(30) | Vendor code of the base vendor. Send this or basevendorid, not both unless they agree. |
| buyeruserid | integer | Buyeruserid. Id only. |
| buyeruser | string(50) | Login name of the buyer. Send this or buyeruserid, not both unless they agree. |
| default_checkacctid | integer | Checking account payments to this vendor default to. |
| default_checkacct | string(30) | Name of the default bank account. Send this or default_checkacctid, not both unless they agree. |
| default_paymethod | integer | Default payment method for bills: 1 = cash, 2 = check, 3 = credit card, 4 = ACH/EFT; 0 when none is set. |
| lead | boolean | True when the record is a prospective vendor entered as a lead (Leads feature) rather than an active vendor. |
| orderfrom_email | string(255) | Email address purchase orders are sent to. |
| orderfrom_fax | string(20) | Fax number for sending purchase orders. |
| orderfrom_phone | string(20) | Phone number of the ordering contact. |
| paytoname | string(150) | Pay To name printed on checks, when different from the vendor name. |
| taskstatusid | integer | Reference to taskstatuses, by id. Write either this or taskstatus. |
| taskstatus | string(100) | Task status name. Send this or taskstatusid, not both unless they agree. |
| timezoneid | integer | Reference to timezones, by id. Write either this or timezone. |
| timezone | string(64) | IANA time zone name. Send this or timezoneid, not both unless they agree. |
| insuranceemail | string(50) | Email address of the vendor’s insurance contact, used for certificate-of-insurance tracking. |
| insuranceemailcomment | string(50) | Label describing the insurance email contact. |
| insurancephone | string(20) | Phone number of the vendor’s insurance contact. |
| insurancephonecomment | string(50) | Label describing the insurance phone contact. |
| paytoemail | string(255) | Email address payment remittances are sent to. |
| excludefrompaymentreport | boolean | True leaves the vendor off payment reports. |
| insurancefax | string(20) | Fax number of the vendor’s insurance contact. |
| insurancefaxcomment | string(50) | Label describing the insurance fax contact. |
| addressverifiedread-only | string(32) | Hash of the address as it stood when it last passed the AvaTax/USPS address check; when it no longer matches the current address the address counts as unverified. Maintained by the verification flow, so it cannot be written through the API. |
| displaynameread-only | string(255) | STORED GENERATED in the database. Read-only - MySQL computes it, and a value sent here is silently discarded. |
| displaynamenocoderead-only | string(255) | STORED GENERATED in the database. Read-only - MySQL computes it, and a value sent here is silently discarded. |
| externalid | string(100) | Your own key. Scoped to your company. |
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | A required field was missing. |
curl -X POST \ 'https://acme.nolapro.com/!/api/v2/vendors' \ -H 'Authorization: Bearer $NP_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: your-unique-key' \ -d '{ "name": "Example name", "orderfromname": "Example orderfromname", "paytermsid": 104, "paynone": 1, "defaultglacctid": 104, "defaultglacct": "Example defaultglacct" }'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/vendors'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => json_encode([ 'name' => 'Example name', 'orderfromname' => 'Example orderfromname', 'paytermsid' => 104, 'paynone' => 1, 'defaultglacctid' => 104, 'defaultglacct' => 'Example defaultglacct', ]), ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.post( "https://acme.nolapro.com/!/api/v2/vendors", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, json={ "name": "Example name", "orderfromname": "Example orderfromname", "paytermsid": 104, "paynone": 1, "defaultglacctid": 104, "defaultglacct": "Example defaultglacct", }, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/vendors', { method: 'POST', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, body: JSON.stringify({ name: "Example name", orderfromname: "Example orderfromname", paytermsid: 104, paynone: 1, defaultglacctid: 104, defaultglacct: "Example defaultglacct", }), } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var body = new { name = "Example name", orderfromname = "Example orderfromname", paytermsid = 104, paynone = 1, defaultglacctid = 104, defaultglacct = "Example defaultglacct", }; var req = new HttpRequestMessage(HttpMethod.Post, "https://acme.nolapro.com/!/api/v2/vendors") { Content = JsonContent.Create(body), }; req.Headers.Add("Idempotency-Key", "your-unique-key"); var res = await http.SendAsync(req); res.EnsureSuccessStatusCode();
{
"name": "Example name",
"orderfromname": "Example orderfromname",
"paytermsid": 104,
"paynone": 1,
"defaultglacctid": 104,
"defaultglacct": "Example defaultglacct"
}
Retrieve one record.
Requires scope vendors:read.
| Name | In | Type | Notes |
|---|---|---|---|
| idrequired | path | integer | The record id. |
| include | query | string | Comma-separated extras to embed. Only custom_fields is available: the extra fields this install has defined on the record. Off by default, and an unrecognised value is refused rather than ignored. See Conventions. |
| Status | Code | Meaning |
|---|---|---|
| 404 | not_found | No record with that id. |
curl \ 'https://acme.nolapro.com/!/api/v2/vendors/104' \ -H 'Authorization: Bearer $NP_TOKEN'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/vendors/104'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.get( "https://acme.nolapro.com/!/api/v2/vendors/104", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/vendors/104', { method: 'GET', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var res = await http.GetAsync( "https://acme.nolapro.com/!/api/v2/vendors/104"); res.EnsureSuccessStatusCode();
{
"name": "Example name",
"orderfromname": "Example orderfromname",
"paytermsid": 104,
"paynone": 1,
"defaultglacctid": 104,
"defaultglacct": "Example defaultglacct"
}
Update.
Requires scope vendors:write.
| Name | In | Type | Notes |
|---|---|---|---|
| idrequired | path | integer | The record id. |
| Idempotency-Key | header | string | Makes the write safely retryable. Any unique string per logical operation; a UUID is fine.
The failure this prevents is specific: the request succeeds, the response is lost to a timeout, you retry, and the customer is billed twice. With a key, the retry returns the original response - same status, same body, same id - and creates nothing.
The body is part of the key's identity. Reusing a key with a different body is a bug on your side, not a retry, and answers 409 idempotency_replay rather than silently handing back the old response. Keys are remembered for 24 hours. |
| Field | Type | Description |
|---|---|---|
| name | string(30) | Last name, for an individual vendor. The display name uses companyname when that is set, otherwise the personal name fields. |
| idread-only | integer | NolaPro id. |
| orderfromname | string(30) | Contact name on the Order From address block - where purchase orders go when ordering differs from the payment address. |
| paytermsid | integer | Paytermsid. Id only - the table this points at is not identifiable from the column name, so there is no human key to send instead. |
| paynone | integer | 1 puts the vendor on payment hold: payment runs set to skip held vendors exclude their bills, and bill lists mark the vendor with *. |
| defaultglacctid | integer | Reference to glaccounts, by id. Write either this or defaultglacct. |
| defaultglacct | string(20) | Code for the referenced glaccount, instead of the id. |
| defaultbilldescription | string(50) | Description pre-filled on new bills entered for this vendor. |
| customeraccount | string(20) | Your account number with this vendor, printed on payments. |
| cancel | boolean | Cancelled. Always a boolean on the wire, whatever integer width the column uses (D23). |
| entrydateread-only | string | When the record was created. |
| lastchangedateread-only | string | Last modification. Drives modifiedsince. |
| companyname | string(100) | Company name. When set it is the vendor’s display name; otherwise the salutation/first/middle/name/suffix fields are used. |
| address1 | string(100) | Street address. |
| address2 | string(100) | Second address line. |
| mailstop | string(20) | Mail stop line printed with the payment address. |
| city | string(50) | City of the payment address. |
| state | string(20) | State of the payment address. |
| zip | string(15) | Postal code. |
| country | string(20) | Country of the payment address. |
| phone1 | string(20) | Primary phone. |
| phone1comment | string(20) | Label describing what phone1 reaches (Office, Mobile, ...). |
| phone2 | string(20) | Additional phone number. |
| phone2comment | string(20) | Label describing what phone2 reaches (Office, Mobile, ...). |
| phone3 | string(20) | Additional phone number. |
| phone3comment | string(20) | Label describing what phone3 reaches (Office, Mobile, ...). |
| phone4 | string(20) | Additional phone number. |
| phone4comment | string(20) | Label describing what phone4 reaches (Office, Mobile, ...). |
| email1 | string(255) | Primary email address. |
| email1comment | string(20) | Label describing what email1 is for. |
| email2 | string(255) | Secondary email. |
| email2comment | string(20) | Label describing what email2 is for. |
| website | string(100) | Vendor’s website URL. |
| orderfrom_companyname | string(100) | Company name on the Order From address, when purchase orders go to a different address than payments. |
| orderfrom_address1 | string(100) | Street address line 1 of the Order From address. |
| orderfrom_address2 | string(100) | Street address line 2 of the Order From address. |
| orderfrom_mailstop | string(20) | Mail stop line of the Order From address. |
| orderfrom_city | string(50) | City of the Order From address. |
| orderfrom_state | string(20) | State of the Order From address. |
| orderfrom_zip | string(15) | ZIP/postal code of the Order From address. |
| orderfrom_country | string(20) | Country of the Order From address. |
| imageread-only | string(64) | Filename of the picture uploaded on the vendor screen. Managed by the file upload, so it cannot be written through the API. |
| default_cost_per_hourmoney | string(6dp) | Stored as decimal(12,6). |
| vendor_code | string(50) | Vendor number, shown as Vendor Code on the vendor screens. Auto-assigned from the company’s next-vendor-code counter when left blank. |
| vendor_lead_time | integer | Lead time in days. New purchase orders default their due date this many days out. |
| carrierserviceid | integer | Default carrier service (ship method) for this vendor’s purchase orders. |
| carrierservice | string(100) | Code for the referenced carrierservice, instead of the id. |
| noreturns | integer | 1 blocks RMA returns to this vendor. |
| percent_commissionnumber | string(4dp) | Numeric string, 4 decimal places. Not money - do not apply currency rounding. |
| flat_commissionmoney | string(4dp) | Stored as decimal(12,4). |
| parent_vendorid | integer | Parent vendor, when this record is a location or division of a larger vendor. |
| parent_vendor | string(30) | Vendor code of the parent vendor. Send this or parent_vendorid, not both unless they agree. |
| taxgroupid | integer | Tax group applied to this vendor’s purchases. |
| taxgroup | string(20) | Code for the referenced taxgroup, instead of the id. |
| vendorcode | string(30) | Older short vendor code, appended to the display name in parentheses. |
| salutation | string(20) | Salutation for an individual vendor (Mr., Ms., ...). |
| first_name | string(50) | First name, for an individual vendor. |
| middle_name | string(50) | Middle name, for an individual vendor. |
| name_suffix | string(20) | Name suffix for an individual vendor (Jr., III, ...). |
| vendortypeid | integer | Reference to vendortypes, by id. Write either this or vendortype. |
| vendortype | string(100) | Code for the referenced vendortype, instead of the id. |
| default_retainermoney | string(3dp) | Stored as decimal(6,3). |
| currency | string(10) | Currency the vendor bills in. Bills and purchase orders for the vendor default to it. |
| gets1099 | integer | 1 when the vendor receives a 1099 at year end. |
| basevendorid | integer | Reference to vendors, by id. Write either this or basevendor. |
| basevendor | string(30) | Vendor code of the base vendor. Send this or basevendorid, not both unless they agree. |
| buyeruserid | integer | Buyeruserid. Id only. |
| buyeruser | string(50) | Login name of the buyer. Send this or buyeruserid, not both unless they agree. |
| default_checkacctid | integer | Checking account payments to this vendor default to. |
| default_checkacct | string(30) | Name of the default bank account. Send this or default_checkacctid, not both unless they agree. |
| default_paymethod | integer | Default payment method for bills: 1 = cash, 2 = check, 3 = credit card, 4 = ACH/EFT; 0 when none is set. |
| lead | boolean | True when the record is a prospective vendor entered as a lead (Leads feature) rather than an active vendor. |
| orderfrom_email | string(255) | Email address purchase orders are sent to. |
| orderfrom_fax | string(20) | Fax number for sending purchase orders. |
| orderfrom_phone | string(20) | Phone number of the ordering contact. |
| paytoname | string(150) | Pay To name printed on checks, when different from the vendor name. |
| taskstatusid | integer | Reference to taskstatuses, by id. Write either this or taskstatus. |
| taskstatus | string(100) | Task status name. Send this or taskstatusid, not both unless they agree. |
| timezoneid | integer | Reference to timezones, by id. Write either this or timezone. |
| timezone | string(64) | IANA time zone name. Send this or timezoneid, not both unless they agree. |
| insuranceemail | string(50) | Email address of the vendor’s insurance contact, used for certificate-of-insurance tracking. |
| insuranceemailcomment | string(50) | Label describing the insurance email contact. |
| insurancephone | string(20) | Phone number of the vendor’s insurance contact. |
| insurancephonecomment | string(50) | Label describing the insurance phone contact. |
| paytoemail | string(255) | Email address payment remittances are sent to. |
| excludefrompaymentreport | boolean | True leaves the vendor off payment reports. |
| insurancefax | string(20) | Fax number of the vendor’s insurance contact. |
| insurancefaxcomment | string(50) | Label describing the insurance fax contact. |
| addressverifiedread-only | string(32) | Hash of the address as it stood when it last passed the AvaTax/USPS address check; when it no longer matches the current address the address counts as unverified. Maintained by the verification flow, so it cannot be written through the API. |
| displaynameread-only | string(255) | STORED GENERATED in the database. Read-only - MySQL computes it, and a value sent here is silently discarded. |
| displaynamenocoderead-only | string(255) | STORED GENERATED in the database. Read-only - MySQL computes it, and a value sent here is silently discarded. |
| externalid | string(100) | Your own key. Scoped to your company. |
| Status | Code | Meaning |
|---|---|---|
| 404 | not_found | No record with that id. |
curl -X PATCH \ 'https://acme.nolapro.com/!/api/v2/vendors/104' \ -H 'Authorization: Bearer $NP_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: your-unique-key' \ -d '{ "name": "Example name", "orderfromname": "Example orderfromname", "paytermsid": 104, "paynone": 1, "defaultglacctid": 104, "defaultglacct": "Example defaultglacct" }'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/vendors/104'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'PATCH', CURLOPT_POSTFIELDS => json_encode([ 'name' => 'Example name', 'orderfromname' => 'Example orderfromname', 'paytermsid' => 104, 'paynone' => 1, 'defaultglacctid' => 104, 'defaultglacct' => 'Example defaultglacct', ]), ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.patch( "https://acme.nolapro.com/!/api/v2/vendors/104", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, json={ "name": "Example name", "orderfromname": "Example orderfromname", "paytermsid": 104, "paynone": 1, "defaultglacctid": 104, "defaultglacct": "Example defaultglacct", }, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/vendors/104', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, body: JSON.stringify({ name: "Example name", orderfromname: "Example orderfromname", paytermsid: 104, paynone: 1, defaultglacctid: 104, defaultglacct: "Example defaultglacct", }), } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var body = new { name = "Example name", orderfromname = "Example orderfromname", paytermsid = 104, paynone = 1, defaultglacctid = 104, defaultglacct = "Example defaultglacct", }; var req = new HttpRequestMessage(HttpMethod.Patch, "https://acme.nolapro.com/!/api/v2/vendors/104") { Content = JsonContent.Create(body), }; req.Headers.Add("Idempotency-Key", "your-unique-key"); var res = await http.SendAsync(req); res.EnsureSuccessStatusCode();
{
"name": "Example name",
"orderfromname": "Example orderfromname",
"paytermsid": 104,
"paynone": 1,
"defaultglacctid": 104,
"defaultglacct": "Example defaultglacct"
}
Cancel.
Requires scope vendors:cancel.
| Name | In | Type | Notes |
|---|---|---|---|
| idrequired | path | integer | The record id. |
| Idempotency-Key | header | string | Makes the write safely retryable. Any unique string per logical operation; a UUID is fine.
The failure this prevents is specific: the request succeeds, the response is lost to a timeout, you retry, and the customer is billed twice. With a key, the retry returns the original response - same status, same body, same id - and creates nothing.
The body is part of the key's identity. Reusing a key with a different body is a bug on your side, not a retry, and answers 409 idempotency_replay rather than silently handing back the old response. Keys are remembered for 24 hours. |
| Status | Code | Meaning |
|---|---|---|
| 404 | not_found | No record with that id. |
curl -X DELETE \ 'https://acme.nolapro.com/!/api/v2/vendors/104' \ -H 'Authorization: Bearer $NP_TOKEN'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/vendors/104'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'DELETE', ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.delete( "https://acme.nolapro.com/!/api/v2/vendors/104", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/vendors/104', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var req = new HttpRequestMessage(HttpMethod.Delete, "https://acme.nolapro.com/!/api/v2/vendors/104"); var res = await http.SendAsync(req); res.EnsureSuccessStatusCode();
{
"name": "Example name",
"orderfromname": "Example orderfromname",
"paytermsid": 104,
"paynone": 1,
"defaultglacctid": 104,
"defaultglacct": "Example defaultglacct"
}
1099 form as a PDF
The 1099-MISC for the vendor. Defaults to last tax year.
Answers application/pdf, not JSON. Because the body is binary it cannot be carried inside a /batch results array; asking for it there returns 415 not_batchable.
Requires scope vendors:read.
| Name | In | Type | Notes |
|---|---|---|---|
| idrequired | path | integer | The record id. |
| taxyear | query | string | Four-digit tax year. Defaults to last year. |
| formtype | query | string | Form variant, e.g. MISC. |
curl \ 'https://acme.nolapro.com/!/api/v2/vendors/104/form1099' \ -H 'Authorization: Bearer $NP_TOKEN'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/vendors/104/form1099'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.get( "https://acme.nolapro.com/!/api/v2/vendors/104/form1099", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/vendors/104/form1099', { method: 'GET', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var res = await http.GetAsync( "https://acme.nolapro.com/!/api/v2/vendors/104/form1099"); res.EnsureSuccessStatusCode();
List files attached to a vendor.
The attachments on this vendor, newest first. Accepted filedefinitionid values: 6, 45 (default 6). Metadata only - each file's bytes are at GET /attachments/{id}/content.
Requires scope vendors:read.
| Name | In | Type | Notes |
|---|---|---|---|
| idrequired | path | integer | The vendor id. |
| filedefinitionid | query | integer | Only files in this list. Accepted filedefinitionid values: 6, 45 (default 6). |
| filecategoryid | query | integer | Only files filed under this category. |
| filename | query | string | Partial match on the file name, case insensitive. |
| Status | Code | Meaning |
|---|---|---|
| 404 | not_found | No vendor with that id in this company. |
curl \ 'https://acme.nolapro.com/!/api/v2/vendors/104/attachments' \ -H 'Authorization: Bearer $NP_TOKEN'
$ch = curl_init('https://acme.nolapro.com/!/api/v2/vendors/104/attachments'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN')], CURLOPT_RETURNTRANSFER => true, ]); $res = json_decode(curl_exec($ch), true);
import os, requests r = requests.get( "https://acme.nolapro.com/!/api/v2/vendors/104/attachments", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}"}, ) r.raise_for_status()
const res = await fetch( 'https://acme.nolapro.com/!/api/v2/vendors/104/attachments', { method: 'GET', headers: { Authorization: `Bearer ${process.env.NP_TOKEN}` }, } ); const data = await res.json();
using System.Net.Http.Json; var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); var res = await http.GetAsync( "https://acme.nolapro.com/!/api/v2/vendors/104/attachments"); res.EnsureSuccessStatusCode();
Attach a file to a vendor.
multipart/form-data with one file part; see the AttachmentUpload schema for the other parts. Accepted filedefinitionid values: 6, 45 (default 6). Answers 201 with the attachment's metadata and Location: /attachments/{id}. Check _meta.warnings for datatype_truncated and stored_under_parent_company.
Requires scope vendors:write.
| Name | In | Type | Notes |
|---|---|---|---|
| idrequired | path | integer | The vendor id. |
| Idempotency-Key | header | string | Makes the write safely retryable. Any unique string per logical operation; a UUID is fine.
The failure this prevents is specific: the request succeeds, the response is lost to a timeout, you retry, and the customer is billed twice. With a key, the retry returns the original response - same status, same body, same id - and creates nothing.
The body is part of the key's identity. Reusing a key with a different body is a bug on your side, not a retry, and answers 409 idempotency_replay rather than silently handing back the old response. Keys are remembered for 24 hours. |
| Field | Type | Description |
|---|---|---|
| filerequired | string | The file. Exactly one part named file; a second one, or file[], is 400 invalid_request so an idempotent retry can never half-succeed. Empty is refused. Over the cap (the smaller of APIV2_MAX_UPLOAD_BYTES, 64 MB by default, and PHP's upload_max_filesize / post_max_size) is 413 payload_too_large naming the limit that applied. |
| filename | string(255) | Overrides the part's file name. |
| notes | text | Free text shown beside the file. |
| filedefinitionid | integer | Only when the parent accepts more than one list. Anything the parent does not accept is 422 unknown_value naming the accepted ids. |
| filecategoryid | integer | Category by id. |
| filecategory | string(255) | Category by name. Sent with filecategoryid and disagreeing is 422 conflicting_reference. |
| Status | Code | Meaning |
|---|---|---|
| 400 | unknown_parameter | A form field that is not on the AttachmentUpload schema. |
| 400 | invalid_type | filedefinitionid or filecategoryid that is not an integer. |
| 404 | not_found | No vendor with that id in this company. |
| 409 | upload_limit_reached | This file list allows a fixed number of files on a vendor and it is full. Remove one first. |
| 413 | payload_too_large | The file is over the cap. The body names the limit that applied. |
| 415 | multipart_required | The body was not multipart/form-data. |
| 422 | unknown_value | filedefinitionid is not one this vendor accepts, or the category does not exist in this company. |
curl -X POST \ 'https://acme.nolapro.com/!/api/v2/vendors/104/attachments' \ -H 'Authorization: Bearer $NP_TOKEN' \ -H 'Idempotency-Key: your-unique-key' \ -F 'file=@grant-letter-signed.pdf' \ -F 'filename=grant-letter-signed.pdf' \ -F 'notes=Signed copy received 21 Sep' \ -F 'filedefinitionid=8' \ -F 'filecategory=Receipts'
$fields = [ 'filename' => 'grant-letter-signed.pdf', 'notes' => 'Signed copy received 21 Sep', 'filedefinitionid' => '8', 'filecategory' => 'Receipts', ]; $fields['file'] = new CURLFile('grant-letter-signed.pdf'); $ch = curl_init('https://acme.nolapro.com/!/api/v2/vendors/104/attachments'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NP_TOKEN'), 'Idempotency-Key: your-unique-key'], CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => $fields, ]); $res = json_decode(curl_exec($ch), true);
import os, requests with open("grant-letter-signed.pdf", "rb") as fh: r = requests.post( "https://acme.nolapro.com/!/api/v2/vendors/104/attachments", headers={"Authorization": f"Bearer {os.environ['NP_TOKEN']}", "Idempotency-Key": "your-unique-key"}, files={"file": fh}, data={ "filename": "grant-letter-signed.pdf", "notes": "Signed copy received 21 Sep", "filedefinitionid": "8", "filecategory": "Receipts", }, ) r.raise_for_status()
import { openAsBlob } from 'node:fs';
const form = new FormData();
form.append('file', await openAsBlob('grant-letter-signed.pdf'), 'grant-letter-signed.pdf');
form.append('filename', "grant-letter-signed.pdf");
form.append('notes', "Signed copy received 21 Sep");
form.append('filedefinitionid', "8");
form.append('filecategory', "Receipts");
const res = await fetch(
'https://acme.nolapro.com/!/api/v2/vendors/104/attachments',
{
method: 'POST',
headers: { Authorization: `Bearer ${process.env.NP_TOKEN}`, 'Idempotency-Key': 'your-unique-key' },
body: form,
}
);
const data = await res.json();
var token = Environment.GetEnvironmentVariable("NP_TOKEN"); using var http = new HttpClient(); http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); using var form = new MultipartFormDataContent(); form.Add(new StreamContent(File.OpenRead("grant-letter-signed.pdf")), "file", "grant-letter-signed.pdf"); form.Add(new StringContent("grant-letter-signed.pdf"), "filename"); form.Add(new StringContent("Signed copy received 21 Sep"), "notes"); form.Add(new StringContent("8"), "filedefinitionid"); form.Add(new StringContent("Receipts"), "filecategory"); var req = new HttpRequestMessage(HttpMethod.Post, "https://acme.nolapro.com/!/api/v2/vendors/104/attachments") { Content = form }; req.Headers.Add("Idempotency-Key", "your-unique-key"); var res = await http.SendAsync(req); res.EnsureSuccessStatusCode();