Tag

A tag

Readonly Properties

Name Type Description
id string 22 Unique identifier - UUID
name string ≤ 50 The tag itself
taggings_count number Usage count of this tag, for all objects in whole company scope.

Writable Properties

Name Type Description

Links

Invoice

An invoice

Readonly Properties

Name Type Description
archived_pdf object (Attachment) Archived PDF version of the document. Is created when an document is printed and archived. A document can have multiple archived versions. This only returns the most recent one.
client object (Client) DEPRECATED: use contact
contact object (Contact) The contact for the document. Use contact_id field to set a contact.
cost_total number Cost total of all line items, 2 decimals places in document currency.
created_at string (date-time) Date the object was created in SK. Never changes afterwards.
exchange_rate number The exchange rate from the foreign document currency(eg. USD) to the company currency(EUR). If the rate is empty we use the exchange rate on the document date or today if doc.date is empty. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday). If you open the doc at a later time make sure to manually refresh the rate, as we dont change it.
gross_margin_pct number Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100
gross_margin_total number Total gross margin across all line items. Calculated from net_total-cost_total.
gross_total number Gross total of all line items, 2 decimals places in document currency.
gross_total_exchanged number Exchanged gross total, in your company currency.
id string 22 Unique identifier - UUID
net_total number Net total, 2 decimals places
net_total_base number Net total, 6 decimal places incl. discount
price_tax number DEPRECATED: use tax_total
price_total number DEPRECATED use net_total_base
recurring_id string 22 Recurring document ID, if the invoice was created from a recurring.
tax_total number Tax total, 2 decimals places
team_id string 22 A team uuid taken from the contact. If set only the team and its parent teams can see the record.
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
address_field string Receiver address, normally shown in envelope window. Defaults to client address_field if empty and client_id given.
client_id string 22 DEPRECATED: use contact_id
contact_id string 22 The contact uuid. When assigning a contact its language, currency, address_field (due days, cash discount) values are used for the document if those doc-fields are not set.
currency string 3 Currency code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
date string (date) Date the invoice is issued. Automatically set when invoice is opened. Required for non-draft documents. YYYY-MM-DD
due_date string (date) Auto-calculated from date + due days if empty and the document is opened. YYYY-MM-DD
due_days integer Used to calculate the due date of the document. Useless if date and due date are present.
external_ref string ≤ 255 Some external reference, whatever this may be.
items array [Line item | Divider item | Sub total item] ≥ 0 Items for the document. Access items of all types including divider and sub_total items. GOTCHAs when using items instead of line_items: You MUST set the type field(CamelCasesItem class name) on each item. You cannot use both, the line_items array is stronger for backward compat.
language string ≤ 10 Should be a valid language short-code: de-DE, fr, en-GB; like defined in your account language menu. When the document is emailed or printed, a localized version of a multi-language template(email, pdf) will be used if available. Defaults to the clients language, if empty and a client is assigned.
line_items array [Line item] DEPRECATED use items
lock_version integer Auto-incremented to prevent concurrent updates. First save wins and increments version.
notes_after string (text) Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.
notes_before string (text) Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used.
number string ≤ 50 Unique number assigned by SK invoice number schema. Auto-assigned when invoice is opened. Required unless doc status is draft.
payment_method string (enum) [cash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms] How the document is being payed. Used in new payments.
sepa_debit_sequence_type string (enum) [FRST, OOFF, RCUR, FNAL] SEPA direct debit sequence type. Check with you bank how they handle FRST(first) and FNAL(final) types. When exporting SEPA debit to your bank the type defaults to OOF if blank.
sepa_mandate_id string ≤ 35 SEPA mandate identifier needed in direct debit transactions. This is a unique id given by you to the customer beforehand.
sepa_mandate_signed_at string (date) Date the SEPA mandate was signed by your customer. Must not be in the future!
status string (enum) [draft, open, closed, overdue] Defaults to draft for new documents, unless otherwise stated. For new documents with status 'open' or 'closed' or doc where the status changes away from draft, following fields are set if empty: number(next in number schema), date(today), due date(due_days must be given). Only draft documents can be deleted. Beware that the overdue-status is virtual as it depends on the real status=open and the document date.
tag_list string Space separated list of tags. Are split and saved as Tag objects on create, update.
tax_exemption_id string 22 ID of a tax exemption. When set all item taxes are omitted.
title string ≤ 255 The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your invoice [number]'

Links

Payment

An payment must always be related to an document, so you must use the nested URL e.g. POST invoices/ID/payments. In this case the related_object_id/type are automatically set.

Readonly Properties

Name Type Description
amount_exchanged number The exchanged amount.
created_at string (date-time) Date the object was created in SK. Never changes afterwards
exchange_rate number The exchange rate from the foreign document currency(eg. USD) to the company currency(EUR). If the rate is empty we use the exchange rate on the document date or today if doc.date is empty. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday). If you open the doc at a later time make sure to manually refresh the rate, as we dont change it.
id string 22 Unique identifier - UUID
team_id string 22 A team uuid taken from the related object(e.g.invoice). If set only the team and its parent teams can see the record.

Writable Properties

Name Type Description
amount (required) number The payment amount
cash_discount number The cash discount amount. If a client withdraws a cash discount say 2% of 100€, he pays 98€ used in amount and 2€ in cash_discount. Handled separate for correction of sales,vat accounts in bookkeeping.
currency string 3 Currency code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
date (required) string (date) Date the payment was made. YYYY-MM-DD
external_ref string ≤ 255 Reference number f.ex. issued by the bank.
is_partial boolean If set the related document is NOT closed.
late_fee number Add a late fee if an invoice has payment reminders. We create a second payment for the last reminder and close all others. Set to 0, if you want to waive the fee(has not been paid). In this case all reminders are closed and we also correct the sales+debtor account with the open fees. This is a pure setter-method used in creation!
payment_method string (enum) [cash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms] How the payment was made.
related_object_id (required) string 22 uuid of the payments parent object. Is auto-set when using the nested URL POST invoices/ID/payments
related_object_type (required) string Object type of the payments parent. Is the camel-cased base class name: Document for invoice, credit_note. Is auto-set when using the nested URL POST invoices/ID/payments

Links

Company

A company is the main entity, so any data belongs to a company. It is identified by the current subdomain and cannot be edited via API atm

Readonly Properties

Name Type Description
account_link string (uri) Link to a company's SalesKing account.
created_at string (date-time) Date the record was created in SK. Never changes afterwards.
id string 22 Unique identifier - UUID
updated_at string (date-time) Last date when the record was edited.

Writable Properties

