This s a documentation page for our shiny new REST API - you weren't meant to find it. This API isn't ready for public use yet. We're chopping and changing it a LOT as we grow it. So if you build something that uses it then it's very likely to break in a future update. Don't say you weren't warned!
URL: | https://api.kashflow.com/v2/suppliers |
Method(s): | get, post, put, delete |
Response Formats: | JSON or XML |
Description: | This method allows you to retrieve list of a supplier and retrieve, create, update and delete a single supplier. |
Parameters
| Name | Type | Description |
|---|---|---|
| Code | String | Unique code used to represent a supplier |
| Name | String | Supplier name |
| Contacts | Object | This object contains an array of customers contact information like name, title, firstname, lastname,Telephone, FAX, Mobile, Website |
| Address | Object | This object contains the suppliers’ address details |
| ApplyWithholdingTax | Boolean | WHT(Withholdong Tax commonly renamed to CIS. If this is true then a deduction needs to be applied to receipts for this supplier |
| BankAccount | Object | Bank account details |
| CreatedDate | Date | The date the supplier was created (e.g. [JSONDATE]) |
| Currency | Object | The default currency used when creating a receipt |
| DefaultNominalCode | Numeric | The default outgoing type to be used when creating a receipt |
| DefaultPdfTheme | Numeric | The default PDF theme to be used when emailing |
| IsRegisteredInEC | Boolean | Should be set to “True” is supplier is registered in another EC member state |
| LastUpdatedDate | Date | The last date the supplier was updated (e.g. [JSONDATE]) |
| Note | String | Notes |
| OutstandingBalance | Numeric | Amount outstanding for unpaid receipts |
| PaymentMethod | Numeric | The default payment method id to used when recording a payment for a supplier |
| TotalPaidAmount | Numeric | Total amount paid |
| TotalDueAmount | Numeric | Total due amount |
| BilledNetAmount | Numeric | Total net amount of receipts |
| BilledVatAmount | Numeric | Total VAT amount of receipts |
| IsArchived | Boolean | Flag indicating whether user is archived or not. |
| FirstPurchaseDate | Date | The date of the first purchase for this supplier. For e.g. [JSONDATE] |
| LastPurchaseDate | Date | The date of the last purchase for this supplier. For e.g. [JSONDATE] |
| VatNumber | String | VAT number |
| WithholdingTaxRate | Numeric | Withholding Tax rate |
| WithholdingTaxReferences | Object | References to be used when Withholding Tax (Name-Value pair object) |
| CreateSupplierCodeIfDuplicate | Boolean | If this flag is true, create a new supplier when supplier code is duplicate |
| CreateSupplierNameIfEmptyOrNull | Boolean | If this flag is true, create a new supplier when supplier name is null or empty |
| BankAccount | ||
| Name | String | Bank name |
| Number | String | Account number |
| SortCode | String | Account sort code |
| PaymentTerms | ||
| Days | Numeric | Indicates payment terms in number of days. Receipt due date calculation is done based on this value. |
| Type | String | [AfterIssuedDate | AfterMonthEnd] If value is AfterIssuedDate then number of days set above will be added to the receipt date in order to calculate the default due date. If value is AfterMonthEnd then the days set above will be added to the end of the month in which the receipt is dated. |
GET Operation
Returns a list of all suppliers.To get paginated suppliers list –
URL : /suppliers?page={page}&perpage={perpage}&sortby={sortby}&order={order}&namestartswith={namestartswith}&filterarchived={filterarchived}
Request Parameters
| Name | Description |
|---|---|
| page | Is the page number to be retrieved and the default value is 1. |
| perpage | The number of records to be returned and the default value is 10. Maximum allowed records per page is 250. |
| sortby | Filter by column allowed values are as 1. Name 2. Code 3. TotalPaidAmount 4. OutstandingBalance |
| order | The sort direction and the default value is ‘Asc’ for ascending. Results can also be sorted in ‘Desc’ – descending order. |
| namestartswith | All suppliers with name starting from the specified value will be returned. Specify ‘non-alpha’ in order to retrieve all suppliers with name starting with numeric, special or foreign characters. |
| filterarchived | Flag to indicate whether to include archived suppliers on list or not. True indicates archived suppliers should be shown on list. Default value is False. |
| When all the above parameters are excluded from the url, the first 10 suppliers sorted by supplier name in ascending order are returned. | |
Example response for page wise retrieval of suppliers
{
"Data": [{
"Address": {
"Line1": null,
"Line2": null,
"Line3": null,
"Line4": null,
"PostCode": null
},
"ApplyWithholdingTax": false,
"BankAccount": {
"Name": null,
"Number": null,
"SortCode": null
},
"BilledNetAmount": 0,
"BilledVatAmount": 0,
"Code": "ABCDEF123",
"Contacts": [{
"Email": "[email protected]",
"Fax": null,
"Firstname": null,
"LastName": null,
"Mobile": null,
"Name": null,
"Telephone": null,
"Title": null,
"Website": ""
}],
"CreatedDate": null,
"Currency": {
"Code": null,
"DisplaySymbolOnRight": false,
"ExchangeRate": 0,
"Name": null,
"Symbol": null
},
"DefaultPdfTheme": 0,
"DefaultNominalCode": 0,
"FirstPurchaseDate": null,
"Id": 2467872,
"IsArchived": false,
"IsRegisteredInEC": false,
"LastPurchaseDate": null,
"LastUpdatedDate": null,
"Name": "3423423",
"Note": null,
"OutstandingBalance": 0.0000,
"PaymentMethod": 0,
"PaymentTerms": null,
"TotalPaidAmount": 0.0000,
"UniqueEntityNumber": null,
"VatNumber": null,
"WithholdingTaxRate": 0,
"WithholdingTaxReferences": null
}, {
"Address": {
"Line1": null,
"Line2": null,
"Line3": null,
"Line4": null,
"PostCode": null
},
"ApplyWithholdingTax": false,
"BankAccount": {
"Name": null,
"Number": null,
"SortCode": null
},
"BilledNetAmount": 0,
"BilledVatAmount": 0,
"Code": "342301",
"Contacts": [{
"Email": "[email protected]",
"Fax": null,
"Firstname": null,
"LastName": null,
"Mobile": null,
"Name": null,
"Telephone": null,
"Title": null,
"Website": ""
}],
"CreatedDate": null,
"Currency": {
"Code": null,
"DisplaySymbolOnRight": false,
"ExchangeRate": 0,
"Name": null,
"Symbol": null
},
"CreateSupplierCodeIfDuplicate" : false,
"CreateSupplierNameIfEmptyOrNull" : false,
"DefaultPdfTheme": 0,
"DefaultNominalCode": 0,
"FirstPurchaseDate": null,
"Id": 2467935,
"IsArchived": false,
"IsRegisteredInEC": false,
"LastPurchaseDate": null,
"LastUpdatedDate": null,
"Name": "3423423",
"Note": null,
"OutstandingBalance": 0.0000,
"PaymentMethod": 0,
"PaymentTerms": null,
"TotalPaidAmount": 0.0000,
"UniqueEntityNumber": null,
"VatNumber": null,
"WithholdingTaxRate": 0,
"WithholdingTaxReferences": null
}],
"MetaData": {
"FirstPageUrl": "\/v2\/suppliers?page=1&perpage=2&sortby=Name&order=Asc&filterbystartcharacter=&filterarchived=False",
"LastPageUrl": "\/v2\/suppliers?page=27&perpage=2&sortby=Name&order=Asc&filterbystartcharacter=&filterarchived=False",
"NextPageUrl": "\/v2\/suppliers?page=2&perpage=2&sortby=Name&order=Asc&filterbystartcharacter=&filterarchived=False",
"PreviousPageUrl": null,
"TotalRecords": 53
}
}
To get details of a particular supplier with all details –
URL : /suppliers/{code}
Example response for GET of suppliers
{
"Address": {
"Line1": "Line1",
"Line2": "Line2",
"Line3": "Line3",
"Line4": "Line4",
"PostCode": "ABCDEF"
},
"ApplyWithholdingTax": false,
"BankAccount": {
"Name": "Current Account",
"Number": "1234",
"SortCode": "VF324"
},
"BilledNetAmount": 15.0000,
"BilledVatAmount": 2.2500,
"Code": "424201",
"Contacts": [{
"Email": "[email protected]",
"Fax": "12345677",
"Firstname": "Adam",
"LastName": "Taylor",
"Mobile": "123456789",
"Name": "A G Taylor",
"Telephone": "123456789",
"Title": "Mr.",
"Website": "example.com"
}],
"CreatedDate": "2013-10-17 12:00:00",
"Currency": {
"Code": "EUR",
"DisplaySymbolOnRight": false,
"ExchangeRate": 1.0000,
"Name": "Euros",
"Symbol": "€"
},
"DefaultPdfTheme": 0,
"DefaultNominalCode": 5000,
"FirstPurchaseDate": "2013-11-11 12:00:00",
"Id": 2467871,
"IsArchived": false,
"IsRegisteredInEC": false,
"LastPurchaseDate": "2013-11-11 12:00:00",
"LastUpdatedDate": "2013-10-17 12:00:00",
"Name": "Supplier Adam",
"Note": "",
"OutstandingBalance": 17.2500,
"PaymentMethod": 0,
"PaymentTerms": {
"Days": 30,
"Type": "AfterIssuedDate"
},
"CreateSupplierCodeIfDuplicate" : false,
"CreateSupplierNameIfEmptyOrNull" : false,
"TotalPaidAmount": 0.0000,
"UniqueEntityNumber": "",
"VatNumber": "",
"WithholdingTaxRate": -1.0000,
"WithholdingTaxReferences": null
}
POST Operation
Creates a new supplier with the specified data –URL : /suppliers
Features:
1. A supplier can be created with just a supplier name and the code is auto generated if left blank.
2. The auto generated code is constructed by appending the next available number (with a “0” at the left) to the first 4 characters of the supplier name.
3. The supplier name should be at least 2 characters in length.
4. Supplier code can be passed in the request body. The code must be unique w.r.t. the user and must not contain spaces in between.
Example request for POST of supplier
{
"Address": {
"Line1": "Unit 3",
"Line2": "Hillside Business Park",
"Line3": "",
"Line4": "",
"PostCode": "S13 3AS"
},
"ApplyWithholdingTax": false,
"BankAccount": {
"Name": "Bank of Scotland",
"Number": "11673489",
"SortCode": "45-10-90"
},
"Contacts": [{
"Email": "[email protected]",
"Fax": "0208 12345678",
"Firstname": "Joe",
"LastName": "Bloggs",
"Mobile": "0123456789",
"Name": "Mr Joe Bloggs",
"Telephone": "0208 12345678",
"Title": "Mr",
"Website": "www.example.co.uk"
}],
"CreatedDate": "2013-11-01 12:00:00",
"Currency": {
"Code": "GBP",
"DisplaySymbolOnRight": false,
"ExchangeRate": 1,
"Name": "British Pound",
"Symbol": "£"
},
"DefaultOutgoingType": 0,
"DefaultPdfTheme": 0,
"InvoicedNetAmount": 32230.00,
"InvoicedVatAmount": 46.00,
"IsArchived": false,
"IsRegisteredInEC": false,
"LastUpdatedDate": "2013-11-01 12:00:00",
"Name": "DHL",
"Note": null,
"OutstandingBalance": -11284.91,
"PaymentMethod": 0,
"PaymentTerms": {
"Days": 28,
"Type": "AfterIssuedDate"
},
"CreateSupplierCodeIfDuplicate" : false,
"CreateSupplierNameIfEmptyOrNull" : false,
"TotalPaidAmount": 21923.55,
"UniqueEntityNumber": null,
"VatNumber": null,
"WithholdingTaxRate": 0,
"WithholdingTaxReferences": null
}
PUT Operation
Updates an existing supplier with the specified data –URL : /suppliers/{code}
Features:
1. To update supplier details you need to send the whole supplier object (similar to the get supplier response) and only update the required elements .
2. The code can be changed by passing the desired code in the ‘Code’ field of the request body. The desired code should be unique w.r.t. to the user.
Example request for PUT of supplier
{
"Address": {
"Line1": "Unit 3",
"Line2": "Hillside Business Park",
"Line3": "",
"Line4": "",
"PostCode": "S13 3AS"
},
"ApplyWithholdingTax": false,
"BankAccount": {
"Name": "Bank of Scotland",
"Number": "11673489",
"SortCode": "45-10-90"
},
"Code": "DHL01",
"Contacts": [{
"Email": "[email protected]",
"Fax": "0208 123456783",
"Firstname": "Joe",
"LastName": "Bloggs",
"Mobile": "0123456789",
"Name": "Mr Joe Bloggs",
"Telephone": "0208 12345678",
"Title": "Mr",
"Website": "www.example.co.uk"
}],
"CreatedDate": "2013-11-01 12:00:00",
"Currency": {
"Code": "GBP",
"DisplaySymbolOnRight": false,
"ExchangeRate": 1,
"Name": "British Pound",
"Symbol": "£"
},
"DefaultOutgoingType": 0,
"DefaultPdfTheme": 0,
"InvoicedNetAmount": 32230.00,
"InvoicedVatAmount": 46.00,
"IsArchived": false,
"IsRegisteredInEC": false,
"LastUpdatedDate": "2013-11-01 12:00:00",
"Name": "DHL",
"Note": null,
"OutstandingBalance": -11284.91,
"PaymentMethod": 0,
"PaymentTerms": {
"Days": 28,
"Type": "AfterIssuedDate"
},
"TotalPaidAmount": 21923.55,
"UniqueEntityNumber": null,
"VatNumber": null,
"WithholdingTaxRate": 0,
"WithholdingTaxReferences": null,
"CreateSupplierCodeIfDuplicate" : false,
"CreateSupplierNameIfEmptyOrNull" : false
}
Delete Operation
Deletes the supplier with the code provided in the URL –URL : /suppliers/{code}