SalesKing API Browser JSON Schema Browser

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

IDENTITY

true

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)

The export status

Valid Values

pending, in_progress, failed, success

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

* collection_ids 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 string (enum)

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. dtaus: German bank format, relies on valid bank information in your company and for each client of the exported documents. dtaus_lk Lastschrift. dtaus_gk: Gutschrift.

Valid Values

text, archived_pdf, attachments, dtaus_lk, dtaus_gk, allinone_pdf

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

GET exports/{id} self

GET exports instances

URL Params

/api/exports?sort=Value&filter[from]=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
filter[from]	string (date)	All objects with a date after the date
filter[to]	string (date)	All objects with date before the date
sort_by	string (enum) [created_at, updated_at]	Sort the results by the given field => number
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE exports/{id} destroy

PUT exports/{id} update

POST exports create

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

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

id string 22

Unique identifier - UUID

IDENTITY

true

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

description string (text)

Additional information about the template.

* kind string (enum)

Kind of object the template can be used for.

Valid Values

invoice, estimate, credit_note, payment_reminder, order

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

GET pdf_templates/{id} self

GET pdf_templates instances

URL Params

/api/pdf_templates?sort=Value&page=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
sort_by	string (enum) [created_at, updated_at, name, kind]	Sort the results by the given field
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC
filter[q]	string	Searches in name, description
filter[kind]	string (enum) [invoice, estimate, credit_note, payment_reminder, order]	Kind of object this template can be used for: invoice, order

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

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

IDENTITY

true

updated_at string (date-time)

Last date when the record was edited.

Writable Properties

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.

See

Addresses

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

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

GET companies/current current

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

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

IDENTITY

true

Writable Properties

* amount 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 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.

DEFAULT

false

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)

How the payment was made.

Valid Values

cash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms

* related_object_id string 22

uuid of the payments parent object. Is auto-set when using the nested URL POST invoices/ID/payments

* related_object_type 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

team_id string 22

A team uuid. If set only the team and its parent teams can see the record.

Links

GET payments/{id} self

GET payments instances

URL Params

/api/payments?per_page=Value&filter[to]=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
filter[q]	string	Search in title, number, address field
filter[from]	string (date)	All objects with a date after the date. YYYY-MM-DD
filter[to]	string (date)	All objects with date before the date. YYYY-MM-DD
sort_by	string (enum) [amount, created_at, updated_at]	Sort the results by the given field => number
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE payments/{id} destroy

POST payments create

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

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

IDENTITY

true

net_total number

Net sub-total

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

_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 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

Tag

A tag

Readonly Properties

id string 22

Unique identifier - UUID

IDENTITY

true

name string ≤ 50

The tag itself

taggings_count number

Usage count of this tag, for all objects in whole company scope.

Writable Properties

Links

GET tags/{id} self

GET tags instances

URL Params

/api/tags?sort_by=Value&per_page=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
filter[q]	string	Search in name
filter[related_object_type]	string	Filter tags by their related object base type
sort_by	string (enum) [filename, taggings_count]	Sort the results by the given field
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE tags/{id} destroy

PUT tags/{id} update

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

context_name string ≤ 255

The context for the permission, being a resource: clients, emails

id string 22

Unique identifier - UUID

IDENTITY

true

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

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

GET auth_permissions instances

URL Params

/api/auth_permissions?filter[q]=Value&sort=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
filter[q]	string	Search in name and context names
sort_by	string (enum) [auth_permission.name, auth_context.name]	Sort the results by the given field => number
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

GET auth_permissions/{id} self

User

A user as seen by SalesKing

Readonly Properties

created_at string (date-time)

Date the record was created in SK. Never changes afterwards.

id string 22

Unique identifier - UUID

IDENTITY

true

updated_at string (date-time)

Last date when the record was edited.

Writable Properties

birthday string (date)

* email string ≤ 100

Email address of the user. Unique in SK

first_name string ≤ 50

First name

gender string (enum)