Name Type Description
addresses array [Addresses] A company can have many addresses, sorted by date descending(new first). Default address used in placeholder is the most recent one.
bank_account_number string ≤ 35 Bank account number.
bank_iban string ≤ 35 IBAN Number of the bank account. Is validated
bank_name string ≤ 70 Bank name
bank_number string ≤ 35 Bank number
bank_owner string ≤ 70 Bank account owner
bank_swift string ≤ 11 SWIFT BIC- Bank Identifier Code
currency string 3 Currency code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
email (required) string ≤ 100 Email address
language string ≤ 10 Default language, used for new users. Must be a valid language available in SalesKing
name string ≤ 100 Company name
phone_fax string ≤ 30 Fax number
phone_mobile string ≤ 30 Mobile phone number
phone_office string ≤ 30 Office phone number
sepa_creditor_id string ≤ 18 SEPA Creditor ID, needed for SEPA direct debit transactions.
sub_domain string ≤ 20 Unique subdomain identifying the company's SalesKing account.
tax_number string ≤ 30 Tax number, normally applies to a private person running a small business.
time_zone string ≤ 50 Default time zone, used for new users
url string ≤ 255 A company website
vat_number string ≤ 30 VAT number, for a company entitled to pay value added taxes.

Links

Task

An Task in SK.

Readonly Properties

Name Type Description
attachments array [Attachment] Attached files, uploads.
closed_at string (date) Date the task was completed.
contact object (Contact) The contact for the task. Use contact_id field to set a contact.
created_at string (date-time) Date the object was created in SK. Never changes afterwards
id string 22 Unique identifier - UUID
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
assignee_id string 22 User who should do the tasks.
contact_id string 22 Related contact of the tasks.
creator_id string 22 User who created the tasks.
description (required) string Notes, explanations for the task.
documents array [Document] A tasks can have many related documents.
name (required) string The task title.
status string (enum) [open, closed, overdue] New tasks are open by default, unless otherwise stated.

Links

Document

This resource is readonly and serves as a convenient way to query documents independent of their type(invoice, order,..). The specific document type is set in each object in the result-set. Internally Document is the base class for all types and special fields are defined in each child-class. Due to this some fields might be missing if you are using this meta-class in queries.

Readonly Properties

Name Type Description
created_at string (date-time) Date the object was created in SK. Never changes afterwards.
exchange_rate number The exchange rate from the foreign document currency(eg. USD) to the company currency(EUR). If the rate is empty we use the exchange rate on the document date or today if doc.date is empty. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday). If you open the doc at a later time make sure to manually refresh the rate, as we dont change it.
gross_total number Gross total of all line items, 2 decimals places in document currency.
gross_total_exchanged number Exchanged gross total, in your company currency.
id string 22 Unique identifier - UUID
net_total number Net total, 2 decimals places
net_total_base number Net total, 6 decimal places incl. discount
tax_total number Tax total, 2 decimals places
team_id string 22 A team uuid taken from the contact. If set only the team and its parent teams can see the record.
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
address_field string Receiver address, normally shown in envelope window. Defaults to client address_field.
client_id string 22 DEPRECATED: use contact_id
contact_id string 22 The contact uuid. When assigning a contact its language, currency, address_field (due days, cash discount) values are used for the document if those doc-fields are not set.
currency string 3 Currency code as defined by the ISO 4217 standard. 3-letter UPCASE: EUR, USD
date string (date) Date the document is issued. Automatically set when document is opened. Required for non-draft documents. YYYY-MM-DD
external_ref string ≤ 255 Some external reference, whatever this may be.
items array [Line item | Divider item | Sub total item] ≥ 0 Items for the document. Access items of all types including divider and sub_total items.
language string ≤ 10 Should be a valid language short-code: de-DE, fr, en-GB; like defined in your account language menu. When the document is emailed or printed, a localized version of a multi-language template(email, pdf) will be used if available. Defaults to the clients language, if empty and a client is assigned.
line_items array [Line items] Line items for the document
notes_after string (text) Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.
notes_before string (text) Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used.
number string ≤ 50 Unique number assigned by a user or automatic by the object's number schema.
object_type string The specific type of the document singular CamelCased: Invoice, PaymentReminder
tag_list string Space separated list of tags. Are split and saved as Tag objects on create, update.
title string ≤ 255 The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your invoice [number]'

Links

Credit note

A credit note

Readonly Properties

Name Type Description
archived_pdf object (Attachment) Archived PDF version of the document. Is created when an document is printed and archived. A document can have multiple archived versions. This only returns the most recent one.
client object (Client) DEPRECATED: use contact
contact object (Contact) The contact for the document. Use contact_id field to set a contact.
cost_total number Cost total of all line items, 2 decimals places in document currency.
created_at string (date-time) Date the object was created in SK. Never changes afterwards.
exchange_rate number The exchange rate from the foreign document currency(eg. USD) to the company currency(EUR). If the rate is empty we use the exchange rate on the document date or today if doc.date is empty. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday). If you open the doc at a later time make sure to manually refresh the rate, as we dont change it.
gross_margin_pct number Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100
gross_margin_total number Total gross margin across all line items. Calculated from net_total-cost_total.
gross_total number Gross total of all line items, 2 decimals places in document currency.
gross_total_exchanged number Exchanged gross total, in your company currency.
id string 22 Unique identifier - UUID
net_total number Net total, 2 decimals places
net_total_base number Net total, 6 decimal places incl. discount
price_tax number DEPRECATED: use tax_total
price_total number DEPRECATED: use net_total_base
tax_total number Tax total, 2 decimals places
team_id string 22 A team uuid taken from the contact. If set only the team and its parent teams can see the record.
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
address_field string Address field with the receiver. Shown in envelope window.
client_id string 22 DEPRECATED: use contact_id
contact_id string 22 The contact uuid. When assigning a contact its language, currency, address_field (due days, cash discount) values are used for the document if those doc-fields are not set.
currency string 3 Currency code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
date string (date) Date the credit note is issued. Automatically set when document is opened. Required unless doc status is draft. YYYY-MM-DD
due_date string (date) Auto-calculated from date + due days if empty and the document is opened. YYYY-MM-DD
due_days integer Used to calculate the due date of the credit note. Useless if date and due date are present.
external_ref string ≤ 255 Some external reference, whatever this may be.
items array [Line item | Divider item | Sub total item] ≥ 0 Items for the document. Access items of all types including divider and sub_total items. GOTCHAs when using items instead of line_items: You MUST set the type field(CamelCasesItem class name) on each item. You cannot use both, the line_items array is stronger for backward compat.
language string ≤ 10 Should be a valid language short-code: de-DE, fr, en-GB; like defined in your account language menu. When the document is emailed or printed, a localized version of a multi-language template(email, pdf) will be used if available. Defaults to the clients language, if empty and a client is assigned.
line_items array [Line item] DEPRECATED use items
lock_version integer Auto-incremented to prevent concurrent updates. First save wins.
notes_after string (text) Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.
notes_before string (text) Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used.
number string ≤ 50 Unique number assigned by SK credit note number schema. Auto-assigned when document is opened. Required unless doc status is draft.
payment_method string (enum) [cash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms] How the document is being payed. Used for new payments.
status string (enum) [draft, open, closed] Defaults to draft for new documents, unless otherwise stated. For new documents with status 'open' or 'closed' or doc where the status changes away from draft, following fields are set if empty: number(next in number schema), date(today), due date(due_days must be given). Only draft documents can be deleted.
tag_list string Space separated list of tags. Are split and saved as Tag objects on create, update.
tax_exemption_id string 22 ID of a tax exemption. When set all item taxes are omitted.
title string ≤ 255 The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your credit note [number]'

