Objects
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
Link to a company's SalesKing account.
Date the record was created in SK. Never changes afterwards.
Unique identifier - UUID
IDENTITYtrue
Last date when the record was edited.
Writable Properties
A company can have many addresses, sorted by date descending(new first). Default address used in placeholder is the most recent one.
SeeBank account number.
IBAN Number of the bank account. Is validated
Bank name
Bank number
Bank account owner
SWIFT BIC- Bank Identifier Code
Currency code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
Email address
Default language, used for new users. Must be a valid language available in SalesKing
Company name
Fax number
Mobile phone number
Office phone number
SEPA Creditor ID, needed for SEPA direct debit transactions.
Unique subdomain identifying the company's SalesKing account.
Tax number, normally applies to a private person running a small business.
Default time zone, used for new users
A company website
VAT number, for a company entitled to pay value added taxes.
Links
Address
An address in SK is maintained within it's parent object(client, company). The first address(default_address) is used inside the address field of new documents. With multiple addresses sorting(first) is done by date, newest first. So if you add a new adddress it will be the new default one. See order and type property for details about ordering and accessing parcel work or home addresses.
Readonly Properties
Date the object was created in SK. Never changes afterwards
Unique identifier - UUID
IDENTITYtrue
Date the object was edited in SK.
Writable Properties
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).
Should contain the street or otherwise primary address information.
Additional address information, like floor number
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.
work, home, parcel
City for the address. Must at least be present for an address.
Country of the address.
Geo-Location latitude
Geo-Location longitude
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).
Post office box number
Country state of address
Zip number of the city. Length must be between 4..10
Links
Credit note
A credit note
Readonly Properties
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.
SeeThe contact for the document. Use contact_id field to set a contact.
SeeCost total of all line items, 2 decimals places in document currency.
Date the object was created in SK. Never changes afterwards.
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.
Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100
Total gross margin across all line items. Calculated from net_total-cost_total.
Gross total of all line items, 2 decimals places in document currency.
Exchanged gross total, in your company currency.
Unique identifier - UUID
IDENTITYtrue
Net total, 2 decimals places
Net total, 6 decimal places incl. discount
DEPRECATED: use tax_total
DEPRECATED: use net_total_base
Tax total, 2 decimals places
A team uuid taken from the contact. If set only the team and its parent teams can see the record.
Date the object was edited in SK.
Writable Properties
Address field with the receiver. Shown in envelope window.
DEPRECATED: use contact_id
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 code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
Date the credit note is issued. Automatically set when document is opened. Required unless doc status is draft. YYYY-MM-DD
Auto-calculated from date + due days if empty and the document is opened. YYYY-MM-DD
Used to calculate the due date of the credit note. Useless if date and due date are present.
Some external reference, whatever this may be.
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.
DEFAULTany
SeeShould 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.
DEPRECATED use items
SeeAuto-incremented to prevent concurrent updates. First save wins.
Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.
Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used.
Unique number assigned by SK credit note number schema. Auto-assigned when document is opened. Required unless doc status is draft.
How the document is being payed. Used for new payments.
Valid Valuescash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms
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.
DEFAULTdraft
Valid Valuesdraft, open, closed
Space separated list of tags. Are split and saved as Tag objects on create, update.
ID of a tax exemption. When set all item taxes are omitted.
The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your credit note [number]'
Links
/api/credit_notes?filter[to]=Value&filter[from]=Value
Name | Type | Description / Example |
---|---|---|
page | number |
In paginated results set the page to look for |
per_page | number |
Results per page. Default is 50, max is 200 |
filter[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 |
/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. |
/api/credit_notes/{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). |
/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. |
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
Date the object was created in SK. Never changes afterwards
Unique identifier - UUID
IDENTITYtrue
Date the object was edited in SK.
Writable Properties
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.
The divider text
Required since items are sorted by position.
The item type: DividerItem. Must be set when creating new items via document.items array
Links
Text template
An text_template in SK
Readonly Properties
Date the object was created in SK. Never changes afterwards
Unique identifier - UUID
IDENTITYtrue
Date the object was edited in SK.
Writable Properties
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
A meaningful name.
A team uuid. If set only the team and its parent teams can see the record.
Text which may contain placeholders, replaced when the template is used.
Links
/api/text_templates?sort_by=Value&page=Value
Name | Type | Description / Example |
---|---|---|
page | number |
In paginated results set the page to look for |
per_page | number |
Results per page. Default is 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 |
An email in SK must always be related to an object. Receivers are limited to 5 per address field.
Readonly Properties
The emails attachments.
SeeDate the object was created in SK. Never changes afterwards
Date the email was delivered by SK. If set, the message cannot be edited anymore.
Unique identifier - UUID
IDENTITYtrue
Is set after an email has been scheduled for sending until it has been sent.
Logs error message when sending failed.
A team uuid taken from the related object. If set only the team and its parent teams can see the record.
Date the object was edited in SK.
Writable Properties
BCC addresses, comma separated. Max 5, format: a@b.de,'George'
The email text.
CC addresses, comma separated. Max 5, format: a@b.de,'George'
From address. If empty the email of the current user is taken.
uuid of the emails parent object.
Object type of the emails parent. Is the camelcased base class name: Document for invoice, credit_note, contact,..
The email subject.
TO addresses, comma separated. Max 5, format: a@b.de,'George'
Links
/api/emails?page=Value&sort_by=Value
Name | Type | Description / Example |
---|---|---|
page | number |
In paginated results set the page to look for |
per_page | number |
Results per page. Default is 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 |
/api/emails?archived_pdf=Value&send=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). |
Line item
A line item for a document
Readonly Properties
Total costs. Calculated from cost_single * quantity
Date the object was created in SK. Never changes afterwards
Gross margin percentage. Calculated from gross_margin_total/cost_total
Gross margin, the difference between revenue and cost before accounting for certain other costs. Calculated from net_total - cost_total
Gross price. Net total with taxes applied.
Unique identifier - UUID
IDENTITYtrue
Net price of a single item. Calculated from price_single * quantity * discount
Date the object was edited in SK.
Writable Properties
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 price for a single item. Used to calculate the gross margin. Max 6 decimal places.
Item description
Discount in percent applied to the items net total. Can also be negative if you want to add additional charges.
Arbitrary number e.g. external product reference.
The name of an item
Position by which the items are sorted. Two items can have the same position(if you dont care) and numbers dont need to continuous
DEFAULT1
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.
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
DEFAULTfalse
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 of the item. Must be >= 0. Max 6 decimal places.
DEFAULT1
Quantity unit: kg, days, month.
Tax percent for a single item.
The item type: LineItem. Must be set when creating new items via document.items array
Links
Account billing
BETA An account billing serves as the glue between an account a document and their related account entries and line items. It also lets one keep track of who billed what and when. A billing is created from billable account entries, which are turned into line items for a document.
Readonly Properties
Date the object was created in SK. Never changes afterwards
User who created the record.
The document created by the billing.
Unique identifier - UUID
IDENTITYtrue
Writable Properties
The related account. Must be set for entries to be found.
The document type to create. CamelCase document class name. Invoice by default
DEFAULTInvoice
Valid ValuesInvoice, CreditNote, Order, Estimate
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 Valuesname, day, week, month, year
A note for the billing e.g. happyPDF usage April 2014. The field is wildcard searchable
Set billed at date for related account entries.
DEFAULTfalse
A team uuid. Is inferred from the accounts team id.
Links
/api/account_billings?sort_by=Value&page=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 |
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
Date the record was created in SK. Never changes afterwards.
Unique identifier - UUID
IDENTITYtrue
Last date when the record was edited.
Writable Properties
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.
The channel to which to subscribe. See available at subs/channels.
Links
Language
A language in SK can be assigned to documents, contacts and templates. When creating new documents, emails or PDF the language is used to select a specific template or language agnostic defaults. A language has many translations.
Readonly Properties
Date the object was created in SK. Never changes afterwards
Unique identifier - UUID
IDENTITYtrue
Date the object was edited in SK.
Writable Properties
Language short-code
The name of the language, shown in the interface
Links
/api/languages?per_page=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 |
Attachment
An file attachment
Readonly Properties
Auto detected on upload. Might not always reflect the real content type
Date the object was created in SK. Never changes afterwards
Unique filename set by SK
The filename as set when uploaded
uuid of the object.
IDENTITYtrue
Filesize in kb. Auto detected on upload.
DEPRECATED use attachments/ID/download
Writable Properties
True if the file(pdf) has been digitally signed.
uuid of the attachment parent object.
Object type of the attachment parent. A base class name: Document(for invoice, credit_note) Contact, Message(for email), Template(for email, pdf template)
A team uuid. If set only the team and its parent teams can see the record.
Links
/api/attachments?filter[q]=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 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 |
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
The exchanged amount.
Date the object was created in SK. Never changes afterwards
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.
Unique identifier - UUID
IDENTITYtrue
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
The payment amount
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 code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
Date the payment was made. YYYY-MM-DD
Reference number f.ex. issued by the bank.
If set the related document is NOT closed.
DEFAULTfalse
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!
How the payment was made.
Valid Valuescash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms
uuid of the payments parent object. Is auto-set when using the nested URL POST invoices/ID/payments
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
/api/payments?sort=Value&sort_by=Value
Name | Type | Description / Example |
---|---|---|
page | number |
In paginated results set the page to look for |
per_page | number |
Results per page. Default is 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 |
Order
An order
Readonly Properties
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.
SeeThe contact for the document. Use contact_id field to set a contact.
SeeCost total of all line items, 2 decimals places in document currency.
Date the object was created in SK. Never changes afterwards.
Estimate document ID, if the order was created from a estimate.
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.
Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100
Total gross margin across all line items. Calculated from net_total-cost_total.
Gross total of all line items, 2 decimals places in document currency.
Exchanged gross total, in your company currency.
Unique identifier - UUID
IDENTITYtrue
Net total, 2 decimals places
Net total, 6 decimal places incl. discount
Tax total, 2 decimals places
A team uuid taken from the contact. If set only the team and its parent teams can see the record.
Date the object was edited in SK.
Writable Properties
Receiver address, normally shown in envelope window. Defaults to client address_field if empty and client_id present.
DEPRECATED: use contact_id
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 code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
Date the order is issued. Automatically set when order is opened. Required for non-draft documents. YYYY-MM-DD
Auto-calculated from date + due days if empty and the document is opened. YYYY-MM-DD
Used to calculate the due date for the document. Useless if date and due date are present.
Some external reference, whatever this may be.
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.
DEFAULTany
SeeShould 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.
DEPRECATED use items
SeeAuto-incremented to prevent concurrent updates. First save wins and increments version.
Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.
Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used.
Unique number assigned by SK order number schema. Auto-assigned when order is opened. Required unless doc status is draft.
How the document is being payed. Used in new payments.
Valid Valuescash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms
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.
DEFAULTdraft
Valid Valuesdraft, open, closed
Space separated list of tags. Are split and saved as Tag objects on create, update.
ID of a tax exemption. When set all item taxes are omitted.
The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your order [number]'
Links
/api/orders?filter[product_ids]=Value&filter[creator_ids]=Value
Name | Type | Description / Example |
---|---|---|
page | number |
In paginated results set the page to look for |
per_page | number |
Results per page. Default is 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 |
/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. |
/api/orders/{id}/emails?send=Value&archived_pdf=Value
Name | Type | Description / Example |
---|---|---|
template_id | string |
UUID of an email template to use. If present template fields like subject, body, attachments are used for the current email. |
send |
Schedule email for sending. Omit this parameter or set value to 0 or false(String or Integer) to keep email as draft. |
|
archived_pdf |
Adds the archived pdf from the related resource(if it has one). |
/api/orders/{id}/print?base64=Value&template_id=Value
Name | Type | Description / Example |
---|---|---|
template_id * |
UUID of a pdf template used to print the document. MUST be present |
|
base64 |
If set the new pdf is returned inside the attachment JSON within 'base64' key. Leave empty to save traffic. |
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
The context for the permission, being a resource: clients, emails
Unique identifier - UUID
IDENTITYtrue
A permission has many privileges which define the actions someone can execute. Such actions are resource methods like index, update, edit, show
Writable Properties
Context_name and name localized: API Clients read - API Kunden anzeigen
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
/api/auth_permissions?page=Value&filter[q]=Value
Name | Type | Description / Example |
---|---|---|
page | number |
In paginated results set the page to look for |
per_page | number |
Results per page. Default is 50, max is 200 |
filter[q] | string |
Search in name 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 |
Comment
An comment in SK must always be related to an object.
Readonly Properties
Date the object was created in SK. Never changes afterwards
Unique identifier - UUID
IDENTITYtrue
A team uuid taken from the related object. If set only the team and its parent teams can see the record.
Date the object was edited in SK.
Writable Properties
uuid of the comments parent object.
Object type of the comments parent. Is the camelcased base class name: Document for invoice, credit_note, contact
The comment himself.
Links
/api/comments?filter[contact_ids]=Value&sort_by=Value
Name | Type | Description / Example |
---|---|---|
page | number |
In paginated results set the page to look for |
per_page | number |
Results per page. Default is 50, max is 200 |
filter[q] | string |
Search in text |
filter[contact_ids] | string |
Comma-separated list of contact IDs. While present, it will return comments related to the contact and all its documents. |
filter[related_object_ids] | string |
Comma-separated list of related object IDs (objects which can have their own comments: document, task, products). Can also be used with a single ID to find all comments related to the given object. |
filter[from] | string (date) |
All objects with a date after the date. YYYY-MM-DD |
filter[to] | string (date) |
All objects with date before the date. YYYY-MM-DD |
sort_by |
string
(enum)
[created_at, updated_at] |
Sort the results by the given field => number |
sort |
string
(enum)
[ASC, DESC] |
Sort the results in ASC or DESC |
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
The account balance is the sum of all entries, also those from sub-accounts.
Date the object was created in SK. Never changes afterwards
The user uuid who created the record.
Unique identifier - UUID
IDENTITYtrue
Date the object was edited in SK.
Writable Properties
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.
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.
Tax value for a billing fee line item. The item is added to the resulting document upon each account_billing creation.
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?
The contacts uuid to which the account is related.
The default price single for new account entries, if price single is empty on create. Max 6 decimal places.
The default quantity unit for new account entries, if unit is empty on create.
Account description
Document uuid, related to the account.
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
The name of the account
Unique number assigned by you or if empty SK account number schema.
A team uuid. If set only the team and its parent teams can see the record.
Links
/api/accounts?filter[parent_id]=Value&page=Value
Name | Type | Description / Example |
---|---|---|
filter[q] | string |
Wildcard search in number, name, description |
filter[number] | string |
Search by exact number |
filter[balance_from] | number |
Find account with a balance greater(>=) than given number. |
filter[balance_to] | number |
Find accounts with a balance smaller(<=) than given number. |
filter[contact_ids] | string |
Find objects belonging to a single or a list of contacts, use ids comma separated. |
filter[parent_id] | string |
Search children of the given account. |
page | number |
In paginated results set the page to look for |
per_page | number |
Results per page. Default is 50, max is 200 |
sort_by |
string
(enum)
[name, number, balance, created_at, updated_at] |
Sort the results by the given field => number |
sort |
string
(enum)
[ASC, DESC] |
Sort the results in ASC or DESC |
Invoice
An invoice
Readonly Properties
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.
SeeThe contact for the document. Use contact_id field to set a contact.
SeeCost total of all line items, 2 decimals places in document currency.
Date the object was created in SK. Never changes afterwards.
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.
Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100
Total gross margin across all line items. Calculated from net_total-cost_total.
Gross total of all line items, 2 decimals places in document currency.
Exchanged gross total, in your company currency.
Unique identifier - UUID
IDENTITYtrue
Net total, 2 decimals places
Net total, 6 decimal places incl. discount
DEPRECATED: use tax_total
DEPRECATED use net_total_base
Recurring document ID, if the invoice was created from a recurring.
Tax total, 2 decimals places
A team uuid taken from the contact. If set only the team and its parent teams can see the record.
Date the object was edited in SK.
Writable Properties
Receiver address, normally shown in envelope window. Defaults to client address_field if empty and client_id given.
DEPRECATED: use contact_id
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 code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
Date the invoice is issued. Automatically set when invoice is opened. Required for non-draft documents. YYYY-MM-DD
Auto-calculated from date + due days if empty and the document is opened. YYYY-MM-DD
Used to calculate the due date of the document. Useless if date and due date are present.
Some external reference, whatever this may be.
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.
DEFAULTany
SeeShould 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.
DEPRECATED use items
SeeAuto-incremented to prevent concurrent updates. First save wins and increments version.
Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.
Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used.
Unique number assigned by SK invoice number schema. Auto-assigned when invoice is opened. Required unless doc status is draft.
How the document is being payed. Used in new payments.
Valid Valuescash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms
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 ValuesFRST, OOFF, RCUR, FNAL
SEPA mandate identifier needed in direct debit transactions. This is a unique id given by you to the customer beforehand.
Date the SEPA mandate was signed by your customer. Must not be in the future!
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.
DEFAULTdraft
Valid Valuesdraft, open, closed, overdue
Space separated list of tags. Are split and saved as Tag objects on create, update.
ID of a tax exemption. When set all item taxes are omitted.
The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your invoice [number]'
Links
/api/invoices?filter[q]=Value&sort_by=Value
Name | Type | Description / Example |
---|---|---|
page | number |
In paginated results set the page to look for |
per_page | number |
Results per page. Default is 50, max is 200 |
filter[q] | string |
Search in 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 |
/api/invoices?source=Value&cancel=Value
Name | Type | Description / Example |
---|---|---|
source | string |
Copies the source(excl. number,date) and returns a new draft document. Fields passed with the object(e.g. notes, title, address_field) are not overwritten. When copying a different document type e.g. creating an invoice from an order(pass an order ID), ONLY the items, contact, currency and tag list are taken from the source doc. |
cancel | boolean - Depends on: source |
Cancelling a document copies the source and negates all line item values. A source id MUST be set. |
/api/invoices/{id}/emails?template_id=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). |
/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 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 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.
SeeThe contact for the document. Is assigned through the related invoice.
SeeThe contact uuid. Is assigned through the related invoice.
Date the object was created in SK. Never changes afterwards.
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.
DEPRECATED use net_total bcs there are no taxes applied
Exchanged gross total, in your company currency.
Unique identifier - UUID
IDENTITYtrue
Net total, 2 decimals places
A team uuid taken from the contact. If set only the team and its parent teams can see the record.
Date the object was edited in SK.
Writable Properties
Receiver address, shown in envelope window. Defaults to invoice.client.address_field if created from invoice.
DEPRECATED: use contact_id
Currency code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
Date the payment_reminder is issued. Automatically set when created from invoice. Defaults to today. YYYY-MM-DD
Auto-calculated from date + due days if empty and the payment_reminder is opened. YYYY-MM-DD
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
Some external reference, whatever this may be.
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 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.
DEFAULTany
SeeShould 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.
DEPRECATED use items
SeeAuto-incremented to prevent concurrent updates. First save wins and increments version.
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 shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used. Defaults to values from settings
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.
DEFAULTopen
Valid Valuesdraft, open, closed, overdue
Space separated list of tags. Are split and saved as Tag objects on create, update.
The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your payment_reminder [number]'. Defaults to values from settings
Links
/api/payment_reminders?filter[tags]=Value&filter[languages]=Value
Name | Type | Description / Example |
---|---|---|
page | number |
In paginated results set the page to look for |
per_page | number |
Results per page. Default is 50, max is 200 |
filter[q] | string |
Search in title, number, address field |
filter[tags] | string |
Filter by a space delimited list of tags |
filter[from] | string (date) |
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 |
/api/payment_reminders/{id}/emails?template_id=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). |
/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. |
Export
An export in SK
Readonly Properties
The exported data as attachment.
SeeDate the object was created in SK. Never changes afterwards
Date the was finished
Unique identifier - UUID
IDENTITYtrue
Errors and warnings, can contain html markup f.ex. links to contacts with invalid back accounts when doing dtaus export
Date the was started
The export status
Valid Valuespending, in_progress, failed, success
Date the object was edited in SK.
Writable Properties
Comma separated uuid's of the export objects. The backend uses a mysql text-column limited to ~64kb. 100 uuids are ~2.5kb
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.
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 Valuestext, archived_pdf, attachments, allinone_pdf, sepa_debit, sepa_credit
A team uuid. If set only the team and its parent teams can see the record.
A export template uuid. Required for text exports. collection_type can be empty as is forced to the templates type
Links
/api/exports?filter[to]=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[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 |
Tag
A tag
Readonly Properties
Unique identifier - UUID
IDENTITYtrue
The tag itself
Usage count of this tag, for all objects in whole company scope.
Writable Properties
Links
/api/tags?filter[related_object_type]=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 |
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 |
User
A user as seen by SalesKing
Readonly Properties
Date the record was created in SK. Never changes afterwards.
Unique identifier - UUID
IDENTITYtrue
Last date when the record was edited.
Writable Properties
Email address of the user. Unique in SK
First name
The users gender, used in salutation
Valid Valuesmale, female
The users language, reflected in the interface.
Last name of a person. At least this or the organisation field must be filled for new records
Fax number
Private phone number.
Mobile phone number
Office phone number
Position of a person in a company.
Time zone
Academical title of a person e.g. Dr., Prof
An url associated with the person, e.g its company website.
Links
Task
An Task in SK.
Readonly Properties
Attached files, uploads.
SeeDate the task was completed.
The contact for the task. Use contact_id field to set a contact.
SeeDate the object was created in SK. Never changes afterwards
Unique identifier - UUID
IDENTITYtrue
Date the object was edited in SK.
Writable Properties
User who should do the tasks.
Related contact of the tasks.
User who created the tasks.
Notes, explanations for the task.
A tasks can have many related documents.
SeeThe task title.
New tasks are open by default, unless otherwise stated.
DEFAULTopen
Valid Valuesopen, closed, overdue
Links
/api/tasks?filter[assignee_ids]=Value&filter[updated_at_to]=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 |
/api/tasks?source=Value&document_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. |
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
Date the object was created in SK. Never changes afterwards
Unique identifier - UUID
IDENTITYtrue
Date the object was edited in SK.
Writable Properties
Additional information about the template.
Kind of object the template can be used for.
Valid Valuesinvoice, estimate, credit_note, payment_reminder, order
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 of the template as shown to the user.
A team uuid. If set only the team and its parent teams can see the record.
Links
/api/pdf_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, 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 |
Recurring
An recurring is used as an template for new invoices.
Readonly Properties
The contact for the document. Use contact_id field to set a contact.
SeeCost total of all line items, 2 decimals places in document currency.
Date the object was created in SK. Never changes afterwards.
Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100
Total gross margin across all line items. Calculated from net_total-cost_total.
Gross total of all line items, 2 decimals places
Unique identifier - UUID
IDENTITYtrue
Net total, 2 decimals places
Net total, 6 decimal places incl. discount
Tax total, 2 decimals places
A team uuid taken from the contact. If set only the team and its parent teams can see the record.
Date the object was edited in SK.
Writable Properties
Receiver address, normally shown in envelope window. Defaults to client address_field if empty and client_id given.
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 ValuesDEPRECATED: use contact_id
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 code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
First date the recurring is issued. Not allowed to be in the past. YYYY-MM-DD
Used to calculate the due date of the recurring. Useless if date and due date are present.
The Email template used for the email in auto sending. Required when auto_send'ing is enabled.
Some external reference, whatever this may be.
The last date the recurring is executed. YYYY-MM-DD
Recurring frequency
Valid Valuesyearly, monthly, weekly, quarterly, biweekly, sixmonthly
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.
DEFAULTany
SeeShould 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.
DEPRECATED use items
SeeAuto-incremented to prevent concurrent updates. First save wins and increments version.
Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.
Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used.
Unique name to identify the document. Unlike all other document this one has no number schema and not auto assign
How the document is being payed. Used in new payments.
Valid Valuescash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms
The PDF template used for printing the invoice when auto sending. Required when auto_send'ing is enabled.
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 ValuesFRST, OOFF, RCUR, FNAL
SEPA mandate identifier needed in direct debit transactions. This is a unique id given by you to the customer beforehand.
Date the SEPA mandate was signed by your customer. Must not be in the future!
Space separated list of tags. Are split and saved as Tag objects on create, update.
ID of a tax exemption. When set all item taxes are omitted.
The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your recurring [number]'
Links
/api/recurrings?filter[created_at_to]=Value&filter[ids]=Value
Name | Type | Description / Example |
---|---|---|
page | number |
In paginated results set the page to look for |
per_page | number |
Results per page. Default is 50, max is 200 |
filter[q] | string |
Search in title, number, address field |
filter[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 |
/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. |
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
Date the object was created in SK. Never changes afterwards
Gross sub-total
Unique identifier - UUID
IDENTITYtrue
Net sub-total
Date the object was edited in SK.
Writable Properties
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.
Title of the sub-total e.g. Hardware total
Required since items are sorted by position.
The item type: SubTotalItem. Must be set when creating new items via document.items array
Links
Estimate
An estimate
Readonly Properties
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.
SeeThe contact for the document. Use contact_id field to set a contact.
SeeCost total of all line items, 2 decimals places in document currency.
Date the object was created in SK. Never changes afterwards.
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.
Product of the probability and net total. In company currency
Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100
Total gross margin across all line items. Calculated from net_total-cost_total.
Gross total of all line items, 2 decimals places in document currency.
Exchanged gross total, in your company currency.
Unique identifier - UUID
IDENTITYtrue
Net total, 2 decimals places
Net total, 6 decimal places incl. discount
Tax total, 2 decimals places
A team uuid taken from the contact. If set only the team and its parent teams can see the record.
Date the object was edited in SK.
Writable Properties
Receiver address, normally shown in envelope window. Defaults to client address_field if empty and client_id present.
DEPRECATED: use contact_id
Date when the deal is expected to be closed.
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 code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)
Date the estimate is issued. Automatically set when estimate is opened. Required for non-draft documents. YYYY-MM-DD
Auto-calculated from date + due days if empty and the estimate is opened. YYYY-MM-DD
Used to calculate the valid-until date of the estimate. Useless if date and due date are present.
Some external reference, whatever this may be.
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.
DEFAULTany
SeeShould 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.
DEPRECATED use items
SeeAuto-incremented to prevent concurrent updates. First save wins and increments version.
Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.
Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used.
Unique number assigned by SK estimate number schema. Auto-assigned when estimate is opened. Required unless doc status is draft.
Percentage of estimated confidence in closing the deal. Estimated Probability percentage of the net total amount
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.
DEFAULTdraft
Valid Valuesdraft, open, closed, rejected, billed
Space separated list of tags. Are split and saved as Tag objects on create, update.
The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your estimate [number]'
Links
/api/estimates?filter[product_ids]=Value&filter[languages]=Value
Name | Type | Description / Example |
---|---|---|
page | number |
In paginated results set the page to look for |
per_page | number |
Results per page. Default is 50, max is 200 |
filter[q] | string |
Search in title, number, address field |
filter[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 |
/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. |
/api/estimates/{id}/emails?archived_pdf=Value&template_id=Value
Name | Type | Description / Example |
---|---|---|
template_id | string |
UUID of an email template to use. If present template fields like subject, body, attachments are used for the current email. |
send |
Schedule email for sending. Omit this parameter or set value to 0 or false(String or Integer) to keep email as draft. |
|
archived_pdf |
Adds the archived pdf from the related resource(if it has one). |
/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. |
Export template
An export_template in SK
Readonly Properties
Date the object was created in SK. Never changes afterwards
Unique identifier - UUID
IDENTITYtrue
Date the object was edited in SK.
Writable Properties
Name of the created export file. Date placeholders can be used: %y-%m-%d_%H-%M_clients.csv
Kind of object the template can be used for.
Valid Valuesinvoice, estimate, credit_note, payment_reminder, order, contact, payment, comment, email, history, product, recurring
A meaningful name.
A team uuid. If set only the team and its parent teams can see the record.
Text with placeholders, replaced when the template is used.
Links
/api/export_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 |
Account entry
A entry for an account
Readonly Properties
Date the object was created. Never changes afterwards
Document the entry is related to. This relation is set by an account billing.
Unique identifier - UUID
IDENTITYtrue
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 price of a single entry. Calculated from price_single * quantity
Date the object was edited.
Writable Properties
When set an existing entry will be deleted. This switch is used for entries passed during batch operations.
Account the entry belongs to.
True if the entry can be billed.
DEFAULTfalse
Date the object was billed. Automatically set when the entry is used on an invoice.
Date of the entry. Defaults to today. Entries are sorted by date per default.
Entry description
The name of an entry
Net price of a single entry. If a product id is given, price_single is taken from the product if not set.
Quantity of the entry.
DEFAULT1
Quantity unit e.g: kg, days, month, ..
Tax percentage
Links
/api/account_entries?filter[account_ids]=Value&filter[q]=Value
Name | Type | Description / Example |
---|---|---|
page | number |
In paginated results set the page to look for |
per_page | number |
Results per page. Default is 50, max is 200 |
filter[q] | string |
Wildcard search in name, description |
filter[account_ids] | string |
Set multiple account ids comma separated or as array |
filter[document_ids] | string |
Set multiple document ids comma separated or as array |
filter[ids] | string |
Set multiple entry ids comma separated or as array |
filter[unbilled] | boolean |
Entries available for billing: marked as billable without a billing date(billed_at) set. False values will skip this filter. To find billed entries simply use filter[billed_at_to] e.g with todays date. |
filter[billable] | boolean |
Billable or not billable entries. Set false(string) or 0(Integer) to get not billable entries. For billable entries use true or 1. Also see filter[unbilled] to find not yet billed entries. |
filter[date_from] | string (date) |
Objects with a date eq/after the date. YYYY-MM-DD |
filter[date_to] | string (date) |
Objects with date eq/before the date. YYYY-MM-DD |
filter[billed_at_from] | string (date) |
Objects with a billing date eq/after the date. YYYY-MM-DD |
filter[billed_at_to] | string (date) |
Objects with billing date eq/before the date. YYYY-MM-DD. A set billing date means the entry has been billed, so simply use this filter e.g with date today to find all billed entries. |
filter[created_at_from] | string (date) |
Objects with a date eq/after the date. YYYY-MM-DD |
filter[created_at_to] | string (date) |
Objects with a creation until the date(<=). ISO 8601 format YYY-MM-DDThh:mm:ss+z or just a date YYY-MM-DD. If date is given the time is set to the end of the day(23:59:59) so all objects created on that day are included. A time should be already utc time. |
sort_by |
string
(enum)
[name, number, date, quantity, price_single, created_at, updated_at] |
Sort the results by the given field => number |
sort |
string
(enum)
[ASC, DESC] |
Sort the results in ASC or DESC |
Product
A product in SK
Readonly Properties
Date the object was created in SK. Never changes afterwards
Unique identifier - UUID
IDENTITYtrue
Date the object was edited in SK.
Writable Properties
Name of the product category. A new category is created if it does not exist.
Cost price of a single product. Max 6 decimal places.
Product description
The name of the product
Unique number assigned by you or if empty SK product number schema.
Net price of a single product. Max 6 decimal places.
Unit like kg, days, month.
Space separated list of tags. Are split and saved as Tag objects on create, update.
Tax percentage for this product.
A team uuid. If set only the team and its parent teams can see the record.
Links
/api/products?filter[q]=Value&sort_by=Value
Name | Type | Description / Example |
---|---|---|
page | number |
In paginated results set the page to look for |
per_page | number |
Results per page. Default is 50, max is 200 |
filter[q] | ["string", "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 |
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
Date the object was created in SK. Never changes afterwards
Unique identifier - UUID
IDENTITYtrue
Date the object was edited in SK.
Writable Properties
Default blind copy receivers comma separated valid email addresses.
Body with placeholders, replaced when the template is used.
Default copy receivers comma separated valid email addresses.
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 of object the template can be used for.
Valid Valuesinvoice, estimate, credit_note, payment_reminder, order, contact
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.
A meaningful name.
Subject containing placeholders, replaced when the template is used.
A team uuid. If set only the team and its parent teams can see the record.
Links
/api/email_templates?page=Value&filter[kind]=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 |
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
Returns the address field used on new docs. Consist of Organisation name and default(first) address
Date the record was created in SK. Never changes afterwards.
Product of the probability and sales potential. e.g how much of the sales_potential can we get?
Unique identifier - UUID
IDENTITYtrue
Last date when the record was edited.
Writable Properties
A client can have many addresses, sorted by date descending(new first). Default address is the most recent one.
SeeBank account number.
IBAN Number of the bank account. Is validated
Bank name
Bank number
Bank account owner
SWIFT BIC- Bank Identifier Code
The birthday. YYYY-MM-DD
Default cash discount for new invoices.
Date the contact converted from lead to client or any other contact type (supplier)
Currency code as defined by the ISO 4217 standard(3-letter UPCASE: EUR, USD). If set the currency is taken for new documents.
Default due days for new documents.
Email address of the contact.
First name of a person.
Can be empty for a company. Is used in salutation
Valid Valuesmale, female
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.
DEFAULTfalse
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 of a person. At least this or the organisation field must be filled for new records
Lead date e.g. date of first contact with your company. YYYY-MM-DD
Lead reference e.g. a tracking id, web-url
Lead source describing where a contact came from e.g. a campaign name, website, facebook, URL
Increased on every edit, so SK can detect/prevent a concurrent edit by another user. First save wins.
Notes for a contact. For day to day information you should use comments instead.
Unique number, auto-created by SK for new contacts(client, supplier) without number.
Name of a company. This or lastname must be present
ID of a parent contact.
Default payment method for used for new documemts
Valid Valuescash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms
Fax number
Private phone number
Mobile phone number
Office phone number
Position of a person in a company.
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 for the contact e.g what is his budget, how much can he spend?
Space separated list of tags. Are split and saved as Tag objects on create, update.
ID of a tax exemption. New documents inherit the tax exemption and will be created without any taxes.
Tax number, normally applies to a private person
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!!
Academical title of a person e.g. Dr., Prof
Type of contact
Valid ValuesClient, Lead, Supplier
An url associated with the person, e.g its company website.
VAT number, for a company or person paying value added taxes.
Links
/api/contacts?filter[sales_potential_to]=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 |
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 |
/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). |
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
Date the object was created in SK. Never changes afterwards.
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 of all line items, 2 decimals places in document currency.
Exchanged gross total, in your company currency.
Unique identifier - UUID
IDENTITYtrue
Net total, 2 decimals places
Net total, 6 decimal places incl. discount
Tax total, 2 decimals places
A team uuid taken from the contact. If set only the team and its parent teams can see the record.
Date the object was edited in SK.
Writable Properties
Receiver address, normally shown in envelope window. Defaults to client address_field.
DEPRECATED: use contact_id
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 code as defined by the ISO 4217 standard. 3-letter UPCASE: EUR, USD
Date the document is issued. Automatically set when document is opened. Required for non-draft documents. YYYY-MM-DD
Some external reference, whatever this may be.
Items for the document. Access items of all types including divider and sub_total items.
DEFAULTany
SeeShould 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 for the document
SeeNotes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.
Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used.
Unique number assigned by a user or automatic by the object's number schema.
The specific type of the document singular CamelCased: Invoice, PaymentReminder
Space separated list of tags. Are split and saved as Tag objects on create, update.
The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your invoice [number]'
Links
/api/documents?filter[tags]=Value&filter[from]=Value
Name | Type | Description / Example |
---|---|---|
page | number |
In paginated results set the page to look for |
per_page | number |
Results per page. Default is 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 |
Client
A client as seen by SalesKing. This resource is DEPRECATED please use contacts instead with type-field set 'Client'
Readonly Properties
Returns the address field used on new docs. Consist of Organisation name and default(first) address
Date the record was created in SK. Never changes afterwards.
Unique identifier - UUID
IDENTITYtrue
Last date when the record was edited.
Writable Properties
A client can have many addresses, sorted by date descending(new first). Default address is the most recent one.
SeeBank account number.
IBAN Number of the bank account. Is validated
Bank name
Bank number
Bank account owner
SWIFT BIC- Bank Identifier Code
The birthday. YYYY-MM-DD
Default cash discount for new invoices.
Currency code as defined by the ISO 4217 standard(3-letter UPCASE: EUR, USD). If set the currency is taken for new documents.
Default due days for new invoices.
Email address of the contact.
First name of a person.
Can be empty for a company. Is used in salutation
Valid Valuesmale, female
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 of a person. At least this or the organisation field must be filled for new records
Increased on every edit, so SK can detect/prevent a concurrent edit by another user. First save wins.
Notes for a contact. For day to day information you should use comments instead.
Unique number, auto-created by SK for new client without number.
Name of a company. This or lastname must be present
Default payment method for used for new documemts
Valid Valuescash, bank_transfer, credit_card, paypal, direct_debit, cheque, moneybookers, premium_sms
Fax number
Private phone number
Mobile phone number
Office phone number
Position of a person in a company.
Space separated list of tags. Are split and saved as Tag objects on create, update.
Tax number, normally applies to a private person
A team uuid. If set only the team and its parent teams can see the record.
Academical title of a person e.g. Dr., Prof
An url associated with the person, e.g its company website.
VAT number, for a company or person paying value added taxes.
Links
/api/clients?sort=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 |
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 |