The users gender, used in salutation

Valid Values

male, female

* language 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

GET users/current self

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

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

id string 22

Unique identifier - UUID

IDENTITY

true

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

_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 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

Estimate

An estimate

Readonly Properties

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.

See

client object (Client)

DEPRECATED: use contact

See

contact object (Contact)

The contact for the document. Use contact_id field to set a contact.

See

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

IDENTITY

true

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

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

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 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.

DEFAULT

any

See

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

See

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.

status string (enum)

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.

DEFAULT

draft

Valid Values

draft, open, closed, rejected, billed

tag_list string

Space separated list of tags. Are split and saved as Tag objects on create, update.

team_id string 22

A team uuid. If set only the team and its parent teams can see the record.

title string ≤ 255

The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your estimate [number]'

Links

GET estimates/{id} self

GET estimates instances

URL Params

/api/estimates?filter[ids]=Value&filter[creator_ids]=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
filter[q]	string	Search in title, number, address field
filter[status]	string	A single or a list of status, comma separated: open,closed,draft, rejected, billed
filter[number]	string	Find by exact number
filter[tags]	string	Filter by a space delimited list of tags
filter[from]	string (date)	Objects with a date after the date. YYYY-MM-DD
filter[to]	string (date)	Objects with date before the date. YYYY-MM-DD
filter[created_at_from]	string (date-time)	Objects with a creation date after the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z
filter[created_at_to]	string (date-time)	Objects with a creation date before the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z
filter[languages]	string	A list of language codes, comma separated
filter[client_ids]	string	DEPRECATED use contact_ids
filter[contact_ids]	string	A single or a list of contact uuids, comma separated
filter[ids]	string	A single or a list of document uuids, comma separated
filter[creator_ids]	string	Objects created by the given users uuids, comma separated
sort_by	string (enum) [title, number, created_at, updated_at, price_total, price_tax, date, due_date]	Sort the results by the given field => number
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE estimates/{id} destroy

PUT estimates/{id} update

POST estimates create

URL Params

/api/estimates?source=Value

Name	Type	Description / Example
source	string	Copies the source(excl. number,date) and returns a new draft document. You can pass any document type(e.g. invoice, order). Fields passed with the object(e.g. notes, title, address_field) are not overwritten.

GET estimates/{id}/attachments attachments

GET estimates/{id}/comments comments

GET estimates/{id}/emails emails

POST estimates/{id}/emails emails create

URL Params

/api/estimates/{id}/emails?template_id=Value&send=Value

Name	Type	Description / Example
template_id	string	UUID of an email template to use. If present template fields like subject, body, attachments are used for the current email.
send		Schedule email for sending. Omit this parameter or set value to 0 or false(String or Integer) to keep email as draft.
archived_pdf		Adds the archived pdf from the related resource(if it has one).

POST estimates/{id}/print print

URL Params

/api/estimates/{id}/print?base64=Value&template_id=Value

Name	Type	Description / Example
template_id *		UUID of a pdf template used to print the document. MUST be present
base64		If set the new pdf is returned inside the attachment JSON within 'base64' key. Leave empty to save traffic.

Text template

An text_template in SK

Readonly Properties

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

id string 22

Unique identifier - UUID

IDENTITY

true

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

* kind string (enum)

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.

Valid Values

, invoice, estimate, credit_note, payment_reminder, order, contact, email

* name 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 string (text)

Text which may contain placeholders, replaced when the template is used.

Links

GET text_templates/{id} self

GET text_templates instances

URL Params

/api/text_templates?sort=Value&page=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
sort_by	string (enum) [created_at, updated_at]	Sort the results by the given field => number
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE text_templates/{id} destroy

PUT text_templates/{id} update

POST text_templates create

Recurring

An recurring is used as an template for new invoices.

Readonly Properties

client object (Client)

DEPRECATED: use contact

See

contact object (Contact)

The contact for the document. Use contact_id field to set a contact.

See

created_at string (date-time)