Links

Account entry

A entry for an account

Readonly Properties

Name Type Description
created_at string (date-time) Date the object was created. Never changes afterwards
document_id string 22 Document the entry is related to. This relation is set by an account billing.
id string 22 Unique identifier - UUID
item_id string 22 Line item on the document the entry is related to. This relation is set by an account billing or when a document is booked onto an account.
net_total number Net price of a single entry. Calculated from price_single * quantity
updated_at string (date-time) Date the object was edited.

Writable Properties

Name Type Description
_destroy boolean When set an existing entry will be deleted. This switch is used for entries passed during batch operations.
account_id (required) string 22 Account the entry belongs to.
billable boolean True if the entry can be billed.
billed_at string (date-time) Date the object was billed. Automatically set when the entry is used on an invoice.
date string (date-time) Date of the entry. Defaults to today. Entries are sorted by date per default.
description string (text) Entry description
name string ≤ 50 The name of an entry
price_single (required) number Net price of a single entry. If a product id is given, price_single is taken from the product if not set.
quantity number Quantity of the entry.
quantity_unit string ≤ 30 Quantity unit e.g: kg, days, month, ..
tax number Tax percentage

Links

Divider item

A divider item serves as a separator or headline between line items, e.g. to distinguish hardware and service products on a document. Access and creation is done via documents.items(instead of line_items) where each item has a 'type' field set to its CamelCased class name.

Readonly Properties

Name Type Description
created_at string (date-time) Date the object was created in SK. Never changes afterwards
id string 22 Unique identifier - UUID
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
_destroy boolean When set an existing item will be deleted. This switch is used for items submitted nested within their parent object(a document), which is default as long as there is no line item endpoint available.
name string ≤ 50 The divider text
position (required) integer Required since items are sorted by position.
type string ≤ 20 The item type: DividerItem. Must be set when creating new items via document.items array

Links

Text template

An text_template in SK

Readonly Properties

Name Type Description
created_at string (date-time) Date the object was created in SK. Never changes afterwards
id string 22 Unique identifier - UUID
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
kind (required) string (enum) [, invoice, estimate, credit_note, payment_reminder, order, contact, email] Kind of object the template can be used for. If empty the snippet can be used global. In this case watch not all placeholders are available: a client has different fields than an invoice.
name (required) string ≤ 50 A meaningful name.
team_id string 22 A team uuid. If set only the team and its parent teams can see the record.
text (required) string (text) Text which may contain placeholders, replaced when the template is used.

Links

Line item

A line item for a document

Readonly Properties

Name Type Description
cost_total number Total costs. Calculated from cost_single * quantity
created_at string (date-time) Date the object was created in SK. Never changes afterwards
gross_margin_pct number Gross margin percentage. Calculated from gross_margin_total/cost_total
gross_margin_total number Gross margin, the difference between revenue and cost before accounting for certain other costs. Calculated from net_total - cost_total
gross_total number Gross price. Net total with taxes applied.
id string 22 Unique identifier - UUID
net_total number Net price of a single item. Calculated from price_single * quantity * discount
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
_destroy boolean When set an existing item will be deleted. This switch is used for items passed-in nested inside their parent object(a document), which is default as long as there is no line item endpoint available.
cost number Cost price for a single item. Used to calculate the gross margin. Max 6 decimal places.
description string (text) Item description
discount number Discount in percent applied to the items net total. Can also be negative if you want to add additional charges.
external_ref string ≤ 255 Arbitrary number e.g. external product reference.
name string ≤ 50 The name of an item
position integer Position by which the items are sorted. Two items can have the same position(if you dont care) and numbers dont need to continuous
price_single (required) number Net price of a single item. If a product id is given, price_single is taken from the product if not set. Max 6 decimal places.
product_from_line_item boolean Saves and associates an instance of a Product from LineItem fields (name, description, quantity, unit, price, cost price), if no Product association is found. Accepted values to trigger this behaviour: 1, true
product_id string 22 A uuid of a product, used by this item. If set or changed, the product fields (name, description, quantity, unit, price, cost price) are copied if the according item fields are missing/blank. Besides this product link makes it possible to track a products turnover and find the documents it is used on.
quantity number ≥ 0 Quantity of the item. Must be >= 0. Max 6 decimal places.
quantity_unit string ≤ 30 Quantity unit: kg, days, month.
tax number Tax percent for a single item.
type string ≤ 20 The item type: LineItem. Must be set when creating new items via document.items array

Links

Account billing

BETA An account billing serves as the glue between an account a document and their related account entries and line items. It also lets one keep track of who billed what and when. A billing is created from billable account entries, which are turned into line items for a document.

Readonly Properties

Name Type Description
created_at string (date-time) Date the object was created in SK. Never changes afterwards
creator_id string 22 User who created the record.
document_id string 22 The document created by the billing.
id string 22 Unique identifier - UUID

Writable Properties

Name Type Description
account_id (required) string 22 The related account. Must be set for entries to be found.
document_type string (enum) [Invoice, CreditNote, Order, Estimate] The document type to create. CamelCase document class name. Invoice by default
group_entries_by string (enum) [name, day, week, month, year] Group multiple account entries into single line items, when creating a billing+document from entries. Account entries MUST have the SAME price_single and quantity unit, to land in a group. Date base groups also require the SAME entry name.
name string ≤ 100 A note for the billing e.g. happyPDF usage April 2014. The field is wildcard searchable
set_billed_at boolean Set billed at date for related account entries.
team_id string 22 A team uuid. Is inferred from the accounts team id.

Links

Estimate

An estimate

Readonly Properties

