SalesKing API-Browser
  • Quick View
  • Table View
  • Changelog
  • Raw Schema

Objects

  • documents
  • Credit note
  • Divider item
  • Document
  • Estimate
  • Invoice
  • Line item
  • Order
  • Payment reminder
  • Recurring
  • Sub total item
  • contacts
  • Address
  • Contact
  • templates
  • Email template
  • Export template
  • Pdf template
  • Text template
  • system
  • Auth permission
  • Company
  • Language
  • Sub
  • User
  • supportive
  • Attachment
  • Comment
  • Email
  • Export
  • Payment
  • Product
  • Tag
  • Task
  • accounting
  • Account
  • Account billing
  • Account entry

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?filter[q]=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)
[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

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

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?per_page=Value&sort=Value
Name Type Description / Example
page number

In paginated results set the page to look for

per_page number

Results per page. Default is 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

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

Attachment

client object (Client)

DEPRECATED: use contact

See

Client

contact object (Contact)

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

See

Contact

cost_total number

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

created_at string (date-time)

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

exchange_rate number

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

expected_revenue number

Product of the probability and net total. In company currency

gross_margin_pct number

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

gross_margin_total number

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

gross_total number

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

gross_total_exchanged number

Exchanged gross total, in your company currency.

id string 22

Unique identifier - UUID

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

Line item Divider item Sub total item

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

Line item

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[updated_at_from]=Value&filter[number]=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?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 estimates/{id}/print print
URL Params
/api/estimates/{id}/print?template_id=Value&base64=Value
Name Type Description / Example
template_id *

UUID of a pdf template used to print the document. MUST be present

base64

If set the new pdf is returned inside the attachment JSON within 'base64' key. Leave empty to save traffic.

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. Max 6 decimal places.

description string (text)

Item description

discount number

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

external_ref string ≤ 255

Arbitrary number e.g. external product reference.

name string ≤ 50

The name of an item

position integer

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

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. Max 6 decimal places.

product_from_line_item boolean

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

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. Max 6 decimal places.

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

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

Attachment

client object (Client)

DEPRECATED: use contact

See

Client

contact object (Contact)

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

See

Contact

cost_total number

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

created_at string (date-time)

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

exchange_rate number

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

gross_margin_pct number

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

gross_margin_total number

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

gross_total number

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

gross_total_exchanged number

Exchanged gross total, in your company currency.

id string 22

Unique identifier - UUID

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

Line item Divider item Sub total item

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

Line item

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.

tax_exemption_id string 22

ID of a tax exemption. When set all item taxes are omitted.

title string ≤ 255

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

Links

GET invoices/{id} self
GET invoices instances
URL Params
/api/invoices?filter[status]=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[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?cancel=Value&source=Value
Name Type Description / Example
source string

Copies the source(excl. number,date) and returns a new draft document. Fields passed with the object(e.g. notes, title, address_field) are not overwritten. When copying a different document type e.g. creating an invoice from an order(pass an order ID), ONLY the items, contact, currency and tag list are taken from the source doc.

cancel boolean - Depends on: source

Cancelling a document copies the source and negates all line item values. A source id MUST be set.

GET invoices/{id}/attachments attachments
GET invoices/{id}/payments payments
GET invoices/{id}/payment_reminders payment_reminders
GET invoices/{id}/comments comments
GET invoices/{id}/emails emails
POST invoices/{id}/emails emails create
URL Params
/api/invoices/{id}/emails?send=Value&archived_pdf=Value
Name Type Description / Example
template_id string

UUID of an email template to use. If present template fields like subject, body, attachments are used for the current email.

send

Schedule email for sending. Omit this parameter or set value to 0 or false(String or Integer) to keep email as draft.

archived_pdf

Adds the archived pdf from the related resource(if it has one).

POST invoices/{id}/payments payment create
POST invoices/{id}/print print
URL Params
/api/invoices/{id}/print?base64=Value&template_id=Value
Name Type Description / Example
template_id *

UUID of a pdf template used to print the document. MUST be present

base64

If set(any val) the new pdf is returned inside the attachment JSON within 'base64' key. Ommit to save traffic.

Payment

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

Readonly Properties

amount_exchanged number

The exchanged amount.

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

exchange_rate number

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

id string 22

Unique identifier - UUID

IDENTITY

true

team_id string 22

A team uuid taken from the related object(e.g.invoice). If set only the team and its parent teams can see the record.

Writable Properties

* amount number

The payment amount

cash_discount number

The cash discount amount. If a client withdraws a cash discount say 2% of 100€, he pays 98€ used in amount and 2€ in cash_discount. Handled separate for correction of sales,vat accounts in bookkeeping.

currency string 3

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

* date string (date)

Date the payment was made. YYYY-MM-DD

external_ref string ≤ 255

Reference number f.ex. issued by the bank.

is_partial boolean

If set the related document is NOT closed.

DEFAULT

false

late_fee number

Add a late fee if an invoice has payment reminders. We create a second payment for the last reminder and close all others. Set to 0, if you want to waive the fee(has not been paid). In this case all reminders are closed and we also correct the sales+debtor account with the open fees. This is a pure setter-method used in creation!

payment_method string (enum)

How the payment was made.

Valid Values

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

* related_object_id string 22

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

* related_object_type string

Object type of the payments parent. Is the camel-cased base class name: Document for invoice, credit_note. Is auto-set when using the nested URL POST invoices/ID/payments

Links

GET payments/{id} self
GET payments instances
URL Params
/api/payments?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

filter[q] string

Search in title, number, address field

filter[from] string (date)

All objects with a date after the date. YYYY-MM-DD

filter[to] string (date)

All objects with date before the date. YYYY-MM-DD

sort_by string (enum)
[amount, created_at, updated_at]

Sort the results by the given field => number

sort string (enum)
[ASC, DESC]

Sort the results in ASC or DESC

DELETE payments/{id} destroy
POST payments create

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

Line item Divider item Sub total item

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

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

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

Attachment

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[address]=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?template_id=Value&archived_pdf=Value
Name Type Description / Example
template_id string

UUID of an email template to use. If present, subject, body and attachments of the template are used for the current email.

send

Schedule email for sending. Omit this parameter or set value to 0 or false(String or Integer) to keep email as draft.

archived_pdf

Adds the archived pdf from the related resource(if it has one).

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

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

Sub

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

Readonly Properties

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 having the signed_request parameter containing an base64 encoded JSON object in the body.

* 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

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

Attachment

client object (Client)

DEPRECATED: use contact

See

Client

contact object (Contact)

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

See

Contact

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

Line item

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

Line item

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[to]=Value&filter[status]=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?template_id=Value&send=Value
Name Type Description / Example
template_id string

UUID of an email template to use. If present template fields like subject, body, attachments are used for the current email.

send

Schedule email for sending. Omit this parameter or set value to 0 or false(String or Integer) to keep email as draft.

archived_pdf

Adds the archived pdf from the related resource(if it has one).

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

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. Max 6 decimal places.

description string (text)

Product description

* 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. Max 6 decimal places.

quantity_unit string ≤ 30

Unit like kg, days, month.

tag_list string

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

tax number

Tax percentage for this product.

team_id string 22

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

Links

GET products/{id} self
GET products instances
URL Params
/api/products?filter[number]=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", "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

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?per_page=Value&filter[to]=Value
Name Type Description / Example
page number

In paginated results set the page to look for

per_page number

Results per page. Default is 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

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

Attachment

client object (Client)

DEPRECATED: use contact

See

Client

contact object (Contact)

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

See

Contact

cost_total number

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

created_at string (date-time)

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

exchange_rate number

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

gross_margin_pct number

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

gross_margin_total number

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

gross_total number

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

gross_total_exchanged number

Exchanged gross total, in your company currency.

id string 22

Unique identifier - UUID

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

Line item Divider item Sub total item

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

Line item

lock_version integer

Auto-incremented to prevent concurrent updates. First save wins.

notes_after string (text)

Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.

notes_before string (text)

Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used.

number string ≤ 50

Unique number assigned by SK credit note number schema. Auto-assigned when document is opened. Required unless doc status is draft.

payment_method string (enum)

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

Valid Values

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

status string (enum)

Defaults to draft for new documents, unless otherwise stated. For new documents with status 'open' or 'closed' or doc where the status changes away from draft, following fields are set if empty: number(next in number schema), date(today), due date(due_days must be given). Only draft documents can be deleted.

DEFAULT

draft

Valid Values

draft, open, closed

tag_list string

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

tax_exemption_id string 22

ID of a tax exemption. When set all item taxes are omitted.

title string ≤ 255

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

Links

GET credit_notes/{id} self
GET credit_notes instances
URL Params
/api/credit_notes?filter[q]=Value&filter[created_at_to]=Value
Name Type Description / Example
page number

In paginated results set the page to look for

per_page number

Results per page. Default is 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] date

Objects with a date on and after the date. YYYY-MM-DD

filter[to] date

Objects with date before and on the date. YYYY-MM-DD

filter[created_at_from] string (date-time)

Objects with a creation 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

A single or a list of client uuids, comma separated

filter[ids] string

A single or a list of document uuids, comma separated

filter[creator_ids] string

Objects created by the given users uuids, comma separated

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 credit_notes/{id} destroy
PUT credit_notes/{id} update
POST credit_notes create
URL Params
/api/credit_notes?source=Value&cancel=Value
Name Type Description / Example
source

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

cancel - Depends on: source

Cancelling a document negates its line item values. A source id must be set.

GET credit_notes/{id}/attachments attachments
GET credit_notes/{id}/payments payments
GET credit_notes/{id}/comments comments
GET credit_notes/{id}/emails emails
POST credit_notes/{id}/emails emails create
URL Params
/api/credit_notes/{id}/emails?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 invoices/{id}/payments payment create
POST credit_notes/{id}/print print
URL Params
/api/credit_notes/{id}/print?base64=Value&template_id=Value
Name Type Description / Example
template_id *

UUID of a pdf template used to print the document. MUST be present

base64

If set the new pdf is returned inside the attachment JSON within 'base64' key. Leave empty to save traffic.

Address

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

Readonly Properties

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

id string 22

Unique identifier - UUID

IDENTITY

true

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

_destroy boolean

When set an existing address will be deleted. This switch is only used when addresses are passed-in nested inside their parent object(a contact).

address1 string ≤ 100

Should contain the street or otherwise primary address information.

address2 string ≤ 100

Additional address information, like floor number

address_type string (enum)

Type of the address, as seen by vCard definition. There can only be one type. Inside of SK you can use placeholders like client.parcel_address.city to access the first parcel adr(Same for work_ / home_).
Besides the placeholder default_address, always returns the first address found. Sorting is done by the order(if set) else by date, newest first.

Valid Values

work, home, parcel

* city string ≤ 100

City for the address. Must at least be present for an address.

country string ≤ 100

Country of the address.

lat number

Geo-Location latitude

long number

Geo-Location longitude

order integer

Addresses are normally sorted by date, newest first. If you need to strongly rely on their sorting e.g. default_address (always first) or have multiple addresses of one type(3 parcel), use this field for all adrs.
Single adrs are used in placeholders like: addresses.2.city, returning the second adr found(not necessarily one with order=2).

pobox string ≤ 10

Post office box number

state string ≤ 100

Country state of address

zip string ≤ 10

Zip number of the city. Length must be between 4..10

Links

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&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)
[created_at, updated_at]