Date the object was created in SK. Never changes afterwards.

gross_total number

Gross total of all line items, 2 decimals places

id string 22

Unique identifier - UUID

IDENTITY

true

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

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

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)

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

DEFAULT

Valid Values

email

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)

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 string (date)

The last date the recurring is executed. YYYY-MM-DD

* frequency string (enum)

Recurring frequency

Valid Values

yearly, monthly, weekly, quarterly, biweekly, sixmonthly

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.

DEFAULT

any

See

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

See

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 name to identify the document. Unlike all other document this one has no number schema and not auto assign

payment_method string (enum)

How the document is being payed. Used in new payments.

Valid Values

cash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms

pdf_template_id string 22

The PDF template used for printing the invoice when auto sending. Required when auto_send'ing is enabled.

tag_list string

Space separated list of tags. Are split and saved as Tag objects on create, update.

team_id string 22

A team uuid. If set only the team and its parent teams can see the record.

title string ≤ 255

The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your recurring [number]'

Links

GET recurrings/{id} self

GET recurrings instances

URL Params

/api/recurrings?sort=Value&sort_by=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
filter[q]	string	Search in title, number, address field
filter[tags]	string	Filter by a space delimited list of tags
filter[from]	string (date)	Objects with a date after the date. YYYY-MM-DD
filter[to]	string (date)	Objects with date before the date
filter[created_at_from]	string (date-time)	Objects with a creation date after the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z
filter[created_at_to]	string (date-time)	Objects with a creation date before the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z
filter[languages]	string	A list of language codes, comma separated
filter[client_ids]	string	DEPRECATED use contact_ids
filter[contact_ids]	string	A single or a list of contact uuids, comma separated
filter[ids]	string	A single or a list of document uuids, comma separated
filter[creator_ids]	string	Objects created by the given users uuids, comma separated
sort_by	string (enum) [title, number, created_at, updated_at, price_total]	Sort the results by the given field => number
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE recurrings/{id} destroy

PUT recurrings/{id} update

POST recurrings create

URL Params

/api/recurrings?source=Value

Name	Type	Description / Example
source	string	Copies the source(excl. number,date) and returns a new draft document. You can pass any document type(e.g. invoice, order). Fields passed with the object(e.g. notes, title, address_field) are not overwritten.

GET invoices?filter[recurring_ids]={id} invoices

GET recurrings/{id}/attachments attachments

GET recurrings/{id}/comments comments

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

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

id string 22

Unique identifier - UUID

IDENTITY

true

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

bcc_addr string ≤ 255

Default blind copy receivers comma separated valid email addresses.

* body 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 string (enum)

Kind of object the template can be used for.

Valid Values

invoice, estimate, credit_note, payment_reminder, order, contact

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 string ≤ 50

A meaningful name.

* subject 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

GET email_templates/{id} self

GET email_templates instances

URL Params

/api/email_templates?sort=Value&filter[q]=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
sort_by	string (enum) [created_at, updated_at]	Sort the results by the given field
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC
filter[q]	string	Searches in name, body, subject
filter[kind]	string (enum) [invoice, estimate, credit_note, payment_reminder, order, contact]	Kind of object this template can be used for

DELETE email_templates/{id} destroy

PUT email_templates/{id} update

POST email_templates create

Attachment

An file attachment

Readonly Properties

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.

IDENTITY

true

size integer

Filesize in kb. Auto detected on upload.

url string (uri)

DEPRECATED use attachments/ID/download

Writable Properties

is_signed boolean

True if the file(pdf) has been digitally signed.

* related_object_id string 22

uuid of the attachment parent object.

* related_object_type 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

GET attachments/{id} self

GET attachments/{id}/download download

GET attachments instances

URL Params

/api/attachments?filter[from]=Value&sort_by=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
filter[q]	string	Search in filename
filter[from]	string (date)	All objects created at and after the date
filter[to]	string (date)	All objects created at and before the date. YYYY-MM-DD
filter[related_object_type]	string	All objects belonging to the given object type. The singular base class name like: Document, Contact, Export, Message
sort_by	string (enum) [filename, related_object_id, related_object_type, created_at]	Sort the results by the given field
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE attachments/{id} destroy