Name Type Description
archived_pdf object (Attachment) Archived PDF version of the document. Is created when an document is printed and archived. A document can have multiple archived versions. This only returns the most recent one.
client object (Client) DEPRECATED: use contact
contact object (Contact) The contact for the document. Use contact_id field to set a contact.
cost_total number Cost total of all line items, 2 decimals places in document currency.
created_at string (date-time) Date the object was created in SK. Never changes afterwards.
exchange_rate number The exchange rate from the foreign document currency(eg. USD) to the company currency(EUR). If the rate is empty we use the exchange rate on the document date or today if doc.date is empty. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday). If you open the doc at a later time make sure to manually refresh the rate, as we dont change it.
expected_revenue number Product of the probability and net total. In company currency
gross_margin_pct number Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100
gross_margin_total number Total gross margin across all line items. Calculated from net_total-cost_total.
gross_total number Gross total of all line items, 2 decimals places in document currency.
gross_total_exchanged number Exchanged gross total, in your company currency.
id string 22 Unique identifier - UUID
net_total number Net total, 2 decimals places
net_total_base number Net total, 6 decimal places incl. discount
tax_total number Tax total, 2 decimals places
team_id string 22 A team uuid taken from the contact. If set only the team and its parent teams can see the record.
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
address_field string Receiver address, normally shown in envelope window. Defaults to client address_field if empty and client_id present.
client_id string 22 DEPRECATED: use contact_id
close_date number Date when the deal is expected to be closed.
contact_id string 22 The contact uuid. When assigning a contact its language, currency, address_field (due days, cash discount) values are used for the document if those doc-fields are not set.
currency string 3 Currency code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
date string (date) Date the estimate is issued. Automatically set when estimate is opened. Required for non-draft documents. YYYY-MM-DD
due_date string (date) Auto-calculated from date + due days if empty and the estimate is opened. YYYY-MM-DD
due_days integer Used to calculate the valid-until date of the estimate. Useless if date and due date are present.
external_ref string ≤ 255 Some external reference, whatever this may be.
items array [Line item | Divider item | Sub total item] ≥ 0 Items for the document. Access items of all types including divider and sub_total items. GOTCHAs when using items instead of line_items: You MUST set the type field(CamelCasesItem class name) on each item. You cannot use both, the line_items array is stronger for backward compat.
language string ≤ 10 Should be a valid language short-code: de-DE, fr, en-GB; like defined in your account language menu. When the document is emailed or printed, a localized version of a multi-language template(email, pdf) will be used if available. Defaults to the clients language, if empty and a client is assigned.
line_items array [Line item] DEPRECATED use items
lock_version integer Auto-incremented to prevent concurrent updates. First save wins and increments version.
notes_after string (text) Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.
notes_before string (text) Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used.
number string ≤ 50 Unique number assigned by SK estimate number schema. Auto-assigned when estimate is opened. Required unless doc status is draft.
probability number Percentage of estimated confidence in closing the deal. Estimated Probability percentage of the net total amount
status string (enum) [draft, open, closed, rejected, billed] Defaults to draft for new documents, unless otherwise stated. For new documents with status 'open' or 'closed' or doc where the status changes away from draft, following fields are set if empty: number(next in number schema), date(today), due date(due_days must be given). Only draft documents can be deleted.
tag_list string Space separated list of tags. Are split and saved as Tag objects on create, update.
title string ≤ 255 The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your estimate [number]'

Links

Export template

An export_template in SK

Readonly Properties

Name Type Description
created_at string (date-time) Date the object was created in SK. Never changes afterwards
id string 22 Unique identifier - UUID
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
filename string ≤ 255 Name of the created export file. Date placeholders can be used: %y-%m-%d_%H-%M_clients.csv
kind (required) string (enum) [invoice, estimate, credit_note, payment_reminder, order, contact, payment, comment, email, history, product, recurring] Kind of object the template can be used for.
name (required) string ≤ 50 A meaningful name.
team_id string 22 A team uuid. If set only the team and its parent teams can see the record.
text (required) string (text) Text with placeholders, replaced when the template is used.

Links

Export

An export in SK

Readonly Properties

Name Type Description
attachments array [Attachment] The exported data as attachment.
created_at string (date-time) Date the object was created in SK. Never changes afterwards
finished_at string (date-time) Date the was finished
id string 22 Unique identifier - UUID
log string (text) Errors and warnings, can contain html markup f.ex. links to contacts with invalid back accounts when doing dtaus export
started_at string (date-time) Date the was started
status string (enum) [pending, in_progress, failed, success] The export status
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
collection_ids (required) string (text) Comma separated uuid's of the export objects. The backend uses a mysql text-column limited to ~64kb. 100 uuids are ~2.5kb
collection_type string ≤ 20 The type of data to export. Lower-case singular name of the export data's class(invoice,contact..), see available classes in json schema. Not required for text-exports, getting the type from the export_template.
kind (required) string (enum) [text, archived_pdf, attachments, allinone_pdf, sepa_debit, sepa_credit] The export type. text: uses an export template defined by a template_id. archived_pdf: zip with archived PDF(documents only). allinone_pdf: All archived PDF(Documents) in one big PDF. attachments: All attachments of the given objects as zip. SEPA: bank exports, relies on valid bank information in your company, the exported document and the contact.
team_id string 22 A team uuid. If set only the team and its parent teams can see the record.
template_id string 22 A export template uuid. Required for text exports. collection_type can be empty as is forced to the templates type

Links

Address

An address in SK is maintained within it's parent object(client, company). The first address(default_address) is used inside the address field of new documents. With multiple addresses sorting(first) is done by date, newest first. So if you add a new adddress it will be the new default one. See order and type property for details about ordering and accessing parcel work or home addresses.

Readonly Properties

Name Type Description
created_at string (date-time) Date the object was created in SK. Never changes afterwards
id string 22 Unique identifier - UUID
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
_destroy boolean When set an existing address will be deleted. This switch is only used when addresses are passed-in nested inside their parent object(a contact).
address1 string ≤ 100 Should contain the street or otherwise primary address information.
address2 string ≤ 100 Additional address information, like floor number
address_type string (enum) [work, home, parcel] Type of the address, as seen by vCard definition. There can only be one type. Inside of SK you can use placeholders like client.parcel_address.city to access the first parcel adr(Same for work_ / home_).
Besides the placeholder default_address, always returns the first address found. Sorting is done by the order(if set) else by date, newest first.
city (required) string ≤ 100 City for the address. Must at least be present for an address.
country string ≤ 100 Country of the address.
lat number Geo-Location latitude
long number Geo-Location longitude
order integer Addresses are normally sorted by date, newest first. If you need to strongly rely on their sorting e.g. default_address (always first) or have multiple addresses of one type(3 parcel), use this field for all adrs.
Single adrs are used in placeholders like: addresses.2.city, returning the second adr found(not necessarily one with order=2).
pobox string ≤ 10 Post office box number
state string ≤ 100 Country state of address
zip string ≤ 10 Zip number of the city. Length must be between 4..10

Links

User

A user as seen by SalesKing

Readonly Properties

Name Type Description
created_at string (date-time) Date the record was created in SK. Never changes afterwards.
id string 22 Unique identifier - UUID
updated_at string (date-time) Last date when the record was edited.

Writable Properties

