The Suppliers resource allows Suppliers to be listed, viewed, created, and updated. Here are some example URIs:
· /Suppliers/E6E8163F-6911-40e9-B740-90E5A0A3A996 - returns details of a particular Supplier;
· /Suppliers?page=2 - returns the second page of 100 Suppliers;
· /Suppliers - returns the first 100 active Suppliers because page number 1 is the default;
· /Suppliers?page=2&limit=500 - returns the second page of 500 Suppliers; ie. the 501st to 1000th Suppliers;
· /Suppliers?includeDeprecated=1 - returns the first page of 100 Suppliers including deprecated Suppliers;
· /Suppliers?name=ABC - returns the first page of 100 Suppliers with name starting with ABC;
The full range of URIs and HTTP Verbs supported are:
Operation |
HTTP Action |
List of paginated Suppliers |
GET /Suppliers?page={pageNumber} |
View any Supplier |
GET /Suppliers/{id} |
Create a set of Suppliers |
POST /Suppliers |
Update a set of Suppliers |
PUT /Suppliers |
These filters can be used with the GET Suppliers endpoint:
Filter |
Description |
limit |
Specifies the page size for pagination. Default page size is 100 Suppliers. |
name |
Only return Suppliers that start with the specific Supplier name |
modifiedSince |
Only return Suppliers modified since a specified date (UTC time) |
includeDeprecated |
Returns all Suppliers, including deprecated, if set to true. If set to false or if it is not specified then returns only active (ie. non-deprecated) Suppliers |
Filters are used by adding the filter and value to the URI: /Suppliers?name=ABC&includeDeprecated=true
Using bulk create/update:
With POST and PUT actions you create/update a set of Suppliers:
{
Suppliers: [{...}, {...},...]
}
Up to 100 Suppliers can be created/updated in one batch.
As a result of the call to batch actions you will get the following response:
{
"Suppliers": [
{
...,
"OperationStatus":"failed",
"Errors": [
{"ErrorText":"Supplier with specified id does not exist"},
{"ErrorText":"Supplier name cannot be longer than 256 characters"}
]
},
{
...,
"OperationStatus":"succeeded",
"Errors": []
},
]
}
Where “errors” property for every Supplier in a batch indicates problems with executing create/update action on the Supplier. If “errors” array property has no items then operation completed successfully. You can also check “operationStatus” property to find out if specific action in a batch succeeded or failed.
Available Fields for Supplier:
Property |
Type |
Length |
Required |
Notes |
Addresses |
Address collection, see below | |||
Contacts |
Contact collection, see below | |||
Errors |
Errors collection, see below | |||
ID |
Guid |
Ignored by POST action. Required for PUT action | ||
OperationStatus |
String |
Read-only field. Empty in Get action result and one of two possible values as a result of POST, PUT and DELETE actions: “failed” or “succeeded” | ||
Name |
String |
256 |
Yes |
Must be unique |
Currency |
String |
3 |
Yes |
ISO code |
PaymentTerm |
String |
50 |
Yes |
Valid payment term name (payment term with this name must exist in Payment Terms reference book and should be active) |
TaxRule |
String |
50 |
Yes |
Valid taxation rule name (taxation rule with this name must exist in Taxation Rules reference book and should have For Purchases flag set to “true” in API) |
Discount |
Nullable Decimal |
Discount percentage, applied for all purchases by this supplier by default. Range from 0 to 100 | ||
Comments |
String |
256 |
Multiline comment field. Automatically copied to Notes field in sale task when the Supplier is selected. | |
AccountPayable |
String |
50 |
Yes |
Account code of active account from chart of accounts with Account Payable=true |
TaxNumber |
String |
256 |
Taxation number of the Supplier used to report to tax authorities | |
AdditionalAttribute1 |
String |
256 |
Value of the Supplier’s additional attribute 1. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided. | |
AdditionalAttribute2 |
String |
256 |
Value of the Supplier’s additional attribute 2. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided. | |
AdditionalAttribute3 |
String |
256 |
Value of the Supplier’s additional attribute 3. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided. | |
AdditionalAttribute4 |
String |
256 |
Value of the Supplier’s additional attribute 4. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided. | |
AdditionalAttribute5 |
String |
256 |
Value of the Supplier’s additional attribute 5. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided. | |
AdditionalAttribute6 |
String |
256 |
Value of the Supplier’s additional attribute 6. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided. | |
AdditionalAttribute7 |
String |
256 |
Value of the Supplier’s additional attribute 7. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided. | |
AdditionalAttribute8 |
String |
256 |
Value of the Supplier’s additional attribute 8. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided. | |
AdditionalAttribute9 |
String |
256 |
Value of the Supplier’s additional attribute 9. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided. | |
AdditionalAttribute10 |
String |
256 |
Value of the Supplier’s additional attribute 10. Ignored when current DEAR Subscription plan is Small or Medium or when AttributeSet name is not provided. | |
AttributeSet |
String |
50 |
Name of the Supplier’s additional attribute set. Ignored when current DEAR Subscription plan is Small or Medium. (AttributeSet with this name must exist in Additional Attribute Sets reference book) | |
Status |
String |
Yes |
The only valid values are “Active” and “Deprecated” | |
LastModifiedOn |
Nullable DateTime |
Addresses:
Property |
Type |
Length |
Required |
Notes |
Line1 |
String |
256 |
Yes |
|
Line2 |
String |
256 |
||
Type |
String |
8 |
Yes |
Billing, Shipping or Business |
DefaultForType |
Boolean |
Yes |
“true” if specified address should be used as default for its Type (Shipping). Default addresses are selected by default when Supplier is selected in sale task. | |
City |
String |
256 |
||
State |
String |
256 |
||
Postcode |
String |
20 |
||
Country |
String |
32 |
Name of the country |
Contacts:
Property |
Type |
Length |
Required |
Notes |
Name |
String |
256 |
Yes |
Contact person’s name |
Phone |
String |
50 |
||
MobilePhone |
String |
50 |
|
|
JobTitle |
String |
256 |
|
|
Fax |
String |
50 |
||
|
String |
256 |
||
Website |
String |
256 |
||
Default |
Boolean |
Yes |
True if this contact is the Supplier’s default contact. Will be selected automatically when the Supplier is selected in sale task. | |
Comment |
String |
256 |
Multiline comment field. Copied to Notes area in sale task when this Supplier is selected. |
Errors:
Property |
Type |
Length |
Required |
Notes |
ErrorText |
String |
Read-only field indicating problem when executing action on associated entity |