Comment

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

Readonly Properties

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

id string 22

Unique identifier - UUID

IDENTITY

true

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

* related_object_id string 22

uuid of the comments parent object.

* related_object_type string

Object type of the comments parent. Is the camelcased base class name: Document for invoice, credit_note, contact

team_id string 22

A team uuid. If set only the team and its parent teams can see the record.

* text string

The comment himself.

Links

GET comments/{id} self

GET comments instances

URL Params

/api/comments?sort=Value&per_page=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
filter[q]	string	Search in text
filter[from]	string (date)	All objects with a date after the date. YYYY-MM-DD
filter[to]	string (date)	All objects with date before the date. YYYY-MM-DD
sort_by	string (enum) [created_at, updated_at]	Sort the results by the given field => number
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE comments/{id} destroy

PUT comments/{id} update

POST comments create

Product

A product in SK

Readonly Properties

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

id string 22

Unique identifier - UUID

IDENTITY

true

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

category_name string ≤ 255

Name of the product category. A new category is created if it does not exist.

cost_price number

Cost price of a single product

description string (text)

Product description

lock_version integer

Increased on every edit, so SK can detect/prevent a concurrent edit by another user. First save wins.

* name string ≤ 50

The name of the product

number string ≤ 50

Unique number assigned by you or if empty SK product number schema.

* price number

Net price of a single product

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

GET products/{id} self

GET products instances

URL Params

/api/products?filter[number]=Value&sort=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
filter[q]	["string", "number"]	Wildcard search in number, name, description, price
filter[number]	string	Search by exact number
filter[tags]	string	Filter by a space delimited list of tags
sort_by	string (enum) [name, number, price, created_at, updated_at]	Sort the results by the given field => number
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE products/{id} destroy

PUT products/{id} update

POST products create

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 base64 encode string containing a JSON object with the object in it's latest state, the user_id & subdomain, company_id, hmac-signed with your app secret.
- 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

created_at string (date-time)

Date the record was created in SK. Never changes afterwards.

id string 22

Unique identifier - UUID

IDENTITY

true

updated_at string (date-time)

Last date when the record was edited.

Writable Properties

* callback_url string (uri) ≤ 100

An url receiving the notification. The url MUST be within the url of the current app and receives a POST with a single signed_request parameter containing an base64 encoded JSON object.

* channel string ≤ 100

The channel to which to subscribe. See available at subs/channels.

Links

GET {id} self

GET subs/ instances

DELETE subs/{id} destroy

PUT subs/{id} update

GET subs/channels subs/channels

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

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

IDENTITY

true

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

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

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.

DEFAULT

any

See

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

See

Line items

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.

team_id string

A team uuid. If set only the team and its parent teams can see the record.

title string ≤ 255

The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your invoice [number]'

Links

GET documents/{id} self

GET documents instances

URL Params

/api/documents?filter[to]=Value&filter[tags]=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
filter[q]	string	Search in title, number, address field
filter[number]	string	Find by exact number
filter[tags]	string	Filter by a space delimited list of tags
filter[from]	string (date)	Objects with a date after the date. YYYY-MM-DD
filter[to]	string (date)	Objects with date before the date. YYYY-MM-DD
filter[created_at_from]	string (date-time)	Objects with a creation date after the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z
filter[created_at_to]	string (date-time)	Objects with a creation date before the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z
filter[languages]	string	A list of language codes, comma separated
filter[client_ids]	string	DEPRECATED use contact_ids
filter[contact_ids]	string	A single or a list of contact uuids, comma separated
filter[ids]	string	A single or a list of document uuids, comma separated
filter[creator_ids]	string	Objects created by the given users uuids, comma separated
sort_by	string (enum) [title, number, created_at, updated_at, price_total, price_tax, date, due_date]	Sort the results by the given field => number
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