Name Type Description
birthday string (date)
email (required) string ≤ 100 Email address of the user. Unique in SK
first_name string ≤ 50 First name
gender string (enum) [male, female] The users gender, used in salutation
language (required) string ≤ 10 The users language, reflected in the interface.
last_name string ≤ 50 Last name of a person. At least this or the organisation field must be filled for new records
phone_fax string ≤ 30 Fax number
phone_home string ≤ 30 Private phone number.
phone_mobile string ≤ 30 Mobile phone number
phone_office string ≤ 30 Office phone number
position string ≤ 50 Position of a person in a company.
time_zone string Time zone
title string ≤ 50 Academical title of a person e.g. Dr., Prof
url string ≤ 255 An url associated with the person, e.g its company website.

Links

Contact

A contact can be a lead, client or supplier, depending on its type field. Use the filter[type] parameter to show only contacts of a kind. Use this resource instead of clients, as they are deprecated and dropped in the future.

Readonly Properties

Name Type Description
address_field string Returns the address field used on new docs. Consist of Organisation name and default(first) address
created_at string (date-time) Date the record was created in SK. Never changes afterwards.
expected_revenue number Product of the probability and sales potential. e.g how much of the sales_potential can we get?
id string 22 Unique identifier - UUID
updated_at string (date-time) Last date when the record was edited.

Writable Properties

Name Type Description
addresses array [Address] A client can have many addresses, sorted by date descending(new first). Default address is the most recent one.
bank_account_number string ≤ 35 Bank account number.
bank_iban string ≤ 35 IBAN Number of the bank account. Is validated
bank_name string ≤ 70 Bank name
bank_number string ≤ 35 Bank number
bank_owner string ≤ 70 Bank account owner
bank_swift string ≤ 11 SWIFT BIC- Bank Identifier Code
birthday string (date) The birthday. YYYY-MM-DD
cash_discount number Default cash discount for new invoices.
converted_at string (date-time) Date the contact converted from lead to client or any other contact type (supplier)
currency string 3 Currency code as defined by the ISO 4217 standard(3-letter UPCASE: EUR, USD). If set the currency is taken for new documents.
due_days integer Default due days for new documents.
email string ≤ 100 Email address of the contact.
first_name string ≤ 50 First name of a person.
gender string (enum) [male, female] Can be empty for a company. Is used in salutation
is_employee boolean An employee gets number, organisation, tax and vat_number from its parent. If you set any of these, they are overwritten. When changing a parent-contact the fields on his direct child-employees are updated too.
language string ≤ 10 Should be a valid language short-code: de-DE, fr, en-GB; like defined in your account language menu. When the client is emailed, a localized version of a multi-language template(email, pdf) will be used if available. The language will also be set for new documents.
last_name string ≤ 50 Last name of a person. At least this or the organisation field must be filled for new records
lead_date string (date) Lead date e.g. date of first contact with your company. YYYY-MM-DD
lead_ref string Lead reference e.g. a tracking id, web-url
lead_source string Lead source describing where a contact came from e.g. a campaign name, website, facebook, URL
lock_version integer Increased on every edit, so SK can detect/prevent a concurrent edit by another user. First save wins.
notes string (text) Notes for a contact. For day to day information you should use comments instead.
number string ≤ 50 Unique number, auto-created by SK for new contacts(client, supplier) without number.
organisation (required) string ≤ 100 Name of a company. This or lastname must be present
parent_id string 22 ID of a parent contact.
payment_method string (enum) [cash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms] Default payment method for used for new documemts
phone_fax string ≤ 30 Fax number
phone_home string ≤ 30 Private phone number
phone_mobile string ≤ 30 Mobile phone number
phone_office string ≤ 30 Office phone number
position string ≤ 50 Position of a person in a company.
probability number Likelihood that the sales potential will be realised in percent e.g. How hot is the contact, How much of the sales potential will we get also see expected_revenue?
sales_potential number Sales potential for the contact e.g what is his budget, how much can he spend?
tag_list string Space separated list of tags. Are split and saved as Tag objects on create, update.
tax_exemption_id string 22 ID of a tax exemption. New documents inherit the tax exemption and will be created without any taxes.
tax_number string ≤ 30 Tax number, normally applies to a private person
team_id string 22 A team uuid. If set only the team and its parent teams can see the record. The team is set for all new documents and related objects like comments, attachments, emails. When changed ALL related objects are updated with the new team!!
title string ≤ 50 Academical title of a person e.g. Dr., Prof
type (required) string (enum) [Client, Lead, Supplier] ≤ 50 Type of contact
url string ≤ 255 An url associated with the person, e.g its company website.
vat_number string ≤ 30 VAT number, for a company or person paying value added taxes.

Links

Sub total item

A sub-total item shows a sum of the previous line items, e.g. to distinguish hardware and service costs on a document.

Readonly Properties

Name Type Description
created_at string (date-time) Date the object was created in SK. Never changes afterwards
gross_total number Gross sub-total
id string 22 Unique identifier - UUID
net_total number Net sub-total
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
_destroy boolean When set an existing item will be deleted. This switch is used for items passed-in nested inside their parent object(a document), which is default as long as there is no line item endpoint available.
name string ≤ 50 Title of the sub-total e.g. Hardware total
position (required) integer Required since items are sorted by position.
type string ≤ 20 The item type: SubTotalItem. Must be set when creating new items via document.items array

Links

Comment

An comment in SK must always be related to an object.

Readonly Properties

Name Type Description
created_at string (date-time) Date the object was created in SK. Never changes afterwards
id string 22 Unique identifier - UUID
team_id string 22 A team uuid taken from the related object. If set only the team and its parent teams can see the record.
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
related_object_id (required) string 22 uuid of the comments parent object.
related_object_type (required) string Object type of the comments parent. Is the camelcased base class name: Document for invoice, credit_note, contact
text (required) string The comment himself.

Links

Recurring

An recurring is used as an template for new invoices.

Readonly Properties

