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
| Name | Type | Description |
|---|---|---|
| List of associated accounts. Each associated account has the following parameters | ||
| CompanyName | String | Company name of the user |
| Username | String | Name of the user |
| Display settings parameters | ||
| DisplayDensity | String | Display setting for the user’s account. The 3 acceptable options are 1. Comfortable, 2. Cozy and 3. Compact |
| PrimaryColors | Collection | Array 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” ] |
| SecondaryColors | Collection | Array 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” ] |
| CustomColorsEnabled | Boolean | Whether custom coloring is enabled or not for the user’s account |
| Quote settings parameters | ||
| QuoteText | String | The name used to represent quote in the entire application |
| Reference | String | Title of the reference column |
| IncludeTotalInList | Boolean | Flag to indicate if total is to be displayed in the list of quotes |
| DefaultEmailTemplateNumber | Numeric | Unique number of the default email template used for emailing quotes. For further details about email templates, click here |
| InvoiceConversionSettings | Object | Settings for conversion of quote into an invoice |
| InvoiceConversionSettings fields | ||
| Delete | Boolean | Flag to indicate if quote should be deleted after it is converted to invoice |
| CopyReferenceAsComment | Boolean | Flag 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 |
| CopyReferenceAsPurchaseOrder | Boolean | Flag to indicate if quote reference is to be copied to customer reference field of invoice |
| ChangeCategory | Boolean | Flag to indicate if category of the quote is to be changed (re-assigned) after it is converted to invoice |
| ReassignCategoryTo | Numeric | The unique number of the category to which the quote is to be changed (re-assigned) after it is converted to invoice |
| Project settings parameters | ||
| IsEnabled | Boolean | Whether projects are enabled or not for the user |
| ProjectText | String | The name used to represent project in the entire application |
| ProjectOnInvoiceLine | Boolean | Whether project on invoice line items are enabled or not for the user |
| ProjectOnPurchaseLine | Boolean | Whether project on purchase line items are enabled or not for the user |
| ProjectOnBankLine | Boolean | Whether project on bank transaction line items are enabled or not for the user |
| Journal settings parameters | ||
| IsEnabled | Boolean | Whether journal is enabled for the user or not |
| Company settings parameters | ||
| CompanyName | String | Company name of the user |
| SubscriptionType | String | Whether the subscription for the account is ‘Paid’ or ‘FreeTrial’ |
| PayMonthly | Boolean | Whether the subscription payment for the account is done monthly |
| DaysLeftForSubscriptionToExpire | Numeric | Number of days left for the account subscription to expire |
| SiteName | String | The 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’ |
| HomeCurrency | Object | Information related to Home Currency |
| DateFormat | String | Returns either US format (MM/DD/YYYY) or UK format (DD/MM/YYYY). This date format applies to entire application. |
| VATRegistered | Boolean | Whether user is VAT registered |
| TotangoAccountStatus | String | User’s totango account status. Possible values are Free, Paying, Lapsed, Expired |
| TotangoCreatedDate | String | Totango creation date. For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE] |
| Application | String | “RSR” if user is using new rsr app else “Classic” |
| PartnerId | Numeric | Partner Id |
| ApiEnabled | Boolean | Whether SOAP API is enabled for user or not. |
| Address | Object | Address object which has 4 address lines and postal code |
| Telephone | String | Telephone number |
| OnboarderName | String | Onboarder Name |
| PartnerBrandingOptOut | Boolean | Wether to exclude partners branding. |
| LeadCalled | String | Possible values are Yes, No, Uncontactable |
| WithholdingTaxSettings | Object | All Withholding tax related settings. Described in details below. |
| StockSettings | Object | Stock management settings for user. “Enabled” field indicate whether stock management is enabled for user or not. |
| LastPaymentFailed | Boolean | Whether user’s last payment has failed or not. |
| SubscriptionStatus | String | Current subscription status of user. This value will be either of Active | Cancelled | Expired |
| BankReconciliationSettings | Object | Bank reconciliation related settings. Described in details below. |
| User settings parameters | ||
| IsAdmin | Boolean | Whether the user is admin |
| VATText | String | User’s customized name of Vat |
| DescriptionText | String | User’s customized name of Description |
| QuantityText | String | User’s customized name of Quantity |
| RateText | String | User’s customized name of Rate |
| DefaultVATRate | Numeric | User’s default vat rate |
| DisplayAllNominalCodes | Boolean | Wether 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. |
| TotalText | String | This is the heading for the total column. |
| IncludeNominalCodeWithNominalName | Boolean | Whether code should be included with name for nominal list |
| TransactionLockDate | Date | Transaction lock date. For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE] |
| TransactionLockEnabled | Boolean | Whether 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. |
| DefaultBankAccountId | Numeric | Unique id of the default bank account of the user. |
| GoCardLessEnabled | Boolean | Whether the Gocardless account for the user has been configured or not. Ref: https://gocardless.com/ |
| CardPaymentEnabled | Boolean | Whether the user has configured any card payment option or not |
| ManualDiscountEnabled | Boolean | Flag indicating whether manual discount is enabled or not. |
| EmailSettings | Object | Email settings information. Contains BCC enabled and BCC address fields. |
| StartPageUrl | String | Depending on the startpage configured. This value will be either of Overview | Settings | Reports | Customers | Quotes | Invoices | Suppliers | Receipts | Bank |
| PrimaryEmail | String | Primary email of the user. |
| UserName | String | Username of the user. |
| CanBuyService | Boolean | If one user can pay directly to KashFlow for subscription. |
| MOSSRegistered | Boolean | Flag indicating whether user has registered for Mini One Stop Shop (MOSS). |
| CanOverrideDefaultPayOnlineProcessor | Numeric | (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 |
| DefaultPayOnlineProcessor | Numeric | Default 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 | ||
| CustomerReferenceText | String | User’s customized name of Customer Reference |
| InvoiceText | String | User’s customized name of Invoice |
| DefaultEmailTemplateNumberForInvoice | Numeric | Unique number of the default email template used for emailing invoices. For further details about email templates, click here |
| DefaultEmailTemplateNumberForPaymentReceipt | Numeric | Unique number of the default email template used for emailing invoice payment receipts. For further details about email templates, click here |
| IsPackingSlipEnabled | Boolean | Whether packing slips are enabled for invoices in the user’s account |
| InvoicePdfFileNameFormat | String | Format for invoice pdf file name |
| Dropbox settings parameters | ||
| Configured | bool | True, if any of the dropbox setting is available |
| ViaPost settings parameters | ||
| Enabled | Boolean | Whether ViaPost is enabled for the user |
| IncludeContactName | Boolean | Whether contact name included with the address while sending a document using ViaPost |
| PrintDoubleSided | Boolean | Whether ViaPost should print on both sides of the page while sending the document |
| SendInColor | Boolean | Whether ViaPost should print the contents in color instead of black and white while sending the document |
| UserName | String | ViaPost username of the user |
| Purchase settings parameters | ||
| DefaultEmailTemplateNumberForPurchase | Numeric | Unique number of the default email template used for emailing purchases. For further details about email templates, click here |
| DefaultEmailTemplateNumberForRemittance | Numeric | Unique number of the default email template used for emailing remittances. For further details about email templates, click here |
| AdditionalFieldEnabled | Boolean | Whether an extra reference field for each purchase is enabled |
| AdditionalFieldName | String | Name of the extra reference field for each purchase |
| AutoPayOnCreation | Boolean | Add payments and mark a purchase as ‘Paid’ automatically while creating the purchase |
| CheckForDuplicateSupplierReference | Boolean | Enable the check to verify if the suppliers reference provided while creating a purchase has already been entered for the corresponding supplier |
| ShowAttachmentsIcon | Boolean | Display an icon on the purchases page to indicate that a purchase has some items attached to it |
| Customer settings parameters | ||
| DefaultEmailTemplateNumberForStatement | Numeric | Unique number of the default email template used for emailing statements. For further details about email templates, click here |
| Automatic credit control settings parameters | ||
| Enabled | Boolean | Flag indicating whether automatic credit control is enabled for user account. |
| EnabledForNewCustomers | Boolean | Flag 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 | ||
| Name | String | Name of the Subscription package the user has subscribed for. |
| Price | Numeric | The subscription amount for the current package. |
| MultiUserSupport | Boolean | True, if subscription package supports multiuser |
| NumberOfInvoices | Numeric | The maximumn number of invoices allowed for the subscription package, if unlimited invoices are not supported by the package. |
| PayrollEnabled | Boolean | True, if subscription package supports payroll application. |
| RecurringInvoicesSupport | Boolean | True, if subscription package supports creation of recurring invoices. |
| UnlimitedInvoiceSupport | Boolean | True, if subscription package supports creation of unlimited invoices. |
Withholding Tax Settings Parameters
| Name | Type | Description |
|---|---|---|
| EnabledOnPurchases | Boolean | Flag indicating withholding taxes are enabled or not on purchases. |
| EnabledOnSales | Boolean | Flag indicating withholding taxes are enabled or not on invoices. |
| Name | string | Name for this tax. Usually it would be CIS (Construction Industry Scheme) or WHT (Withholding Tax) |
| ShowDeduction | Boolean | Flag 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. |
| NominalCode | Numeric | Nominal code to track CIS. |
| ReferenceSettings | Object | Object containing information related to reference fields. Explained in more details below. |
| WithholdingTaxRateSettings | Object | Object containing information related to withholding tax rate. Explained in more details below. |
| ExclusionSettings | Object | Object containing information related to exclusions. Explained in more details below. |
| ReportSettings | Object | Object containing settings related to reports. Explained in more details below. |
Reference Fields Settings parameters
| Name | Type | Description |
|---|---|---|
| Enabled | Boolean | Flag indicating whether to enable customer /supplier reference fields . |
| Field1Name | String | Name for reference field 1. |
| Field2Name | String | Name for reference field 2. |
| Field3Name | String | Name for reference field 3. |
| Field4Name | String | Name for reference field 4. |
| Field5Name | String | Name for reference field 5. |
Withholding Tax Rate Settings Parameters
| Name | Type | Description |
|---|---|---|
| RateBasedOnNominal | Boolean | Flag indicating whether Rate depends on goods/services or customer/supplier. If true rate depends on goods/services. |
| DefaultWithholdingTaxRate | Numeric | Default CIS rate. You can edit this on a per customer/supplier basis |
| RateDeductedFromGross | Boolean | Flag 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. |
| ListRatesForNominals | Boolean | Flag indication whether to list the rates used for each type of goods/service. |
Withholding Tax Exclusion Settings Parameters
| Name | Type | Description |
|---|---|---|
| Enabled | Boolean | Flag indicating whether exclusions are enabled or not. |
| Name | String | Name given to excluded items. |
| Nominals | Object | Nominal 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
| Name | Type | Description |
|---|---|---|
| ExclusionId | Numeric | Unique database id for exclusion. |
| Id | Numeric | Unique database id for nominal. |
| Code | Numeric | Nominal code |
| Name | String | Nominal name |
| DisplayAs | String | Nominal display as |
Withholding Tax Report Settings Parameters
| Name | Type | Description |
|---|---|---|
| ShowNetAmount | boolean | Flag indicating whether to show net amounts instead of gross. |
| GroupByCustomer | boolean | Flag indicating whether to group items by Customer/Supplier. |
| ShowExclusions | boolean | Flag indicating whether to add a column to show the value of Materials. |
Bank Reconciliation Settings Parameters
| Name | Type | Description |
|---|---|---|
| NewStyleReconciliationEnabled | Boolean | When 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” |
| ExcludeOldUnReconciledTransactions | Boolean | Flag 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": "[email protected]",
"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": ""
}
}