Export template

An export_template in SK

Readonly Properties

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

id string 22

Unique identifier - UUID

IDENTITY

true

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

filename string ≤ 255

Name of the created export file. Date placeholders can be used: %y-%m-%d_%H-%M_clients.csv

* kind string (enum)

Kind of object the template can be used for.

Valid Values

invoice, estimate, credit_note, payment_reminder, order, contact, payment, comment, email, history, product, recurring

* name 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 string (text)

Text with placeholders, replaced when the template is used.

Links

GET export_templates/{id} self

GET export_templates instances

URL Params

/api/export_templates?sort_by=Value&page=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
sort_by	string (enum) [created_at, updated_at]	Sort the results by the given field => number
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE export_templates/{id} destroy

PUT export_templates/{id} update

POST export_templates create

Line item

A line item for a document

Readonly Properties

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

gross_total number

Gross price. Net total with taxes applied.

id string 22

Unique identifier - UUID

IDENTITY

true

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

_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.

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

Required since items are sorted by position.

price_single number

Net price of a single item

product_id string 22

A uuid of a product, referenced in this item. This makes it easier to track a products turnover and list the documents it is used on. Also see use_product

* quantity number ≥ 0

Quantity of the item. Must be >= 0

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

use_product boolean

If set and product_id is present, the products name, description, quantity, unit, price are copied if the according item fields are missing.

Links

Order

An order

Readonly Properties

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.

See

client object (Client)

DEPRECATED: use contact

See

contact object (Contact)

The contact for the document. Use contact_id field to set a contact.

See

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

IDENTITY

true

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

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

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.

DEFAULT

any

See

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

See

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)

How the document is being payed. Used in new payments.

Valid Values

cash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms

status string (enum)

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.

DEFAULT

draft

Valid Values

draft, open, closed

tag_list string

Space separated list of tags. Are split and saved as Tag objects on create, update.

team_id string 22

A team uuid. If set only the team and its parent teams can see the record.

title string ≤ 255

The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your order [number]'

Links

GET orders/{id} self

GET orders instances

URL Params

/api/orders?filter[created_at_to]=Value&sort=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
filter[q]	string	Search in title, number, address field
filter[status]	string	A single or a list of status, comma separated: open,close,draft
filter[number]	string	Find by exact number
filter[tags]	string	Filter by a space delimited list of tags
filter[from]	string (date)	Objects with a date after the date. YYYY-MM-DD
filter[to]	string (date)	Objects with date before the date. YYYY-MM-DD
filter[created_at_from]	string (date-time)	Objects with a creation date after the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z
filter[created_at_to]	string (date-time)	Objects with a creation date before the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z
filter[languages]	string	A list of language codes, comma separated
filter[client_ids]	string	DEPRECATED use contact_ids
filter[contact_ids]	string	A single or a list of contact uuids, comma separated
filter[ids]	string	A single or a list of document uuids, comma separated
filter[creator_ids]	string	Objects created by the given users uuids, comma separated
sort_by	string (enum) [title, number, created_at, updated_at, price_total, price_tax, date, due_date]	Sort the results by the given field => number
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE orders/{id} destroy

PUT orders/{id} update

POST orders create

URL Params

/api/orders?source=Value

Name	Type	Description / Example
source	string	Copies the source(excl. number,date) and returns a new draft document. You can pass any document type(e.g. invoice, order). Fields passed with the object(e.g. notes, title, address_field) are not overwritten.

GET orders/{id}/attachments attachments

GET orders/{id}/comments comments

GET orders/{id}/emails emails

POST orders/{id}/emails emails create

URL Params

/api/orders/{id}/emails?send=Value&archived_pdf=Value

Name	Type	Description / Example
template_id	string	UUID of an email template to use. If present template fields like subject, body, attachments are used for the current email.
send		Schedule email for sending. Omit this parameter or set value to 0 or false(String or Integer) to keep email as draft.
archived_pdf		Adds the archived pdf from the related resource(if it has one).