Name Type Description
client object (Client) DEPRECATED: use contact
contact object (Contact) The contact for the document. Use contact_id field to set a contact.
cost_total number Cost total of all line items, 2 decimals places in document currency.
created_at string (date-time) Date the object was created in SK. Never changes afterwards.
gross_margin_pct number Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100
gross_margin_total number Total gross margin across all line items. Calculated from net_total-cost_total.
gross_total number Gross total of all line items, 2 decimals places
id string 22 Unique identifier - UUID
net_total number Net total, 2 decimals places
net_total_base number Net total, 6 decimal places incl. discount
tax_total number Tax total, 2 decimals places
team_id string 22 A team uuid taken from the contact. If set only the team and its parent teams can see the record.
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
address_field string Receiver address, normally shown in envelope window. Defaults to client address_field if empty and client_id given.
auto_send string (enum) [email] Enable automatic sending of new invoices created from the recurring. Opens the invoice, creates a PDF and sends an email to the contact. GOTCHA's: check PDF-, Email-Template, SMTP Settings and of course the contacts email address! Since new recurrings which start today directly create new invoices, they are also SEND if auto_send is true!! If something fails, we'll send an error-email to the user who created the recurring. For success infos you can add yourself to the BCC of the email template or
client_id string 22 DEPRECATED: use contact_id
contact_id string 22 The contact uuid. When assigning a contact its language, currency, address_field (due days, cash discount) values are used for the document if those doc-fields are not set.
currency string 3 Currency code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
date (required) string (date) First date the recurring is issued. Not allowed to be in the past. YYYY-MM-DD
due_days integer Used to calculate the due date of the recurring. Useless if date and due date are present.
email_template_id string 22 The Email template used for the email in auto sending. Required when auto_send'ing is enabled.
external_ref string ≤ 255 Some external reference, whatever this may be.
final_date (required) string (date) The last date the recurring is executed. YYYY-MM-DD
frequency (required) string (enum) [yearly, monthly, weekly, quarterly, biweekly, sixmonthly] Recurring frequency
items array [Line item | Divider item | Sub total item] ≥ 0 Items for the document. Access items of all types including divider and sub_total items. GOTCHAs when using items instead of line_items: You MUST set the type field(CamelCasesItem class name) on each item. You cannot use both, the line_items array is stronger for backward compat.
language string ≤ 10 Should be a valid language short-code: de-DE, fr, en-GB; like defined in your account language menu. When the document is emailed or printed, a localized version of a multi-language template(email, pdf) will be used if available. Defaults to the clients language, if empty and a client is assigned.
line_items array [Line item] DEPRECATED use items
lock_version integer Auto-incremented to prevent concurrent updates. First save wins and increments version.
notes_after string (text) Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.
notes_before string (text) Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used.
number (required) string ≤ 50 Unique name to identify the document. Unlike all other document this one has no number schema and not auto assign
payment_method string (enum) [cash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms] How the document is being payed. Used in new payments.
pdf_template_id string 22 The PDF template used for printing the invoice when auto sending. Required when auto_send'ing is enabled.
sepa_debit_sequence_type string (enum) [FRST, OOFF, RCUR, FNAL] SEPA direct debit sequence type. Check with you bank how they handle FRST(first) and FNAL(final) types. When exporting SEPA debit to your bank the type defaults to OOF if blank.
sepa_mandate_id string ≤ 35 SEPA mandate identifier needed in direct debit transactions. This is a unique id given by you to the customer beforehand.
sepa_mandate_signed_at string (date) Date the SEPA mandate was signed by your customer. Must not be in the future!
tag_list string Space separated list of tags. Are split and saved as Tag objects on create, update.
tax_exemption_id string 22 ID of a tax exemption. When set all item taxes are omitted.
title string ≤ 255 The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your recurring [number]'

Links

Auth permission

A Permission authorises someone to execute actions(grants privileges) in the scope of a context. The context is a resource f.ex: clients, and the privileges a group of actions like: index, show, edit, update. A permission to read invoices has the context: invoices and as privileges: index,show.

Readonly Properties

Name Type Description
context_name string ≤ 255 The context for the permission, being a resource: clients, emails
id string 22 Unique identifier - UUID
privilege_list string ≤ 255 A permission has many privileges which define the actions someone can execute. Such actions are resource methods like index, update, edit, show

Writable Properties

Name Type Description
full_name string ≤ 255 Context_name and name localized: API Clients read - API Kunden anzeigen
name string ≤ 255 Name for the permission. Since a permission groups multiple privileges the name reflects what someone is allowed to do: read, update, delete. With 'read' granting acccess to the 'index' and 'show' actions of a resource.

Links

Email template

An email_template is used to simplify the creation of emails. When creating a new email just pass template id and all fields from the template are copied to the new email. The fields are NOT merged with present values in a new email object!

Readonly Properties

Name Type Description
created_at string (date-time) Date the object was created in SK. Never changes afterwards
id string 22 Unique identifier - UUID
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
bcc_addr string ≤ 255 Default blind copy receivers comma separated valid email addresses.
body (required) string (text) Body with placeholders, replaced when the template is used.
cc_addr string ≤ 255 Default copy receivers comma separated valid email addresses.
from_addr string ≤ 255 Default from address. A valid email address. Make sure your server(if custom SMPT settings for the API user) allows sending with this address.
kind (required) string (enum) [invoice, estimate, credit_note, payment_reminder, order, contact] Kind of object the template can be used for.
language string ≤ 10 Should be a valid language short-code: de-DE, fr, en-GB; like defined in your account language menu. A multi-language template must belong to a parent. From then on just choose the parent-template and the localized child version is used if the related object(client, invoice,..) of the email, has the appropriate language.
name (required) string ≤ 50 A meaningful name.
subject (required) string ≤ 255 Subject containing placeholders, replaced when the template is used.
team_id string 22 A team uuid. If set only the team and its parent teams can see the record.

Links

Payment reminder

A payment reminder belongs to an invoice and inherits it's line items from the invoice total(first item) and late fee settings(second item).

Readonly Properties

Name Type Description
archived_pdf object (Attachment) Archived PDF version of the document. Is created when an document is printed and archived. A document can have multiple archived versions. This only returns the most recent one.
client object (Client) DEPRECATED: use contact
contact object (Contact) The contact for the document. Is assigned through the related invoice.
contact_id string 22 The contact uuid. Is assigned through the related invoice.
created_at string (date-time) Date the object was created in SK. Never changes afterwards.
exchange_rate number The exchange rate from the foreign document currency(eg. USD) to the company currency(EUR). If the rate is empty we use the exchange rate on the document date or today if doc.date is empty. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday). If you open the doc at a later time make sure to manually refresh the rate, as we dont change it.
gross_total number DEPRECATED use net_total bcs there are no taxes applied
gross_total_exchanged number Exchanged gross total, in your company currency.
id string 22 Unique identifier - UUID
net_total number Net total, 2 decimals places
team_id string 22 A team uuid taken from the contact. If set only the team and its parent teams can see the record.
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
address_field string Receiver address, shown in envelope window. Defaults to invoice.client.address_field if created from invoice.
client_id string 22 DEPRECATED: use contact_id
currency string 3 Currency code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
date (required) string (date) Date the payment_reminder is issued. Automatically set when created from invoice. Defaults to today. YYYY-MM-DD
due_date string (date) Auto-calculated from date + due days if empty and the payment_reminder is opened. YYYY-MM-DD
due_days integer Used to calculate the due date of the payment_reminder. Useless if date and due date are present. Taken from settings when created from invoice
external_ref string ≤ 255 Some external reference, whatever this may be.
invoice_id (required) string 22 The invoice for the reminder. If set assumes all other fields are set to custom values, instead of filling them from the invoice. POSTing to invoices/:id/payment_reminders, automatically set this and all other fields.
items array [Line item] ≥ 1 Items for the document. GOTCHAs: you should NOT create items manually since we create them. The first item contains the invoice total and the optional second one the late_fee.
language string ≤ 10 Should be a valid language short-code: de-DE, fr, en-GB; like defined in your account language menu. When the document is emailed or printed, a localized version of a multi-language template(email, pdf) will be used if available. Defaults to the clients language, if empty and a client is assigned.
line_items array [Line item] DEPRECATED use items
lock_version integer Auto-incremented to prevent concurrent updates. First save wins and increments version.
notes_after string (text) Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used. Defaults to values from settings
notes_before string (text) Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used. Defaults to values from settings
status string (enum) [draft, open, closed, overdue] Defaults to open for new reminders, unless otherwise stated. Beware that the overdue-status is virtual as it depends on the real status=open and the document due_date.
tag_list string Space separated list of tags. Are split and saved as Tag objects on create, update.
title string ≤ 255 The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your payment_reminder [number]'. Defaults to values from settings

