fbpx

Suppliers

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

NameTypeDescription
CodeStringUnique code used to represent a supplier
NameStringSupplier name
ContactsObjectThis object contains an array of customers contact information like
name, title, firstname, lastname,Telephone, FAX, Mobile, Website
AddressObjectThis object contains the suppliers’ address details
ApplyWithholdingTaxBooleanWHT(Withholdong Tax commonly renamed to CIS. If this is true then a deduction needs to be applied to receipts for this supplier
BankAccountObjectBank account details
CreatedDateDateThe date the supplier was created (e.g. [JSONDATE])
CurrencyObjectThe default currency used when creating a receipt
DefaultNominalCodeNumericThe default outgoing type to be used when creating a receipt
DefaultPdfThemeNumericThe default PDF theme to be used when emailing
IsRegisteredInECBooleanShould be set to “True” is supplier is registered in another EC member state
LastUpdatedDateDateThe last date the supplier was updated (e.g. [JSONDATE])
NoteStringNotes
OutstandingBalanceNumericAmount outstanding for unpaid receipts
PaymentMethodNumericThe default payment method id to used when recording a payment for a supplier
TotalPaidAmountNumericTotal amount paid
TotalDueAmountNumericTotal due amount
BilledNetAmountNumericTotal net amount of receipts
BilledVatAmountNumericTotal VAT amount of receipts
IsArchivedBooleanFlag indicating whether user is archived or not.
FirstPurchaseDateDateThe date of the first purchase for this supplier. For e.g. [JSONDATE]
LastPurchaseDateDateThe date of the last purchase for this supplier. For e.g. [JSONDATE]
VatNumberStringVAT number
WithholdingTaxRateNumericWithholding Tax rate
WithholdingTaxReferencesObjectReferences to be used when Withholding Tax (Name-Value pair object)
CreateSupplierCodeIfDuplicateBooleanIf this flag is true, create a new supplier when supplier code is duplicate
CreateSupplierNameIfEmptyOrNullBooleanIf this flag is true, create a new supplier when supplier name is null or empty
BankAccount
NameStringBank name
NumberStringAccount number
SortCodeStringAccount sort code
PaymentTerms
DaysNumericIndicates payment terms in number of days. Receipt due date calculation is done based on this value.
TypeString[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

NameDescription
pageIs the page number to be retrieved and the default value is 1.
perpageThe number of records to be returned and the default value is 10. Maximum allowed records per page is 250.
sortbyFilter by column allowed values are as
1. Name
2. Code
3. TotalPaidAmount
4. OutstandingBalance
orderThe sort direction and the default value is ‘Asc’ for ascending. Results can also be sorted in ‘Desc’ – descending order.
namestartswithAll 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.
filterarchivedFlag 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": "test@dontmail.com",
            "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": "test@dontmail.com",
            "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": "example@example.com",
        "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": "example@example.co.uk",
		"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": "example@example.co.uk",
		"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}

See how KashFlow works with your business and your books