POST orders/{id}/print print

URL Params

/api/orders/{id}/print?template_id=Value&base64=Value

Name	Type	Description / Example
template_id *		UUID of a pdf template used to print the document. MUST be present
base64		If set the new pdf is returned inside the attachment JSON within 'base64' key. Leave empty to save traffic.

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

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

id string 22

Unique identifier - UUID

IDENTITY

true

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

code string ≤ 10

Language short-code

* name string ≤ 30

The name of the language, shown in the interface

Links

GET languages/{id} self

GET languages instances

URL Params

/api/languages?page=Value&sort_by=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
sort_by	string (enum) [name, code, created_at, updated_at]	Sort the results by the given field => code
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE languages/{id} destroy

PUT languages/{id} update

POST languages create

Credit note

A credit note

Readonly Properties

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.

See

client object (Client)

DEPRECATED: use contact

See

contact object (Contact)

The contact for the document. Use contact_id field to set a contact.

See

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

IDENTITY

true

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

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

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.

DEFAULT

any

See

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

See

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)

How the document is being payed. Used for new payments.

Valid Values

cash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms

status string (enum)

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.

DEFAULT

draft

Valid Values

draft, open, closed

tag_list string

Space separated list of tags. Are split and saved as Tag objects on create, update.

team_id string 22

A team uuid. If set only the team and its parent teams can see the record.

title string ≤ 255

The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your credit note [number]'

Links

GET credit_notes/{id} self

GET credit_notes instances

URL Params

/api/credit_notes?filter[created_at_from]=Value&page=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
filter[q]	string	Search in title, number, address field
filter[status]	string	A single or a list of status, comma separated: open,closed,overdue,draft
filter[number]	string	Find by exact number
filter[tags]	string	Filter by a space delimited list of tags
filter[from]	date	Objects with a date on and after the date. YYYY-MM-DD
filter[to]	date	Objects with date before and on the date. YYYY-MM-DD
filter[created_at_from]	string (date-time)	Objects with a creation date after the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z
filter[created_at_to]	string (date-time)	Objects with a creation date before the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z
filter[languages]	string	A list of language codes, comma separated
filter[client_ids]	string	A single or a list of client uuids, comma separated
filter[ids]	string	A single or a list of document uuids, comma separated
filter[creator_ids]	string	Objects created by the given users uuids, comma separated
sort_by	string (enum) [title, number, created_at, updated_at, price_total, price_tax, date, due_date]	Sort the results by the given field => number
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE credit_notes/{id} destroy

PUT credit_notes/{id} update

POST credit_notes create

URL Params

/api/credit_notes?source=Value&cancel=Value

Name	Type	Description / Example
source		Copies the source(excl. number,date) and returns a new draft document. You can pass any document type(e.g. invoice, order). Fields passed with the object(e.g. notes, title, address_field) are not overwritten.
cancel	- Depends on: source	Cancelling a document negates its line item values. A source id must be set.

GET credit_notes/{id}/attachments attachments

GET credit_notes/{id}/payments payments

GET credit_notes/{id}/comments comments

GET credit_notes/{id}/emails emails

POST credit_notes/{id}/emails emails create

URL Params

/api/credit_notes/{id}/emails?send=Value&archived_pdf=Value

Name	Type	Description / Example
template_id	string	UUID of an email template to use. If present template fields like subject, body, attachments are used for the current email.
send		Schedule email for sending. Omit this parameter or set value to 0 or false(String or Integer) to keep email as draft.
archived_pdf		Adds the archived pdf from the related resource(if it has one).

POST invoices/{id}/payments payment create

POST credit_notes/{id}/print print

URL Params

/api/credit_notes/{id}/print?template_id=Value&base64=Value

Name	Type	Description / Example
template_id *		UUID of a pdf template used to print the document. MUST be present
base64		If set the new pdf is returned inside the attachment JSON within 'base64' key. Leave empty to save traffic.