Links

Account

BETA An account to track times, expenses, projects, usages, etc. Those are single entry accounts, opposed to double entry accounting in bookkeeping accounts.

Readonly Properties

Name Type Description
balance number The account balance is the sum of all entries, also those from sub-accounts.
created_at string (date-time) Date the object was created in SK. Never changes afterwards
creator_id string 22 The user uuid who created the record.
id string 22 Unique identifier - UUID
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
billing_fee_name string ≤ 255 Name for a billing fee line item. The item is added to the resulting document upon each account_billing creation, if billing_fee_price_single is set.
billing_fee_price_single number Price of a billing fee line item. This field serves as a trigger of whether to add the item. The item is added to the resulting document upon each account_billing creation.
billing_fee_tax number Tax value for a billing fee line item. The item is added to the resulting document upon each account_billing creation.
budget number If an account is used to track budgetary things f.ex. projects, this fields can be used to perform calculations like: Are we still inside the allowed budget?
contact_id string 22 The contacts uuid to which the account is related.
default_price number The default price single for new account entries, if price single is empty on create. Max 6 decimal places.
default_unit string ≤ 30 The default quantity unit for new account entries, if unit is empty on create.
description string (text) ≤ 255 Account description
document_id string 22 Document uuid, related to the account.
hide_fields string ≤ 255 A list of account entry field names. The fields are hidden on account entry lists and forms so one can focus on the important inputs. For example hide: tax,description,billed_at
name (required) string ≤ 100 The name of the account
number string ≤ 50 Unique number assigned by you or if empty SK account number schema.
team_id string 22 A team uuid. If set only the team and its parent teams can see the record.

Links

Sub

Subscribe to push notifications(webhooks) about object livecycle events like new, update or delete. Only returns subscription for the current app, so you MUST be using oAuth. When a user removes your app its subs are also deleted.
To register you must supply
- callback_url: receives a POST containing a JSON object with the object in it's latest state, the user_id & subdomain, company_id, hmac-signed with your app secret as base64 encode string.
- channel: defining the event, made up of the SINGULAR object name and the action: invoice.delete, payment.new
- register auth_permissions: An app MUST request non-api permissions f.ex.: clients:create. Perms(on company,app,user,team) are checked before any publishing, so if a user cannot create clients in the interface, his apps will not receive any callbacks.

Readonly Properties

Name Type Description
created_at string (date-time) Date the record was created in SK. Never changes afterwards.
id string 22 Unique identifier - UUID
updated_at string (date-time) Last date when the record was edited.

Writable Properties

Name Type Description
callback_url (required) string (uri) ≤ 100 An url receiving the notification. The url MUST be within the url of the current app and receives a POST having the signed_request parameter containing an base64 encoded JSON object in the body.
channel (required) string ≤ 100 The channel to which to subscribe. See available at subs/channels.

Links

Product

A product in SK

Readonly Properties

Name Type Description
created_at string (date-time) Date the object was created in SK. Never changes afterwards
id string 22 Unique identifier - UUID
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
category_name string ≤ 255 Name of the product category. A new category is created if it does not exist.
cost number Cost price of a single product. Max 6 decimal places.
description string (text) Product description
name (required) string ≤ 50 The name of the product
number string ≤ 50 Unique number assigned by you or if empty SK product number schema.
price (required) number Net price of a single product. Max 6 decimal places.
quantity_unit string ≤ 30 Unit like kg, days, month.
tag_list string Space separated list of tags. Are split and saved as Tag objects on create, update.
tax number Tax percentage for this product.
team_id string 22 A team uuid. If set only the team and its parent teams can see the record.

Links

Email

An email in SK must always be related to an object. Receivers are limited to 5 per address field.

Readonly Properties

Name Type Description
attachments array [Attachment] The emails attachments.
created_at string (date-time) Date the object was created in SK. Never changes afterwards
delivered_at string (date-time) Date the email was delivered by SK. If set, the message cannot be edited anymore.
id string 22 Unique identifier - UUID
in_progress boolean Is set after an email has been scheduled for sending until it has been sent.
log text Logs error message when sending failed.
team_id string 22 A team uuid taken from the related object. If set only the team and its parent teams can see the record.
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
bcc_addr string (text) BCC addresses, comma separated. Max 5, format: a@b.de,'George'
body (required) string (text) The email text.
cc_addr string (text) CC addresses, comma separated. Max 5, format: a@b.de,'George'
from_addr string ≤ 255 From address. If empty the email of the current user is taken.
related_object_id (required) string 22 uuid of the emails parent object.
related_object_type (required) string Object type of the emails parent. Is the camelcased base class name: Document for invoice, credit_note, contact,..
subject (required) string ≤ 255 The email subject.
to_addr (required) string (text) TO addresses, comma separated. Max 5, format: a@b.de,'George'

Links

Attachment

An file attachment

Readonly Properties

Name Type Description
content_type string Auto detected on upload. Might not always reflect the real content type
created_at string (date-time) Date the object was created in SK. Never changes afterwards
disk_filename string ≤ 255 Unique filename set by SK
filename string ≤ 255 The filename as set when uploaded
id string 22 uuid of the object.
size integer Filesize in kb. Auto detected on upload.
url string (uri) DEPRECATED use attachments/ID/download

Writable Properties

Name Type Description
is_signed boolean True if the file(pdf) has been digitally signed.
related_object_id (required) string 22 uuid of the attachment parent object.
related_object_type (required) string Object type of the attachment parent. A base class name: Document(for invoice, credit_note) Contact, Message(for email), Template(for email, pdf template)
team_id string 22 A team uuid. If set only the team and its parent teams can see the record.

Links

Pdf template

An PDF template. For now this is a read-only resource ONLY returning your own templates. It fits the most important use-case: A user can select a print template.

Readonly Properties

Name Type Description
created_at string (date-time) Date the object was created in SK. Never changes afterwards
id string 22 Unique identifier - UUID
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
description string (text) Additional information about the template.
kind (required) string (enum) [invoice, estimate, credit_note, payment_reminder, order] Kind of object the template can be used for.
language string ≤ 10 Should be a valid language short-code: de-DE, fr, en-GB; like defined in your account language menu. A multi-language template should belong to a parent. From then on just choose the parent-template and the localized child version is used for printing if the related object(order, invoice,..) has the appropriate language.
name (required) string ≤ 50 Name of the template as shown to the user.
team_id string 22 A team uuid. If set only the team and its parent teams can see the record.

