SalesKing API Browser JSON Schema Browser

contact object (Contact)

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

See

cost_total number

Cost total of all line items, 2 decimals places in document currency.

created_at string (date-time)

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

gross_margin_pct number

Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100

gross_margin_total number

Total gross margin across all line items. Calculated from net_total-cost_total.

gross_total number

Gross total of all line items, 2 decimals places

id string 22

Unique identifier - UUID

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

team_id string 22

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

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

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.

sepa_debit_sequence_type string (enum)

SEPA direct debit sequence type. Check with you bank how they handle FRST(first) and FNAL(final) types. When exporting SEPA debit to your bank the type defaults to OOF if blank.

Valid Values

FRST, OOFF, RCUR, FNAL

sepa_mandate_id string ≤ 35

SEPA mandate identifier needed in direct debit transactions. This is a unique id given by you to the customer beforehand.

sepa_mandate_signed_at string (date)

Date the SEPA mandate was signed by your customer. Must not be in the future!

tag_list string

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

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&filter[languages]=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 50, max is 200
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 on/after the date(>=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the start of the day(00:00:00) so all objects created on this day are included. A time should be already utc time
filter[created_at_to]	string (date-time)	Objects with a creation until the date(<=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the end of the day(23:59:59) so all objects created on that day are included. A time should be already utc time.
filter[languages]	string	A list of language codes, comma separated
filter[client_ids]	string	DEPRECATED use contact_ids
filter[contact_ids]	string	Find objects belonging to a single or a list of contacts, use ids 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[product_ids]	string	Documents using the given product uuids(comma separated) in their line items.
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

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

team_id string 22

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

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

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.

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[tags]=Value&filter[client_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 50, max is 200
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	Find objects belonging to a single or a list of contacts, use ids 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&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 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.

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?per_page=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 50, max is 200
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

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.

log text

Logs error message when sending failed.

team_id string 22

A team uuid taken from the related object. If set only the team and its parent teams can see the record.

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

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.

* 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?filter[q]=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 50, max is 200
filter[q]	string	Search in body and subject
filter[status]	(enum) [draft, sent, in_progress]	Show only sent, draft or emails in progress. The status is virtual and checks the delivered_at and in_progress field values.
filter[address]		Searches in all address fields: bcc, cc, to, from
filter[from]	string (date)	All objects updated on/after the date. YYYY-MM-DD
filter[to]	string (date)	All objects updated on/before the date. YYYY-MM-DD
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

GET emails/{id}/attachments attachments

DELETE emails/{id} destroy

PUT emails/{id} update

POST emails create

URL Params

/api/emails?archived_pdf=Value&template_id=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).

Account

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

Readonly Properties

balance number

The account balance is the sum of all entries, also those from sub-accounts.

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

creator_id string 22

The user uuid who created the record.

id string 22

Unique identifier - UUID

IDENTITY

true

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

budget number

If an account is used to track budgetary things f.ex. projects, this fields can be used to perform calculations like: Are we still inside the allowed budget?

contact_id string 22

The contacts uuid to which the account is related.

default_price number

The default price single for new account entries. Is only used if price single is left empty on create.

default_unit string ≤ 30

The default quantity unit for new account entries. Is only used if unit is left empty on create.

description string (text) ≤ 255

Account description

document_id string 22

Document uuid, related to the account.

hide_fields string ≤ 255

A list of account entry field names. The fields are hidden on account entry lists and forms so one can focus on the important inputs. For example hide: tax,description,billed_at

* name string ≤ 100

The name of the account

number string ≤ 50

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

team_id string 22

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

Links

GET accounts/{id} self

GET accounts instances

URL Params

/api/accounts?filter[q]=Value&page=Value

Name	Type	Description / Example
filter[q]	string	Wildcard search in number, name, description
filter[number]	string	Search by exact number
filter[balance_from]	number	Find account with a balance greater(>=) than given number.
filter[balance_to]	number	Find accounts with a balance smaller(<=) than given number.
filter[contact_ids]	string	Find objects belonging to a single or a list of contacts, use ids comma separated.
filter[parent_id]	string	Search children of the given account.
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 50, max is 200
sort_by	string (enum) [name, number, balance, 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 accounts/{id} destroy

PUT accounts/{id} update

POST accounts create

GET accounts/{id}/account_entries account_entries

GET accounts/{id}/account_billings account_billings

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&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 50, max is 200
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

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

team_id string 22

A team uuid taken from the related object. If set only the team and its parent teams can see the record.

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

* 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

* text string

The comment himself.

Links

GET comments/{id} self

GET comments instances

URL Params

/api/comments?filter[q]=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 50, max is 200
filter[q]	string	Search in text
filter[contact_ids]	string	Comma-separated list of contact IDs. While present, it will return comments related to the contact and all its documents.
filter[related_object_ids]	string	Comma-separated list of related object IDs (objects which can have their own comments: document, task, products). Can also be used with a single ID to find all comments related to the given object.
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

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

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&filter[related_object_type]=Value

Name	Type	Description / Example
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 50, max is 200
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

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

team_id string 22

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

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

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.

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[ids]=Value&filter[client_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 50, max is 200
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 on/after the date(>=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the start of the day(00:00:00) so all objects created on this day are included. A time should be already utc time
filter[created_at_to]	string (date-time)	Objects with a creation until the date(<=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the end of the day(23:59:59) so all objects created on that day are included. A time should be already utc time.
filter[languages]	string	A list of language codes, comma separated
filter[client_ids]	string	DEPRECATED use contact_ids
filter[contact_ids]	string	Find objects belonging to a single or a list of contacts, use ids 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

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

cost_total number

Cost total of all line items, 2 decimals places in document currency.

created_at string (date-time)

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

estimate_id string 22

Estimate document ID, if the order was created from a estimate.

exchange_rate number

The exchange rate from the foreign document currency(eg. USD) to the company currency(EUR). If the rate is empty we use the exchange rate on the document date or today if doc.date is empty. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday). If you open the doc at a later time make sure to manually refresh the rate, as we dont change it.

gross_margin_pct number

Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100

gross_margin_total number

Total gross margin across all line items. Calculated from net_total-cost_total.

gross_total number

Gross total of all line items, 2 decimals places in document currency.

gross_total_exchanged number

Exchanged gross total, in your company currency.

id string 22

Unique identifier - UUID

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

team_id string 22

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

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

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.

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[tags]=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 50, max is 200
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 on/after the date(>=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the start of the day(00:00:00) so all objects created on this day are included. A time should be already utc time
filter[created_at_to]	string (date-time)	Objects with a creation until the date(<=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the end of the day(23:59:59) so all objects created on that day are included. A time should be already utc time.
filter[languages]	string	A list of language codes, comma separated
filter[client_ids]	string	DEPRECATED use contact_ids
filter[contact_ids]	string	Find objects belonging to a single or a list of contacts, use ids 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[product_ids]	string	Documents using the given product uuids(comma separated) in their line items.
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&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 orders/{id}/print print

URL Params

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

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

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 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?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 50, max is 200
filter[q]	["string", "number"]	Wildcard search in number, name, description, price
filter[contact_ids]	string	Comma-separated list of contact IDs. While present, it will return payments related to all contacts' documents.
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

Contact

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

Readonly Properties

address_field string

Returns the address field used on new docs. Consist of Organisation name and default(first) address

created_at string (date-time)

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

expected_revenue number

Product of the probability and sales potential. e.g how much of the sales_potential can we get?

id string 22

Unique identifier - UUID

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.

converted_at string (date-time)

Date the contact converted from lead to client or any other contact type (supplier)

currency string 3

Currency code as defined by the ISO 4217 standard(3-letter UPCASE: EUR, USD). If set the currency is taken for new documents.

due_days integer

Default due days for new 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

is_employee boolean

An employee gets number, organisation, tax and vat_number from its parent. If you set any of these, they are overwritten. When changing a parent-contact the fields on his direct child-employees are updated too.

DEFAULT

false

language string ≤ 10

Should be a valid language short-code: de-DE, fr, en-GB; like defined in your account language menu. When the client is emailed, a localized version of a multi-language template(email, pdf) will be used if available. The language will also be set for new documents.

last_name string ≤ 50

Last name of a person. At least this or the organisation field must be filled for new records

lead_date string (date)

Lead date e.g. date of first contact with your company. YYYY-MM-DD

lead_ref text

Lead reference e.g. a tracking id, web-url

lead_source text

Lead source describing where a contact came from e.g. a campaign name, website, facebook, URL

lock_version integer

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

notes string (text)

Notes for a contact. For day to day information you should use comments instead.

number string ≤ 50

Unique number, auto-created by SK for new contacts(client, supplier) without number.

* organisation string ≤ 100

Name of a company. This or lastname must be present

parent_id string 22

ID of a parent contact.

payment_method string (enum)

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.

probability number

Likelihood that the sales potential will be realised in percent e.g. How hot is the contact, How much of the sales potential will we get also see expected_revenue?

sales_potential number

Sales potential for the contact e.g what is his budget, how much can he spend?

tag_list string

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

tax_number string ≤ 30

Tax number, normally applies to a private person

team_id string 22

A team uuid. If set only the team and its parent teams can see the record. The team is set for all new documents and related objects like comments, attachments, emails. When changed ALL related objects are updated with the new team!!

title string ≤ 50

Academical title of a person e.g. Dr., Prof

* type string (enum) ≤ 50

Type of contact

Valid Values

Client, Lead, Supplier

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 contacts/{id} self

GET contacts instances

URL Params

/api/contacts?filter[ids]=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 50, max is 200
filter[q]	string	Wildcard search in first, last_name, organisation, email, number
filter[organisation]	string	Search by organisation. Searches by organisation begins with name%
filter[tags]	string	Filter by a space delimited list of tags
filter[ids]	string	A single or a list of contacts uuids, comma separated
filter[created_at_from]	string (date-time)	Objects with a creation on/after the date(>=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the start of the day(00:00:00) so all objects created on this day are included. A time should be already utc time
filter[created_at_to]	string (date-time)	Objects with a creation until the date(<=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the end of the day(23:59:59) so all objects created on that day are included. A time should be already utc time.
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
filter[type]	string (enum) [Client, Lead, Supplier]	Type of the contact:
filter[probability_from]	number	Find contacts with a probability greater(>=) than given number. Minimum is 0 for percent fields, max 100
filter[probability_to]		Find contacts with a probability smaller(<=) than given number.
filter[sales_potential_from]	number	Find contacts with a sales potential greater(>=) than given number.
filter[sales_potential_to]		Find contacts with a sales potential smaller(<=) than given number.
sort_by	string (enum) [organisation, number, email, first_name, last_name, 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 contacts/{id} destroy

PUT contacts/{id} update

POST contacts create

GET contacts/{id}/documents documents

GET contacts/{id}/attachments attachments

GET contacts/{id}/invoices invoices

GET contacts/{id}/estimates estimates

GET contacts/{id}/orders orders

GET contacts/{id}/credit_notes credit_notes

GET contacts/{id}/recurrings recurrings

GET contacts/{id}/payment_reminders payment_reminders

GET contacts/{id}/comments comments

GET contacts/{id}/emails emails

POST contacts/{id}/emails emails create

URL Params

/api/contacts/{id}/emails?archived_pdf=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).

Export

An export in SK

Readonly Properties

attachments array [Attachment]

The exported data as attachment.

See

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. SEPA: bank exports, relies on valid bank information in your company, the exported document and the contact.

Valid Values

text, archived_pdf, attachments, allinone_pdf, sepa_debit, sepa_credit

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?filter[to]=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 50, max is 200
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

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

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&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 50, max is 200
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

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

Account entry

A entry for an account

Readonly Properties

created_at string (date-time)

Date the object was created. Never changes afterwards

document_id string 22

Document the entry is related to. This relation is set by an account billing.

id string 22

Unique identifier - UUID

IDENTITY

true

item_id string 22

Line item on the document the entry is related to. This relation is set by an account billing or when a document is booked onto an account.

net_total number

Net price of a single entry. Calculated from price_single * quantity

updated_at string (date-time)

Date the object was edited.

Writable Properties

_destroy boolean

When set an existing entry will be deleted. This switch is used for entries passed during batch operations.

* account_id string 22

Account the entry belongs to.

billable boolean

True if the entry can be billed.

DEFAULT

false

billed_at string (date-time)

Date the object was billed. Automatically set when the entry is used on an invoice.

date string (date-time)

Date of the entry. Defaults to today. Entries are sorted by date per default.

description string (text)

Entry description

name string ≤ 50

The name of an entry

* price_single number

Net price of a single entry. If a product id is given, price_single is taken from the product if not set.

quantity number

Quantity of the entry.

DEFAULT

1

quantity_unit string ≤ 30

Quantity unit e.g: kg, days, month, ..

tax number

Tax percentage

Links

GET account_entries/{id} self

GET account_entries instances

URL Params

/api/account_entries?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 50, max is 200
filter[q]	string	Wildcard search in name, description
filter[account_ids]	string	Set multiple account ids comma separated or as array
filter[document_ids]	string	Set multiple document ids comma separated or as array
filter[ids]	string	Set multiple entry ids comma separated or as array
filter[unbilled]	boolean	Entries available for billing: marked as billable without a billing date(billed_at) set. False values will skip this filter. To find billed entries simply use filter[billed_at_to] e.g with todays date.
filter[billable]	boolean	Billable or not billable entries. Set false(string) or 0(Integer) to get not billable entries. For billable entries use true or 1. Also see filter[unbilled] to find not yet billed entries.
filter[date_from]	string (date)	Objects with a date eq/after the date. YYYY-MM-DD
filter[date_to]	string (date)	Objects with date eq/before the date. YYYY-MM-DD
filter[billed_at_from]	string (date)	Objects with a billing date eq/after the date. YYYY-MM-DD
filter[billed_at_to]	string (date)	Objects with billing date eq/before the date. YYYY-MM-DD. A set billing date means the entry has been billed, so simply use this filter e.g with date today to find all billed entries.
filter[created_at_from]	string (date)	Objects with a date eq/after the date. YYYY-MM-DD
filter[created_at_to]	string (date)	Objects with a creation until the date(<=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the end of the day(23:59:59) so all objects created on that day are included. A time should be already utc time.
sort_by	string (enum) [name, number, date, quantity, price_single, 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 account_entries/{id} destroy

PUT account_entries/{id} update

POST account_entries create

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

cost_total number

Cost total of all line items, 2 decimals places in document currency.

created_at string (date-time)

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

exchange_rate number

The exchange rate from the foreign document currency(eg. USD) to the company currency(EUR). If the rate is empty we use the exchange rate on the document date or today if doc.date is empty. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday). If you open the doc at a later time make sure to manually refresh the rate, as we dont change it.

expected_revenue number

Product of the probability and net total. In company currency

gross_margin_pct number

Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100

gross_margin_total number

Total gross margin across all line items. Calculated from net_total-cost_total.

gross_total number

Gross total of all line items, 2 decimals places in document currency.

gross_total_exchanged number

Exchanged gross total, in your company currency.

id string 22

Unique identifier - UUID

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

team_id string 22

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

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

address_field string

Receiver address, normally shown in envelope window. Defaults to client address_field if empty and client_id present.

client_id string 22

DEPRECATED: use contact_id

close_date number

Date when the deal is expected to be closed.

contact_id string 22

The contact uuid. When assigning a contact its language, currency, address_field (due days, cash discount) values are used for the document if those doc-fields are not set.

currency string 3

Currency code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)

date string (date)

Date the estimate is issued. Automatically set when estimate is opened. Required for non-draft documents. YYYY-MM-DD

due_date string (date)

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

due_days integer

Used to calculate the valid-until date of the estimate. Useless if date and due date are present.

external_ref string ≤ 255

Some external reference, whatever this may be.

items array [Line item | Divider item | Sub total item] ≥ 0

Items for the document. Access items of all types including divider and sub_total items. GOTCHAs when using items instead of line_items: You MUST set the type field(CamelCasesItem class name) on each item. You cannot use both, the line_items array is stronger for backward compat.

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.

probability number

Percentage of estimated confidence in closing the deal. Estimated Probability percentage of the net total amount

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.

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[contact_ids]=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 50, max is 200
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[probability_from]	number	Find documents with a probability greater(>=) than given number. Minimum is 0 for percent fields, max 100
filter[probability_to]	number	Find accounts with a probability smaller(<=) than given number.
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[close_date_from]	string (date)	Objects with a closing date after the date. YYYY-MM-DD
filter[close_date_to]	string (date)	Objects with closing date before the date. YYYY-MM-DD
filter[created_at_from]	string (date-time)	Objects with a creation on/after the date(>=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the start of the day(00:00:00) so all objects created on this day are included. A time should be already utc time
filter[created_at_to]	string (date-time)	Objects with a creation until the date(<=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the end of the day(23:59:59) so all objects created on that day are included. A time should be already utc time.
filter[updated_at_from]	string (date-time)	Objects updated on/after the date(>=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the start of the day(00:00:00) so all objects updated on this day are included. A time should be already utc time
filter[updated_at_to]	string (date-time)	Objects updated until the date(<=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the end of the day(23:59:59) so all objects updated on that day are included. A time should be already utc time.
filter[languages]	string	A list of language codes, comma separated
filter[client_ids]	string	DEPRECATED use contact_ids
filter[contact_ids]	string	Find objects belonging to a single or a list of contacts, use ids 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[product_ids]	string	Documents using the given product uuids(comma separated) in their line items.
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?archived_pdf=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 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.

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&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 50, max is 200
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

Account billing

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

Readonly Properties

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

creator_id string 22

User who created the record.

document_id string 22

The document created by the billing.

id string 22

Unique identifier - UUID

IDENTITY

true

Writable Properties

* account_id string 22

The related account. Must be set for entries to be found.

document_type string (enum)

The document type to create. CamelCase document class name. Invoice by default

DEFAULT

Invoice

Valid Values

Invoice, CreditNote, Order, Estimate

group_entries_by string (enum)

Group multiple account entries into single line items, when creating a billing+document from entries. Account entries MUST have the SAME price_single and quantity unit, to land in a group. Date base groups also require the SAME entry name.

Valid Values

name, day, week, month, year

name string ≤ 100

A note for the billing e.g. happyPDF usage April 2014. The field is wildcard searchable

set_billed_at boolean

Set billed at date for related account entries.

DEFAULT

false

team_id string 22

A team uuid. Is inferred from the accounts team id.

Links

GET account_billings/{id} self

GET account_billings instances

URL Params

/api/account_billings?filter[account_ids]=Value&sort=Value

Name	Type	Description / Example
filter[q]	string	Wildcard search in name
filter[account_ids]	string	Find objects belonging to a single or a list of accounts, use ids comma separated.
filter[created_at_from]	string (date)	Objects with a date eq/after the date. YYYY-MM-DD
filter[created_at_to]	string (date)	Objects with a creation until the date(<=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the end of the day(23:59:59) so all objects created on that day are included. A time should be already utc time.
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 50, max is 200
sort_by	string (enum) [name, number, balance, 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 account_billings/{id} destroy

POST account_billings create

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

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?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 50, max is 200
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

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?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 50, max is 200
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

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[birthday_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 50, max is 200
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 on/after the date(>=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the start of the day(00:00:00) so all objects created on this day are included. A time should be already utc time
filter[created_at_to]	string (date-time)	Objects with a creation until the date(<=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the end of the day(23:59:59) so all objects created on that day are included. A time should be already utc time.
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

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&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 50, max is 200
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

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

cost_total number

Cost total of all line items, 2 decimals places in document currency.

created_at string (date-time)

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

exchange_rate number

The exchange rate from the foreign document currency(eg. USD) to the company currency(EUR). If the rate is empty we use the exchange rate on the document date or today if doc.date is empty. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday). If you open the doc at a later time make sure to manually refresh the rate, as we dont change it.

gross_margin_pct number

Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100

gross_margin_total number

Total gross margin across all line items. Calculated from net_total-cost_total.

gross_total number

Gross total of all line items, 2 decimals places in document currency.

gross_total_exchanged number

Exchanged gross total, in your company currency.

id string 22

Unique identifier - UUID

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

team_id string 22

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

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

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

sepa_debit_sequence_type string (enum)

SEPA direct debit sequence type. Check with you bank how they handle FRST(first) and FNAL(final) types. When exporting SEPA debit to your bank the type defaults to OOF if blank.

Valid Values

FRST, OOFF, RCUR, FNAL

sepa_mandate_id string ≤ 35

SEPA mandate identifier needed in direct debit transactions. This is a unique id given by you to the customer beforehand.

sepa_mandate_signed_at string (date)

Date the SEPA mandate was signed by your customer. Must not be in the future!

status string (enum)

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.

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[product_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 50, max is 200
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	Find objects belonging to a single or a list of contacts, use ids 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
filter[product_ids]	string	Documents using the given product uuids(comma separated) in their line items.
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&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 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.

Task

An Task in SK.

Readonly Properties

attachments array [Attachment]

Attached files, uploads.

See

closed_at string (date)

Date the task was completed.

contact object (Contact)

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

See

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

assignee_id string 22

User who should do the tasks.

contact_id string 22

Related contact of the tasks.

creator_id string 22

User who created the tasks.

* description string

Notes, explanations for the task.

documents array [Document]

A tasks can have many related documents.

See

Document

* name string

The task title.

status string (enum)

New tasks are open by default, unless otherwise stated.

DEFAULT

open

Valid Values

open, closed, overdue

Links

GET tasks/{id} self

GET tasks instances

URL Params

/api/tasks?filter[due_at_to]=Value&filter[creator_ids]=Value

Name	Type	Description / Example
filter[q]	string	Search in name, description
filter[status]	string	A single or a list of status, comma separated: open,closed,overdue
filter[ids]	string	Only find tasks with given ids. Comma-separated list of task IDs.
filter[contact_ids]	string	Tasks related to given contacts. Comma-separated list of contact IDs.
filter[creator_ids]	string	Tasks created by given users. Comma-separated list of user IDs.
filter[assignee_ids]	string	Tasks assigned to given users. Comma-separated list of user IDs.
filter[due_at_from]	string (date)	Tasks due after the date(>=). YYYY-MM-DD
filter[due_at_to]	string (date)	Tasks due before the date(<=). YYYY-MM-DD
filter[closed_at_from]	string (date)	Tasks closed after the date(>=). YYYY-MM-DD
filter[closed_at_to]	string (date)	Tasks closed before the date(<=). YYYY-MM-DD
filter[updated_at_from]	string (date)	Tasks updated after the date(>=). YYYY-MM-DD
filter[updated_at_to]	string (date)	Tasks updated before the date(<=). YYYY-MM-DD
filter[created_at_from]	string (date)	Tasks created after the date(>=). YYYY-MM-DD
filter[created_at_to]	string (date)	Tasks created before the date(<=). YYYY-MM-DD
page	number	In paginated results set the page to look for
per_page	number	Results per page. Default is 50, max is 200
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 tasks/{id} destroy

PUT tasks/{id} update

POST tasks create

URL Params

/api/tasks?source=Value&template_id=Value

Name	Type	Description / Example
template_id	string	Task template(id) to use. If set template fields like name, description, attachments are used for the new task.
document_id	string	If set: the document, its contact and due date are used for the task. Dont forget to set a task.name though. Useful if you want to create a reminder when the document is due e.g call contact.
source	string	Uses name, description, contact, documents from given given source task.

Line item

A line item for a document

Readonly Properties

cost_total number

Total costs. Calculated from cost_single * quantity

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

gross_margin_pct number

Gross margin percentage. Calculated from gross_margin_total/cost_total

gross_margin_total number

Gross margin, the difference between revenue and cost before accounting for certain other costs. Calculated from net_total - cost_total

gross_total number

Gross price. Net total with taxes applied.

id string 22

Unique identifier - UUID

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.

cost number

Cost price for a single item. Used to calculate the gross margin

description string (text)

Item description

discount number

Discount in percent applied to the items net total. Can also be negative if you want to add additional charges.

external_ref string ≤ 255

Arbitrary number e.g. external product reference.

name string ≤ 50

The name of an item

position integer

Position by which the items are sorted. Two items can have the same position(if you dont care) and numbers dont need to continuous

DEFAULT

1

* price_single number

Net price of a single item. If a product id is given, price_single is taken from the product if not set.

product_from_line_item boolean

Saves and associates an instance of a Product from LineItem fields (name, description, quantity, unit, price, cost price), if no Product association is found. Accepted values to trigger this behaviour: 1, true

DEFAULT

false

product_id string 22

A uuid of a product, used by this item. If set or changed, the product fields (name, description, quantity, unit, price, cost price) are copied if the according item fields are missing/blank. Besides this product link makes it possible to track a products turnover and find the documents it is used on.

quantity number ≥ 0

Quantity of the item. Must be >= 0

DEFAULT

1

quantity_unit string ≤ 30

Quantity unit: kg, days, month.

tax number

Tax percent for a single item.

type string ≤ 20

The item type: LineItem. Must be set when creating new items via document.items array

Links

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

cost_total number

Cost total of all line items, 2 decimals places in document currency.

created_at string (date-time)

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

exchange_rate number

The exchange rate from the foreign document currency(eg. USD) to the company currency(EUR). If the rate is empty we use the exchange rate on the document date or today if doc.date is empty. If there is no rate for this day, say on weekends, the closest previous day is taken(Sunday->Friday). If you open the doc at a later time make sure to manually refresh the rate, as we dont change it.

gross_margin_pct number

Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100

gross_margin_total number

Total gross margin across all line items. Calculated from net_total-cost_total.

gross_total number

Gross total of all line items, 2 decimals places in document currency.

gross_total_exchanged number

Exchanged gross total, in your company currency.

id string 22

Unique identifier - UUID

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

team_id string 22

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

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

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