Client

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

Readonly Properties

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

IDENTITY

true

updated_at string (date-time)

Last date when the record was edited.

Writable Properties

addresses array [Address]

A client can have many addresses, sorted by date descending(new first). Default address is the most recent one.

See

Address

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)

Can be empty for a company. Is used in salutation

Valid Values

male, female

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 string ≤ 100

Name of a company. This or lastname must be present

payment_method string (enum)

Default payment method for used for new documemts

Valid Values

cash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms

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

GET clients/{id} self

GET clients instances

URL Params

/api/clients?filter[birthday_from]=Value&filter[ids]=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
filter[q]	string	Wildcard search in first, last_name, organisation, email, number
filter[tags]	string	Filter by a space delimited list of tags
filter[ids]	string	A single or a list of client uuids, comma separated
filter[created_at_from]	string (date-time)	Objects with a creation date after the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z
filter[created_at_to]	string (date-time)	Objects with a creation date before the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z
filter[birthday_from]	string (date)	Contacts with a birthday after and on the date. Leave the birthday-to date blank to only search on this day. YYYY-MM-DD
filter[birthday_to]	string (date)	Contacts with a birthday date before and on the date. YYYY-MM-DD
filter[creator_ids]	string	Objects created by the given users uuids, comma separated
filter[number]	string	Search by number where the number is matched from the start: number%
filter[languages]	string	A single or a list of language codes, comma separated
sort_by	string (enum) [organisation, number, email, first_name, last_name, created_at, updated_at]	Sort the results by the given field => number
sort	(enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE clients/{id} destroy

PUT clients/{id} update

POST clients create

GET clients/{id}/documents documents

GET clients/{id}/attachments attachments

GET clients/{id}/invoices invoices

GET clients/{id}/estimates estimates

GET clients/{id}/orders orders

GET clients/{id}/credit_notes credit_notes

GET clients/{id}/recurrings recurrings

GET clients/{id}/payment_reminders payment_reminders

GET clients/{id}/comments comments

GET clients/{id}/emails emails

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

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.

See

client object (Client)

DEPRECATED: use contact

See

contact object (Contact)

The contact for the document. Is assigned through the related invoice.

See

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

IDENTITY

true

net_total number

Net total, 2 decimals places

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

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 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 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.

DEFAULT

any

See

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

See

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)

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.

DEFAULT

open

Valid Values

draft, open, closed, overdue

tag_list string

Space separated list of tags. Are split and saved as Tag objects on create, update.

team_id string 22

A team uuid. If set, only the team and its parent teams can see the record. Defaults to team id from invoice

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

GET payment_reminders/{id} self

GET payment_reminders instances

URL Params

/api/payment_reminders?filter[ids]=Value&filter[q]=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
filter[q]	string	Search in title, number, address field
filter[tags]	string	Filter by a space delimited list of tags
filter[from]	string (date)	All objects with a date after the date. YYYY-MM-DD
filter[to]	string (date)	All objects with date before the date. YYYY-MM-DD
filter[languages]	string	A list of language codes, comma separated
filter[client_ids]	string	DEPRECATED use contact_ids
filter[contact_ids]	string	A single or a list of contact uuids, comma separated
filter[ids]	string	A single or a list of document uuids, comma separated
filter[status]	string	A single or a list of status, comma separated: open,closed,overdue,draft
sort_by	string (enum) [title, number, created_at, updated_at, price_total, price_tax, date, due_date]	Sort the results by the given field => number
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE payment_reminders/{id} destroy

PUT payment_reminders/{id} update

POST payment_reminders create

GET payment_reminders/{id}/attachments attachments

GET payment_reminders/{id}/emails emails

POST payment_reminders/{id}/emails emails create

URL Params

/api/payment_reminders/{id}/emails?send=Value&template_id=Value