Sort the results by the given field => number

sort string (enum)
[ASC, DESC]

Sort the results in ASC or DESC

DELETE text_templates/{id} destroy
PUT text_templates/{id} update
POST text_templates create

Recurring

An recurring is used as an template for new invoices.

Readonly Properties

client object (Client)

DEPRECATED: use contact

See

Client

contact object (Contact)

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

See

Contact

cost_total number

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

created_at string (date-time)

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

gross_margin_pct number

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

gross_margin_total number

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

gross_total number

Gross total of all line items, 2 decimals places

id string 22

Unique identifier - UUID

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

Line item Divider item Sub total item

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

Line item

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.

tax_exemption_id string 22

ID of a tax exemption. When set all item taxes are omitted.

title string ≤ 255

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

Links

GET recurrings/{id} self
GET recurrings instances
URL Params
/api/recurrings?filter[created_at_from]=Value&filter[contact_ids]=Value
Name Type Description / Example
page number

In paginated results set the page to look for

per_page number

Results per page. Default is 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

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?sort_by=Value&filter[unbilled]=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

Export

An export in SK

Readonly Properties

attachments array [Attachment]

The exported data as attachment.

See

Attachment

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

finished_at string (date-time)

Date the was finished

id string 22

Unique identifier - UUID

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

Task

