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?per_page=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

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 company currency(eg. EUR) to the document currency(USD). The rate is set on document open with the exchange rate based on the document date. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday).

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.

external_ref string ≤ 255

Some external reference, whatever this may be.

items array ≥ 0

Items for the document. Access items of all types including divider and sub_total items.

DEFAULT

any

ITEMS

[{"$ref"=>"./line_item.json#properties"}, {"$ref"=>"./divider_item.json#properties"}, {"$ref"=>"./sub_total_item.json#properties"}]

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 for the document

ITEMS

{"$ref"=>"./line_items.json#properties"}

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[created_at_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 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
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, 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

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

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?sort_by=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", "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

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

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.

Links

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?filter[from]=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
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 comments/{id} destroy

PUT comments/{id} update

POST comments 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?per_page=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 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
filter[related_object_type]	string (date)	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

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 company currency(eg. EUR) to the document currency(USD). The rate is set on document open with the exchange rate based on the document date. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday).

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_raw

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.

due_date string (date)

Auto-calculated from date + due days if empty and the document is opened.

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

Items for the document. Access items of all types including divider and sub_total items. Item creation is currently only supported through line_items array.

DEFAULT

any

ITEMS

[{"$ref"=>"./line_item.json#properties"}, {"$ref"=>"./divider_item.json#properties"}, {"$ref"=>"./sub_total_item.json#properties"}]

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]

Line items for the document

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?sort_by=Value&filter[contact_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[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
filter[to]	string (date)	Objects with date before the date
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 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. If the source is an Estimate or Order only line_items, contact & tags are copied.
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}/print print

URL Params

/api/invoices/{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(any val) the new pdf is returned inside the attachment JSON within 'base64' key. Ommit to save traffic.

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

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

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

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

IDENTITY

true

in_progress boolean

Is set after an email has been scheduled for sending until it has been sent.

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

bcc_addr string (text)

BCC addresses, comma separated. Max 5, format: a@b.de,'George'

* body 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 string 22

uuid of the emails parent object.

* related_object_type string

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

* subject string ≤ 255

The email subject.

team_id string 22

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

* to_addr string (text)

TO addresses, comma separated. Max 5, format: a@b.de,'George'

Links

GET emails/{id} self

GET emails instances

URL Params

/api/emails?per_page=Value&filter[draft]=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 body and subject
filter[sent]		Show only sent emails
filter[draft]		Show only draft emails
filter[address]		Searches in all address fields: bcc, cc, to, from
filter[from]	string (date)	All objects updated on/after the date
filter[to]	string (date)	All objects updated on/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

GET emails/{id}/attachments attachments

DELETE emails/{id} destroy

PUT emails/{id} update

POST emails create

URL Params

/api/emails?send=Value&archived_pdf=Value

Name	Type	Description / Example
template_id	string	UUID of an email template to use. If present, subject, body and attachments of the template 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).

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

Email template

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

* body string (text)

Body with placeholders, replaced when the template is used.

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

Payment

An payment in SK must always be related to an document.

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 company currency(eg. EUR) to the document currency(USD). The rate is set on document open with the exchange rate based on the document date. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday).

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.

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

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.

* related_object_type string

Object type of the payments parent. Is the camel-cased base class name: Document for invoice, credit_note

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?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[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) [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

URL Params

/api/payments?late_fee=Value

Name	Type	Description / Example
late_fee	number	If an invoice has payment reminders with a late fee, add the late fee here if it was paid. We create a second payment for the last reminder and close it.

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 company currency(eg. EUR) to the document currency(USD). The rate is set on document open with the exchange rate based on the document date. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday).

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.

due_date string (date)

Auto-calculated from date + due days if empty and the document is opened.

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.

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]

Line items for the document

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_to]=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[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
filter[to]	date	Objects with date before and on 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	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?cancel=Value&source=Value

Name	Type	Description / Example
source		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.
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}/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.

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?page=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
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

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

Payment reminder

A payment reminder

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 company currency(eg. EUR) to the document currency(USD). The rate is set on document open with the exchange rate based on the document date. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday).

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.

due_date string (date)

Auto-calculated from date + due days if empty and the payment_reminder is opened.

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.

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]

Line items for the document. Defaults to invoice.gross_total and late fee values from settings

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

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[q]=Value&filter[contact_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[tags]	string	Filter by a space delimited list of tags
filter[from]	string (date)	All objects with a date after the date
filter[to]	string (date)	All objects with date before the date
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
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}/print print

URL Params

/api/payment_reminders/{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.

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

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

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.

Valid Values

work, home, parcel

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

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

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

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

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 company currency(eg. EUR) to the document currency(USD). The rate is set on document open with the exchange rate based on the document date. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday).

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.

due_date string (date)

Auto-calculated from date + due days if empty and the estimate is opened.

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.

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]

Line items for the document

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?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
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
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, 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. 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}/print print

URL Params

/api/estimates/{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)

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?page=Value&filter[created_at_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	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.
filter[birthday_to]	string (date)	Contacts with a birthday date before and on the date.
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

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.

Links

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.

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.

due_days integer

Used to calculate the due date of the recurring. Useless if date and due date are present.

external_ref string ≤ 255

Some external reference, whatever this may be.

* final_date string (date)

The last date the recurring is executed.

* frequency string (enum)

Recurring frequency

Valid Values

yearly, monthly, weekly, quarterly, biweekly, sixmonthly

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]

Line items for the document

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

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?filter[from]=Value&filter[contact_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[tags]	string	Filter by a space delimited list of tags
filter[from]	string (date)	Objects with a date after the date
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. Fields passed with the object(e.g. notes, title, address_field) are not overwritten.

GET recurrings/{id}/attachments attachments

GET recurrings/{id}/comments comments

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

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 company currency(eg. EUR) to the document currency(USD). The rate is set on document open with the exchange rate based on the document date. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday).

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.

due_date string (date)

Auto-calculated from date + due days if empty and the document is opened.

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.

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]

Line items for the document

See