Name	Type	Description / Example
template_id	string	UUID of an email template to use. If present template fields like subject, body, attachments are used for the current email.
send		Schedule email for sending. Omit this parameter or set value to 0 or false(String or Integer) to keep email as draft.
archived_pdf		Adds the archived pdf from the related resource(if it has one).

POST payment_reminders/{id}/print print

URL Params

/api/payment_reminders/{id}/print?template_id=Value&base64=Value

Name	Type	Description / Example
template_id *		UUID of a pdf template used to print the document. MUST be present
base64		If set the new pdf is returned inside the attachment JSON within 'base64' key. Leave empty to save traffic.

Invoice

An invoice

Readonly Properties

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.

See

client object (Client)

DEPRECATED: use contact

See

contact object (Contact)

The contact for the document. Use contact_id field to set a contact.

See

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

IDENTITY

true

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

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

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.

DEFAULT

any

See

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

See

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)

How the document is being payed. Used in new payments.

Valid Values

cash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms

status string (enum)

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.

DEFAULT

draft

Valid Values

draft, open, closed, overdue

tag_list string

Space separated list of tags. Are split and saved as Tag objects on create, update.

team_id string 22

A team uuid. If set only the team and its parent teams can see the record.

title string ≤ 255

The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your invoice [number]'

Links

GET invoices/{id} self

GET invoices instances

URL Params

/api/invoices?filter[tags]=Value&filter[from]=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 10, max is 100
filter[q]	string	Search in title, number, address field
filter[status]	string	A single or a list of status, comma separated: open,closed,overdue,draft
filter[number]	string	Find by exact number
filter[tags]	string	Filter by a space delimited list of tags
filter[from]	string (date)	Objects with a date after the date. YYYY-MM-DD
filter[to]	string (date)	Objects with date before the date. YYYY-MM-DD
filter[languages]	string	A list of language codes, comma separated
filter[client_ids]	string	DEPRECATED use contact_ids
filter[contact_ids]	string	A single or a list of contact uuids, comma separated
filter[ids]	string	A single or a list of document uuids, comma separated
filter[creator_ids]	string	Objects created by the given users uuids, comma separated
filter[recurring_ids]	string	Documents belonging to the given recurring uuids, comma separated
sort_by	string (enum) [title, number, created_at, updated_at, price_total, price_tax, date, due_date]	Sort the results by the given field => number
sort	string (enum) [ASC, DESC]	Sort the results in ASC or DESC

DELETE invoices/{id} destroy

PUT invoices/{id} update

POST invoices create

URL Params

/api/invoices?source=Value&cancel=Value

Name	Type	Description / Example
source	string	Copies the source(excl. number,date) and returns a new draft document. Fields passed with the object(e.g. notes, title, address_field) are not overwritten. When copying a different document type e.g. creating an invoice from an order(pass an order ID), ONLY the items, contact, currency and tag list are taken from the source doc.
cancel	boolean - Depends on: source	Cancelling a document copies the source and negates all line item values. A source id MUST be set.

GET invoices/{id}/attachments attachments

GET invoices/{id}/payments payments

GET invoices/{id}/payment_reminders payment_reminders

GET invoices/{id}/comments comments

GET invoices/{id}/emails emails

POST invoices/{id}/emails emails create

URL Params

/api/invoices/{id}/emails?send=Value&archived_pdf=Value

Name	Type	Description / Example
template_id	string	UUID of an email template to use. If present template fields like subject, body, attachments are used for the current email.
send		Schedule email for sending. Omit this parameter or set value to 0 or false(String or Integer) to keep email as draft.
archived_pdf		Adds the archived pdf from the related resource(if it has one).

POST invoices/{id}/payments payment create

POST invoices/{id}/print print

URL Params

/api/invoices/{id}/print?template_id=Value&base64=Value

Name	Type	Description / Example
template_id *		UUID of a pdf template used to print the document. MUST be present
base64		If set(any val) the new pdf is returned inside the attachment JSON within 'base64' key. Ommit to save traffic.

Email

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

Readonly Properties

attachments array [Attachment]

The emails attachments.

See