An Task in SK.

Readonly Properties

attachments array [Attachment]

Attached files, uploads.

See

Attachment

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

Contact

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?sort=Value&filter[status]=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?document_id=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.

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

Sort the results by the given field

sort string (enum)
[ASC, DESC]

Sort the results in ASC or DESC

filter[q] string

Searches in name, body, subject

filter[kind] string (enum)
[invoice, estimate, credit_note, payment_reminder, order, contact]

Kind of object this template can be used for

DELETE email_templates/{id} destroy
PUT email_templates/{id} update
POST email_templates create

Attachment

An file attachment

Readonly Properties

content_type string

Auto detected on upload. Might not always reflect the real content type

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

disk_filename string ≤ 255

Unique filename set by SK

filename string ≤ 255

The filename as set when uploaded

id string 22

uuid of the object.

IDENTITY

true

size integer

Filesize in kb. Auto detected on upload.

url string (uri)

DEPRECATED use attachments/ID/download

Writable Properties

is_signed boolean

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

* related_object_id string 22

uuid of the attachment parent object.

* related_object_type string

Object type of the attachment parent. A base class name: Document(for invoice, credit_note) Contact, Message(for email), Template(for email, pdf template)

team_id string 22

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

Links

GET attachments/{id} self
GET attachments/{id}/download download
GET attachments instances
URL Params
/api/attachments?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

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