Links

Language

A language in SK can be assigned to documents, contacts and templates. When creating new documents, emails or PDF the language is used to select a specific template or language agnostic defaults. A language has many translations.

Readonly Properties

Name Type Description
created_at string (date-time) Date the object was created in SK. Never changes afterwards
id string 22 Unique identifier - UUID
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
code string ≤ 10 Language short-code
name (required) string ≤ 30 The name of the language, shown in the interface

Links

Order

An order

Readonly Properties

Name Type Description
archived_pdf object (Attachment) Archived PDF version of the document. Is created when an document is printed and archived. A document can have multiple archived versions. This only returns the most recent one.
client object (Client) DEPRECATED: use contact
contact object (Contact) The contact for the document. Use contact_id field to set a contact.
cost_total number Cost total of all line items, 2 decimals places in document currency.
created_at string (date-time) Date the object was created in SK. Never changes afterwards.
estimate_id string 22 Estimate document ID, if the order was created from a estimate.
exchange_rate number The exchange rate from the foreign document currency(eg. USD) to the company currency(EUR). If the rate is empty we use the exchange rate on the document date or today if doc.date is empty. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday). If you open the doc at a later time make sure to manually refresh the rate, as we dont change it.
gross_margin_pct number Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100
gross_margin_total number Total gross margin across all line items. Calculated from net_total-cost_total.
gross_total number Gross total of all line items, 2 decimals places in document currency.
gross_total_exchanged number Exchanged gross total, in your company currency.
id string 22 Unique identifier - UUID
net_total number Net total, 2 decimals places
net_total_base number Net total, 6 decimal places incl. discount
tax_total number Tax total, 2 decimals places
team_id string 22 A team uuid taken from the contact. If set only the team and its parent teams can see the record.
updated_at string (date-time) Date the object was edited in SK.

Writable Properties

Name Type Description
address_field string Receiver address, normally shown in envelope window. Defaults to client address_field if empty and client_id present.
client_id string 22 DEPRECATED: use contact_id
contact_id string 22 The contact uuid. When assigning a contact its language, currency, address_field (due days, cash discount) values are used for the document if those doc-fields are not set.
currency string 3 Currency code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
date string (date) Date the order is issued. Automatically set when order is opened. Required for non-draft documents. YYYY-MM-DD
due_date string (date) Auto-calculated from date + due days if empty and the document is opened. YYYY-MM-DD
due_days integer Used to calculate the due date for the document. Useless if date and due date are present.
external_ref string ≤ 255 Some external reference, whatever this may be.
items array [Line item | Divider item | Sub total item] ≥ 0 Items for the document. Access items of all types including divider and sub_total items. GOTCHAs when using items instead of line_items: You MUST set the type field(CamelCasesItem class name) on each item. You cannot use both, the line_items array is stronger for backward compat.
language string ≤ 10 Should be a valid language short-code: de-DE, fr, en-GB; like defined in your account language menu. When the document is emailed or printed, a localized version of a multi-language template(email, pdf) will be used if available. Defaults to the clients language, if empty and a client is assigned.
line_items array [Line item] DEPRECATED use items
lock_version integer Auto-incremented to prevent concurrent updates. First save wins and increments version.
notes_after string (text) Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.
notes_before string (text) Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used.
number string ≤ 50 Unique number assigned by SK order number schema. Auto-assigned when order is opened. Required unless doc status is draft.
payment_method string (enum) [cash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms] How the document is being payed. Used in new payments.
status string (enum) [draft, open, closed] Defaults to draft for new documents, unless otherwise stated. For new documents with status 'open' or 'closed' or doc where the status changes away from draft, following fields are set if empty: number(next in number schema), date(today), due date(due_days must be given). Only draft documents can be deleted.
tag_list string Space separated list of tags. Are split and saved as Tag objects on create, update.
tax_exemption_id string 22 ID of a tax exemption. When set all item taxes are omitted.
title string ≤ 255 The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your order [number]'

Links

Client

A client as seen by SalesKing. This resource is DEPRECATED please use contacts instead with type-field set 'Client'

Readonly Properties

Name Type Description
address_field string Returns the address field used on new docs. Consist of Organisation name and default(first) address
created_at string (date-time) Date the record was created in SK. Never changes afterwards.
id string 22 Unique identifier - UUID
updated_at string (date-time) Last date when the record was edited.

Writable Properties

Name Type Description
addresses array [Address] A client can have many addresses, sorted by date descending(new first). Default address is the most recent one.
bank_account_number string ≤ 35 Bank account number.
bank_iban string ≤ 35 IBAN Number of the bank account. Is validated
bank_name string ≤ 70 Bank name
bank_number string ≤ 35 Bank number
bank_owner string ≤ 70 Bank account owner
bank_swift string ≤ 11 SWIFT BIC- Bank Identifier Code
birthday string (date) The birthday. YYYY-MM-DD
cash_discount number Default cash discount for new invoices.
currency string 3 Currency code as defined by the ISO 4217 standard(3-letter UPCASE: EUR, USD). If set the currency is taken for new documents.
due_days integer Default due days for new invoices.
email string ≤ 100 Email address of the contact.
first_name string ≤ 50 First name of a person.
gender string (enum) [male, female] Can be empty for a company. Is used in salutation
language string ≤ 10 Should be a valid language short-code: de-DE, fr, en-GB; like defined in your account language menu. When the client is emailed, a localized version of a multi-language template(email, pdf) will be used if available. The language will also be set for new documents.
last_name string ≤ 50 Last name of a person. At least this or the organisation field must be filled for new records
lock_version integer Increased on every edit, so SK can detect/prevent a concurrent edit by another user. First save wins.
notes string (text) Notes for a contact. For day to day information you should use comments instead.
number string ≤ 50 Unique number, auto-created by SK for new client without number.
organisation (required) string ≤ 100 Name of a company. This or lastname must be present
payment_method string (enum) [cash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms] Default payment method for used for new documemts
phone_fax string ≤ 30 Fax number
phone_home string ≤ 30 Private phone number
phone_mobile string ≤ 30 Mobile phone number
phone_office string ≤ 30 Office phone number
position string ≤ 50 Position of a person in a company.
tag_list string Space separated list of tags. Are split and saved as Tag objects on create, update.
tax_number string ≤ 30 Tax number, normally applies to a private person
team_id string 22 A team uuid. If set only the team and its parent teams can see the record.
title string ≤ 50 Academical title of a person e.g. Dr., Prof
url string ≤ 255 An url associated with the person, e.g its company website.
vat_number string ≤ 30 VAT number, for a company or person paying value added taxes.

Links