Settings

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/settings

Method(s):

get

Response Formats:

JSON, XML

Description:

This method allows you to retrieve all the settings of the user.

Response elements

NameTypeDescription
List of associated accounts. Each associated account has the following parameters
CompanyNameStringCompany name of the user
UsernameStringName of the user
Display settings parameters
DisplayDensityStringDisplay setting for the user’s account. The 3 acceptable options are 1. Comfortable, 2. Cozy and 3. Compact
PrimaryColorsCollectionArray of the shades of the primary color. The primary color is the most prominent color used in the application. The shades are represented by hexadecimal color code strings. For example, [ “#5FBF46”, “#AFDFA2”, “#D7EFD0”, “#FBFDF9” ]
SecondaryColorsCollectionArray of the shades of the secondary color. The secondary color is generally used for highlighting. The shades are represented by hexadecimal color code strings. For example, [ “#F76B97”, “#C0B5FB”, “#DFDAFD”, “#EEECFE” ]
CustomColorsEnabledBooleanWhether custom coloring is enabled or not for the user’s account
Quote settings parameters
QuoteTextStringThe name used to represent quote in the entire application
ReferenceStringTitle of the reference column
IncludeTotalInListBooleanFlag to indicate if total is to be displayed in the list of quotes
DefaultEmailTemplateNumberNumericUnique number of the default email template used for emailing quotes.
For further details about email templates, click here
InvoiceConversionSettingsObjectSettings for conversion of quote into an invoice
InvoiceConversionSettings fields
DeleteBooleanFlag to indicate if quote should be deleted after it is converted to invoice
CopyReferenceAsCommentBooleanFlag to indicate if quote reference is to be converted to a line item in the converted invoice and also copied to customer reference field of invoice
CopyReferenceAsPurchaseOrderBooleanFlag to indicate if quote reference is to be copied to customer reference field of invoice
ChangeCategoryBooleanFlag to indicate if category of the quote is to be changed (re-assigned) after it is converted to invoice
ReassignCategoryToNumericThe unique number of the category to which the quote is to be changed (re-assigned) after it is converted to invoice
Project settings parameters
IsEnabledBooleanWhether projects are enabled or not for the user
ProjectTextStringThe name used to represent project in the entire application
ProjectOnInvoiceLineBooleanWhether project on invoice line items are enabled or not for the user
ProjectOnPurchaseLineBooleanWhether project on purchase line items are enabled or not for the user
ProjectOnBankLineBooleanWhether project on bank transaction line items are enabled or not for the user
Journal settings parameters
IsEnabledBooleanWhether journal is enabled for the user or not
Company settings parameters
CompanyNameStringCompany name of the user
SubscriptionTypeStringWhether the subscription for the account is ‘Paid’ or ‘FreeTrial’
PayMonthlyBooleanWhether the subscription payment for the account is done monthly
DaysLeftForSubscriptionToExpireNumericNumber of days left for the account subscription to expire
SiteNameStringThe application name of the account. In case of partner-associated accounts, this can be customized by the user. For all other accounts, the value for this field is ‘KashFlow’
HomeCurrencyObjectInformation related to Home Currency
DateFormatStringReturns either US format (MM/DD/YYYY) or UK format (DD/MM/YYYY). This date format applies to entire application.
VATRegisteredBooleanWhether user is VAT registered
TotangoAccountStatusStringUser’s totango account status. Possible values are Free, Paying, Lapsed, Expired
TotangoCreatedDateStringTotango creation date. For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
ApplicationString“RSR” if user is using new rsr app else “Classic”
PartnerIdNumericPartner Id
ApiEnabledBooleanWhether SOAP API is enabled for user or not.
AddressObjectAddress object which has 4 address lines and postal code
TelephoneStringTelephone number
OnboarderNameStringOnboarder Name
PartnerBrandingOptOutBooleanWether to exclude partners branding.
LeadCalledStringPossible values are Yes, No, Uncontactable
WithholdingTaxSettingsObjectAll Withholding tax related settings. Described in details below.
StockSettingsObjectStock management settings for user. “Enabled” field indicate whether stock management is enabled for user or not.
LastPaymentFailedBooleanWhether user’s last payment has failed or not.
SubscriptionStatusStringCurrent subscription status of user. This value will be either of
Active | Cancelled | Expired
BankReconciliationSettingsObjectBank reconciliation related settings. Described in details below.
User settings parameters
IsAdminBooleanWhether the user is admin
VATTextStringUser’s customized name of Vat
DescriptionTextStringUser’s customized name of Description
QuantityTextStringUser’s customized name of Quantity
RateTextStringUser’s customized name of Rate
DefaultVATRateNumericUser’s default vat rate
DisplayAllNominalCodesBooleanWether access to all nominal codes in all areas is enabled – this will mean that you can enter bank transactions against the same nominal codes as you enter purchases and sales.
TotalTextStringThis is the heading for the total column.
IncludeNominalCodeWithNominalNameBooleanWhether code should be included with name for nominal list
TransactionLockDateDateTransaction lock date. For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
TransactionLockEnabledBooleanWhether the transaction lock is enabled or not. If enabled, user won’t be allowed to alter invoice if it comes withing transaction lock date range.
DefaultBankAccountIdNumericUnique id of the default bank account of the user.
GoCardLessEnabledBooleanWhether the Gocardless account for the user has been configured or not.
Ref: https://gocardless.com/
CardPaymentEnabledBooleanWhether the user has configured any card payment option or not
ManualDiscountEnabledBooleanFlag indicating whether manual discount is enabled or not.
EmailSettingsObjectEmail settings information. Contains BCC enabled and BCC address fields.
StartPageUrlStringDepending on the startpage configured. This value will be either of
Overview | Settings | Reports | Customers | Quotes | Invoices | Suppliers | Receipts | Bank
PrimaryEmailStringPrimary email of the user.
UserNameStringUsername of the user.
CanBuyServiceBooleanIf one user can pay directly to KashFlow for subscription.
MOSSRegisteredBooleanFlag indicating whether user has registered for Mini One Stop Shop (MOSS).
CanOverrideDefaultPayOnlineProcessorNumeric(ReadOnly)Flag indicating if user can override default payment payonline processor (payonline link on emailed PDF of an invoice) from Bank Payment to Card Payment and vice versa while updating/creating using Invoice.PayOnlinePaymentProcessor property of invoice resource. 0 = false. 1 = true
DefaultPayOnlineProcessorNumericDefault PayOnlineProcessor for user. i.e. 15 = Bank Payment, 4 = Card Payment, 0 = Means default will be picked (or in case if Settings.UserSettings. CanOverrideDefaultPayOnlineProcessor is equal to 0)
Invoice settings parameters
CustomerReferenceTextStringUser’s customized name of Customer Reference
InvoiceTextStringUser’s customized name of Invoice
DefaultEmailTemplateNumberForInvoiceNumericUnique number of the default email template used for emailing invoices.
For further details about email templates, click here
DefaultEmailTemplateNumberForPaymentReceiptNumericUnique number of the default email template used for emailing invoice payment receipts.
For further details about email templates, click here
IsPackingSlipEnabledBooleanWhether packing slips are enabled for invoices in the user’s account
InvoicePdfFileNameFormatStringFormat for invoice pdf file name
Dropbox settings parameters
ConfiguredboolTrue, if any of the dropbox setting is available
ViaPost settings parameters
EnabledBooleanWhether ViaPost is enabled for the user
IncludeContactNameBooleanWhether contact name included with the address while sending a document using ViaPost
PrintDoubleSidedBooleanWhether ViaPost should print on both sides of the page while sending the document
SendInColorBooleanWhether ViaPost should print the contents in color instead of black and white while sending the document
UserNameStringViaPost username of the user
Purchase settings parameters
DefaultEmailTemplateNumberForPurchaseNumericUnique number of the default email template used for emailing purchases.
For further details about email templates, click here
DefaultEmailTemplateNumberForRemittanceNumericUnique number of the default email template used for emailing remittances.
For further details about email templates, click here
AdditionalFieldEnabledBooleanWhether an extra reference field for each purchase is enabled
AdditionalFieldNameStringName of the extra reference field for each purchase
AutoPayOnCreationBooleanAdd payments and mark a purchase as ‘Paid’ automatically while creating the purchase
CheckForDuplicateSupplierReferenceBooleanEnable the check to verify if the suppliers reference provided while creating a purchase has already been entered for the corresponding supplier
ShowAttachmentsIconBooleanDisplay an icon on the purchases page to indicate that a purchase has some items attached to it
Customer settings parameters
DefaultEmailTemplateNumberForStatementNumericUnique number of the default email template used for emailing statements.
For further details about email templates, click here
Automatic credit control settings parameters
EnabledBooleanFlag indicating whether automatic credit control is enabled for user account.
EnabledForNewCustomersBooleanFlag indicating whether automatic credit control should be enabled for newly created customers. If set to true all new customers created will have automatic credit control enabled.
SubscriptionPackageInfo parameters
NameStringName of the Subscription package the user has subscribed for.
PriceNumericThe subscription amount for the current package.
MultiUserSupportBooleanTrue, if subscription package supports multiuser
NumberOfInvoicesNumericThe maximumn number of invoices allowed for the subscription package, if unlimited invoices are not supported by the package.
PayrollEnabledBooleanTrue, if subscription package supports payroll application.
RecurringInvoicesSupportBooleanTrue, if subscription package supports creation of recurring invoices.
UnlimitedInvoiceSupportBooleanTrue, if subscription package supports creation of unlimited invoices.

Withholding Tax Settings Parameters

NameTypeDescription
EnabledOnPurchasesBooleanFlag indicating withholding taxes are enabled or not on purchases.
EnabledOnSalesBooleanFlag indicating withholding taxes are enabled or not on invoices.
NamestringName for this tax. Usually it would be CIS (Construction Industry Scheme) or WHT (Withholding Tax)
ShowDeductionBooleanFlag indicating whether to show a note on the invoice, below the total, detailing the amount of the deduction and how much is due after the deduction is applied.
NominalCodeNumericNominal code to track CIS.
ReferenceSettingsObjectObject containing information related to reference fields. Explained in more details below.
WithholdingTaxRateSettingsObjectObject containing information related to withholding tax rate. Explained in more details below.
ExclusionSettingsObjectObject containing information related to exclusions. Explained in more details below.
ReportSettingsObjectObject containing settings related to reports. Explained in more details below.

Reference Fields Settings parameters

NameTypeDescription
EnabledBooleanFlag indicating whether to enable customer /supplier reference fields .
Field1NameStringName for reference field 1.
Field2NameStringName for reference field 2.
Field3NameStringName for reference field 3.
Field4NameStringName for reference field 4.
Field5NameStringName for reference field 5.

Withholding Tax Rate Settings Parameters

NameTypeDescription
RateBasedOnNominalBooleanFlag indicating whether Rate depends on goods/services or customer/supplier. If true rate depends on goods/services.
DefaultWithholdingTaxRateNumericDefault CIS rate. You can edit this on a per customer/supplier basis
RateDeductedFromGrossBooleanFlag indication whether Is the rate to be deducted a percentage of the net amount or gross amount. If true rate is deducted from gross amount.
ListRatesForNominalsBooleanFlag indication whether to list the rates used for each type of goods/service.

Withholding Tax Exclusion Settings Parameters

NameTypeDescription
EnabledBooleanFlag indicating whether exclusions are enabled or not.
NameStringName given to excluded items.
NominalsObjectNominal assigned to this exclusion. It contains information such as nominal code, display as, name and id. All fields explained in more details below.

Withholding Tax Exclusion Nominal Parameters

NameTypeDescription
ExclusionIdNumericUnique database id for exclusion.
IdNumericUnique database id for nominal.
CodeNumericNominal code
NameStringNominal name
DisplayAsStringNominal display as

Withholding Tax Report Settings Parameters

NameTypeDescription
ShowNetAmountbooleanFlag indicating whether to show net amounts instead of gross.
GroupByCustomerbooleanFlag indicating whether to group items by Customer/Supplier.
ShowExclusionsbooleanFlag indicating whether to add a column to show the value of Materials.

Bank Reconciliation Settings Parameters

NameTypeDescription
NewStyleReconciliationEnabledBooleanWhen you reconcile a bank statement the starting balance shown is the starting balance on the date selected, including any older un-reconciled items. If this option is enabled older un-reconciled items will be excluded from this balance. Rather than a “starting balance”, the page will instead show a “reconciled balance”
ExcludeOldUnReconciledTransactionsBooleanFlag indicating whether split screen bank reconciliation is enabled or not.

GET Operation

Returns the list of different settings for user. To get list of user settings –

URL : /settings

Example response for GET of list of user settings


{
    "AssociatedAccounts": [],
    "AutomaticCreditControlSettings": {
        "Enabled": true,
        "EnabledForNewCustomers": true
    },
    "CompanySettings": {
        "Address": {
            "Line1": "",
            "Line2": "",
            "Line3": "",
            "Line4": "",
            "PostCode": ""
        },
        "ApiEnabled": false,
        "Application": "RSR",
        "BankReconciliationSettings": {
            "ExcludeOldUnReconciledTransactions": false,
            "NewStyleReconciliationEnabled": true
        },
        "CompanyName": "Empty DB",
        "DateFormat": "DD\/MM\/YYYY",
        "DaysLeftForSubscriptionToExpire": 310,
        "HomeCurrency": {
            "Code": "GBP",
            "DisplaySymbolOnRight": false,
            "ExchangeRate": 0,
            "Name": null,
            "Symbol": "£"
        },
        "IsDemoAccount": false,
        "LastPaymentFailed": false,
        "LeadCalled": "No",
        "MOSSRegistered": false, 
        "OnboarderName": "",
        "PartnerBrandingOptOut": true,
        "PartnerId": 0,
        "PayMonthly": true,
        "PrimaryContact": "lore",
        "SiteName": "KashFlow",
        "StockSettings": {
            "Enabled": false
        },
        "SubscriptionStatus": "Active",
        "SubscriptionType": "FreeTrial",
        "Telephone": "1234567890",
        "TotangoAccountStatus": "Free",
        "TotangoCreatedDate": "2014-07-09 12:00:00",
        "VATRegistered": true,
        "WithholdingTaxSettings": {
            "EnabledOnPurchases": false,
            "EnabledOnSales": true,
            "ExclusionSettings": {
                "Enabled": false,
                "Name": "Materials",
                "Nominals": []
            },
            "Name": "CIS",
            "NominalCode": 2212,
            "ReferenceSettings": {
                "Enabled": true,
                "Field1Name": "UTR No",
                "Field2Name": "Company Reg. Number",
                "Field3Name": "NI number",
                "Field4Name": "Verification Number",
                "Field5Name": ""
            },
            "ReportSettings": {
                "GroupByCustomer": false,
                "ShowExclusions": false,
                "ShowNetAmount": false
            },
            "ShowDeduction": false,
            "WithholdingTaxRateSettings": {
                "DefaultWithholdingTaxRate": 27.0000,
                "ListRatesForNominals": false,
                "RateBasedOnNominal": false,
                "RateDeductedFromGross": false
            }
        }
    },
    "CustomerSettings": {
        "DefaultEmailTemplateNumberForStatement": 3
    },
    "DisplaySettings": {
        "CustomColorsEnabled": false,
        "DisplayDensity": "Comfortable",
        "PrimaryColors": ["", "", "", ""],
        "SecondaryColors": ["", "", "", ""]
    },
    "DropboxSettings": {
        "Configured": true
    },
    "InvoiceSettings": {
        "CustomerReferenceText": "Purchase Order",
        "DefaultEmailTemplateNumberForInvoice": 2,
        "DefaultEmailTemplateNumberForPaymentReceipt": 0,
        "InvoicePdfFileNameFormat": "[invname]-[invnum]",
        "InvoiceText": "Invoice",
        "IsPackingSlipEnabled": true,
        "PackingSlipName": "Packing Slip",
        "ShowCustomerReferenceOnInvoiceList": false
    },
    "JournalSettings": {
        "IsEnabled": false
    },
    "PartnerRestrictions": {
        "Settings": {
            "ShowDisplayOptions": true
        },
        "Reports": {  
            "RestrictSelfAssessmentTaxes":false
        }
    },
    "ProjectSettings": {
        "IsEnabled": true,
        "ProjectOnBankLine": true,
        "ProjectOnInvoiceLine": false,
        "ProjectOnPurchaseLine": false,
        "ProjectText": "Project"
    },
    "PurchaseSettings": {
        "AdditionalFieldEnabled": false,
        "AdditionalFieldName": "Permit No.",
        "AutoPayOnCreation": false,
        "CheckForDuplicateSupplierReference": false,
        "DefaultEmailTemplateNumberForPurchase": 0,
        "DefaultEmailTemplateNumberForRemittance": 0,
        "ShowAttachmentsIcon": true
    },
    "QuoteSettings": {
        "DefaultEmailTemplateNumber": 0,
        "InvoiceConversionSettings": {
            "ChangeCategory": false,
            "CopyReferenceAsComment": false,
            "CopyReferenceAsPurchaseOrder": false,
            "Delete": true,
            "ReassignCategoryTo": 0
        },
        "QuoteShowTotalInPdf": false,
        "QuoteText": "Quote",
        "ReferenceText": "Quote Ref"
    },
    "SubscriptionPackageInfo": {
        "Name": "Classic KashFlow",
        "Price": 15.0000,
        "Restrictions": {
            "MultiCurrencySupport": true,
            "MultiUserSupport": true,
            "NumberOfInvoices": 0,
            "PayrollEnabled": true,
            "RecurringInvoicesSupport": true,
            "UnlimitedInvoiceSupport": true
        }
    },
    "UserSettings": {
        "CanBuyService": true,
        "CardPaymentEnabled": false,
        "DefaultBankAccountId": 9,
        "DefaultVATRate": 20.0000,
        "DescriptionText": "Description",
        "DisplayAllNominalCodes": true,
        "EmailSettings": {
            "BCCAddress": "",
            "BCCEnabled": false
        },
        "GoCardLessEnabled": false,
        "IncludeNominalCodeWithNominalName": false,
        "IsAdmin": true,
        "ManualDiscountEnabled": false,
        "PaymentProcessorDetails": null,
        "PrimaryEmail": "lorem.ipsum@iris.co.uk",
        "QuantityText": "Qty",
        "RateText": "Rate",
        "StartPageUrl": "Overview",
        "TotalText": "Total",
        "TransactionLockDate": "1900-01-01 12:00:00",
        "TransactionLockEnabled": false,
        "Turnover": 0,
        "UserName": "prashant",
        "VATText": "GST",
	"CanOverrideDefaultPayOnlineProcessor": 1,
	"DefaultPayOnlineProcessor": 0
	},
    "ViaPostSettings": {
        "Enabled": false,
        "IncludeContactName": false,
        "PrintDoubleSided": false,
        "SendInColor": false,
        "UserName": ""
    }
}

See how KashFlow works with your business and your books