Language

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

Readonly Properties

created_at string (date-time)

Date the object was created in SK. Never changes afterwards

id string 22

Unique identifier - UUID

IDENTITY

true

updated_at string (date-time)

Date the object was edited in SK.

Writable Properties

code string ≤ 10

Language short-code

* name string ≤ 30

The name of the language, shown in the interface

Links

GET languages/{id} self
GET languages instances
URL Params
/api/languages?sort=Value&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

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

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

Company

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

Readonly Properties

account_link string (uri)

Link to a company's SalesKing account.

created_at string (date-time)

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

id string 22

Unique identifier - UUID

IDENTITY

true

updated_at string (date-time)

Last date when the record was edited.

Writable Properties

addresses array [Addresses]

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

See

Addresses

bank_account_number string ≤ 35

Bank account number.

bank_iban string ≤ 35

IBAN Number of the bank account. Is validated

bank_name string ≤ 70

Bank name

bank_number string ≤ 35

Bank number

bank_owner string ≤ 70

Bank account owner

bank_swift string ≤ 11

SWIFT BIC- Bank Identifier Code

currency string 3

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

* email string ≤ 100

Email address

language string ≤ 10

Default language, used for new users. Must be a valid language available in SalesKing

name string ≤ 100

Company name

phone_fax string ≤ 30

Fax number

phone_mobile string ≤ 30

Mobile phone number

phone_office string ≤ 30

Office phone number

sepa_creditor_id string ≤ 18

SEPA Creditor ID, needed for SEPA direct debit transactions.

sub_domain string ≤ 20

Unique subdomain identifying the company's SalesKing account.

tax_number string ≤ 30

Tax number, normally applies to a private person running a small business.

time_zone string ≤ 50

Default time zone, used for new users

url string ≤ 255

A company website

vat_number string ≤ 30

VAT number, for a company entitled to pay value added taxes.

Links

GET companies/current current

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

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

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

Attachment

client object (Client)

DEPRECATED: use contact

See

Client

contact object (Contact)

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

See

Contact

cost_total number

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

created_at string (date-time)

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

estimate_id string 22

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

exchange_rate number

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

gross_margin_pct number

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

gross_margin_total number

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

gross_total number

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

gross_total_exchanged number

Exchanged gross total, in your company currency.

id string 22

Unique identifier - UUID

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

Line item Divider item Sub total item

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

Line item

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.

tax_exemption_id string 22

ID of a tax exemption. When set all item taxes are omitted.

title string ≤ 255

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

Links

GET orders/{id} self
GET orders instances
URL Params
/api/orders?filter[created_at_from]=Value&filter[to]=Value
Name Type Description / Example
page number

In paginated results set the page to look for

per_page number

Results per page. Default is 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?archived_pdf=Value&send=Value
Name Type Description / Example
template_id string

UUID of an email template to use. If present template fields like subject, body, attachments are used for the current email.

send

Schedule email for sending. Omit this parameter or set value to 0 or false(String or Integer) to keep email as draft.

archived_pdf

Adds the archived pdf from the related resource(if it has one).

POST orders/{id}/print print
URL Params
/api/orders/{id}/print?template_id=Value&base64=Value
Name Type Description / Example
template_id *

UUID of a pdf template used to print the document. MUST be present

base64

If set the new pdf is returned inside the attachment JSON within 'base64' key. Leave empty to save traffic.

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

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 string

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

lead_source string

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

lock_version integer

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

notes string (text)

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

number string ≤ 50

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

* organisation 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_exemption_id string 22

ID of a tax exemption. New documents inherit the tax exemption and will be created without any taxes.

tax_number string ≤ 30

Tax number, normally applies to a private person

team_id string 22

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

title string ≤ 50

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

* type 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?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).

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

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

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

billing_fee_name string ≤ 255

Name for a billing fee line item. The item is added to the resulting document upon each account_billing creation, if billing_fee_price_single is set.

billing_fee_price_single number

Price of a billing fee line item. This field serves as a trigger of whether to add the item. The item is added to the resulting document upon each account_billing creation.

billing_fee_tax number

Tax value for a billing fee line item. The item is added to the resulting document upon each account_billing creation.

budget number

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

contact_id string 22

The contacts uuid to which the account is related.

default_price number

The default price single for new account entries, if price single is empty on create. Max 6 decimal places.

default_unit string ≤ 30

The default quantity unit for new account entries, if unit is empty on create.

description string (text) ≤ 255

Account description

document_id string 22

Document uuid, related to the account.

hide_fields string ≤ 255

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

* name 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[balance_from]=Value&filter[parent_id]=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
API-Browser on github