API v1

Scoro API v1

v1 api will be deprecated on 01.05.2019. Please move your v1 requests to api v2.

Overview

The Scoro API is an interface for accessing your Scoro account data using HTTP and JSON. The API makes it easy to create web and desktop applications that integrate with your account.

Some potential application ideas:

The Scoro API has a single point of entry, derived from your account URL

Full url depends on the info requested.

Sample URL
https://#companyname#.scoro.ee/api/v1

Please note the use of https:// in the URL above. All API communication is encrypted over HTTPS. Any non-secure requests are automatically rejected, so we recommend establishing a test connection with the secure API entry point before sending sensitive data.

Full address to send JSON requests looks like this

Full request url
https://#companyname#.scoro.ee/api/#module#(/#action#)(/#id#)

where
#companyname# is the subdomain
#module# is the module accessed ("contacts")
#action# (optional) what to do with the selected object. Possible options are ("modify", "delete", "view"), see each module for a list of available actions
#id# (optional) what object to get

Changes from version 18.4

Changes from version 18.1

Changes from version 17.2

Changes from version 16.5

Changes from version 16.4

Changes from version 16.3

Changes from version 16.2

Changes from version 16.1

Changes from version 15.4

Changes from version 15.3

Changes from version 15.2

Request Limits

By default, all accounts have a request limit of 500 API requests per day. Additionally, a maximum of 100 results will be returned for list methods, regardless of the value sent with the per_page parameter. The page paramater can be used to request additional items.

Sample request with per_page and page parameters
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "per_page": 50,
    "page": 2,
    "request": []
}
Sample request with user_token
{
    "user_token": "USER_API_token",
    "lang": "eng",
    "company_account_id": "tutorial",
    "per_page": 50,
    "page": 2,
    "request": []
}

Representation Formats

All API requests are composed of light-weight JSON delivered as an HTTP POST request to the endpoint URL.

All JSON should be UTF-8 encoded.

Date and time values are of the form YYYY-MM-DD HH:MM:SS.

Booleans are either 1 (true) or 0 (false).

Fields denoting percentages are passed as whole values, not decimals (e.g. 5 for five percent).

All requests should contain at least the following values:

The apiKey and company_account_id values are listed in Settings > External Connections > API.

Sample request in PHP using cURL
<?php

    define('API_KEY', 'API_hash');
    define('BASE_URL', 'https://#companyname#.scoro.ee/api');

    $fields = array(
        'apiKey' => API_KEY,
        'lang' => 'eng',
        'company_account_id' => 'sample',
        'per_page' => '10'
    );
    $fieldsJson = json_encode($fields);

    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, BASE_URL.'/contacts');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $fieldsJson);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $result = curl_exec($ch);
    if ($result) {
        $contacts = json_decode($result, true);
        ?><pre><?print_r($contacts);?></pre><?
    }

?>
            

Responses

All responses are wrapped in a top-level response element. The status attribute will let you know whether the request succeeded or failed. Status can be OK or ERROR. The statusCode attribute can contain the following values:

Status code Response message Description
200 Success If data was requested, it will be available in the data field at the top level of the response body.
400 Invalid request This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
401 No authorization A valid API key was not provided with the request, so the API could not associate a user with the request.
403 Forbidden The API key was wrong.
408 Request timed out The maximum execution time of the request was reached.
500 Server error There was a problem on our end.

In the event of an error, the response body will contain an messages field at the top level. This contains an array of at least one error message

Missing authorization header
Request https://#companyname#.scoro.ee/api/contacts
{
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {}
}
Response HTTP/1.1 200
{
    "status": "ERROR",
    "statusCode": "401",
    "messages": {
        "error": [
            "Missing Api Key"
        ]
    }
}
Bad request parameters
Request https://#companyname#.scoro.ee/api/contacts
{
    "apiKey": "wrong",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {}
}
Response HTTP/1.1 200
{
    "status": "ERROR",
    "statusCode": "403",
    "messages": {
        "error": [
            "Wrong Api Key"
        ]
    }
}
There was a problem on our end
Request https://#companyname#.scoro.ee/api/contacts
{
    "apiKey": "API_hash",
    "lang": "abc",
    "company_account_id": "tutorial",
    "request": {}
}
Response HTTP/1.1 200
{
    "status": "ERROR",
    "statusCode": "500",
    "messages": {
        "error": [
            "Language code[lang] missing or wrong"
        ]
    }
}

Filters

List results can be filtered by adding a filter object to the request. This filter object should have field names as keys and search words as values. If filtering by a range the value should be another object containing from and/or to field.

Filter results
https://#companyname#.scoro.ee/api/contacts
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "filter": {
        "name": "Sample%"
    }
}
Filtering by range
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "filter": {
        "modified_date": {
            "from": "2013-02-01",
            "to": "2013-02-28"
        }
    }
}
Filtering by custom fields
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "filter": {
        "custom_fields": {
            "field1": "value1",
            "field2": "value2"
        }
    }
}
Filtering with deleted entries
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "include_deleted": "1",
    "filter": {
        "modified_date": {
            "from": "2013-02-01",
            "to": "2013-02-28"
        }
    }
}

Timezones

Contacts have their own timezone field. List of available timezones are shown here

Name Code
(GMT-12:00) International Date Line West Etc/GMT+12
(GMT-11:00) Midway Island, Samoa Pacific/Apia
(GMT-10:00) Hawaii Pacific/Honolulu
(GMT-09:00) Alaska America/Anchorage
(GMT-08:00) Pacific Time (US & Canada); Tijuana America/Los_Angeles
(GMT-07:00) Arizona America/Phoenix
(GMT-07:00) Mountain Time (US & Canada) America/Denver
(GMT-07:00) Chihuahua, La Paz, Mazatlan America/Chihuahua
(GMT-06:00) Central America America/Managua
(GMT-06:00) Saskatchewan America/Regina
(GMT-06:00) Guadalajara, Mexico City, Monterrey America/Mexico_City
(GMT-06:00) Central Time (US & Canada) America/Chicago
(GMT-05:00) Indiana (East) America/Indiana/Indianapolis
(GMT-05:00) Bogota, Lima, Quito America/Bogota
(GMT-05:00) Eastern Time (US & Canada) America/New_York
(GMT-04:00) Caracas, La Paz America/Caracas
(GMT-04:00) Santiago America/Santiago
(GMT-04:00) Atlantic Time (Canada) America/Halifax
(GMT-03:30) Newfoundland America/St_Johns
(GMT-03:00) Buenos Aires, Georgetown America/Argentina/Buenos_Aires
(GMT-03:00) Greenland America/Godthab
(GMT-03:00) Brasilia America/Sao_Paulo
(GMT-02:00) Mid-Atlantic America/Noronha
(GMT-01:00) Cape Verde Is. Atlantic/Cape_Verde
(GMT-01:00) Azores Atlantic/Azores
(GMT) Casablanca, Monrovia Africa/Casablanca
(CET) Central European Time CET
(GMT) Greenwich Mean Time : Dublin, Edinburgh, Lisbon, London Europe/London
(GMT+01:00) West Central Africa Africa/Lagos
(GMT+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna Europe/Berlin
(GMT+01:00) Brussels, Copenhagen, Madrid, Paris Europe/Paris
(GMT+01:00) Sarajevo, Skopje, Warsaw, Zagreb Europe/Sarajevo
(GMT+01:00) Belgrade, Bratislava, Budapest, Ljubljana, Prague Europe/Belgrade
(GMT+02:00) Harare, Pretoria Africa/Johannesburg
(GMT+02:00) Jerusalem Asia/Jerusalem
(GMT+02:00) Athens Europe/Athens
(GMT+02:00) Helsinki, Kyiv, Riga, Sofia, Tallinn, Vilnius Europe/Helsinki
(GMT+02:00) Cairo Africa/Cairo
(GMT+02:00) Bucharest Europe/Bucharest
(GMT+03:00) Istanbul, Minsk Europe/Istanbul
(GMT+03:00) Nairobi Africa/Nairobi
(GMT+03:00) Kuwait, Riyadh Asia/Riyadh
(GMT+03:00) Moscow, St. Petersburg, Volgograd Europe/Moscow
(GMT+03:00) Baghdad Asia/Baghdad
(GMT+03:30) Tehran Asia/Tehran
(GMT+04:00) Abu Dhabi, Muscat Asia/Muscat
(GMT+04:00) Baku, Tbilisi, Yerevan Asia/Tbilisi
(GMT+04:30) Kabul Asia/Kabul
(GMT+05:00) Islamabad, Karachi, Tashkent Asia/Karachi
(GMT+05:00) Ekaterinburg Asia/Yekaterinburg
(GMT+05:30) Chennai, Kolkata, Mumbai, New Delhi Asia/Kolkata
(GMT+05:45) Kathmandu Asia/Kathmandu
(GMT+06:00) Sri Jayawardenepura Asia/Colombo
(GMT+06:00) Astana, Dhaka Asia/Dhaka
(GMT+06:00) Almaty, Novosibirsk Asia/Novosibirsk
(GMT+06:30) Rangoon Asia/Rangoon
(GMT+07:00) Bangkok, Hanoi, Jakarta Asia/Bangkok
(GMT+07:00) Krasnoyarsk Asia/Krasnoyarsk
(GMT+08:00) Perth Australia/Perth
(GMT+08:00) Taipei Asia/Taipei
(GMT+08:00) Kuala Lumpur, Singapore Asia/Singapore
(GMT+08:00) Beijing, Chongqing, Hong Kong, Urumqi Asia/Hong_Kong
(GMT+08:00) Irkutsk, Ulaan Bataar Asia/Irkutsk
(GMT+09:00) Osaka, Sapporo, Tokyo Asia/Tokyo
(GMT+09:00) Seoul Asia/Seoul
(GMT+09:00) Yakutsk Asia/Yakutsk
(GMT+09:30) Darwin Australia/Darwin
(GMT+09:30) Adelaide Australia/Adelaide
(GMT+10:00) Guam, Port Moresby Pacific/Guam
(GMT+10:00) Brisbane Australia/Brisbane
(GMT+10:00) Vladivostok Asia/Vladivostok
(GMT+10:00) Hobart Australia/Hobart
(GMT+10:00) Canberra, Melbourne, Sydney Australia/Sydney
(GMT+11:00) Magadan, Solomon Is., New Caledonia Asia/Magadan
(GMT+12:00) Fiji, Kamchatka, Marshall Is. Pacific/Fiji
(GMT+12:00) Auckland, Wellington Pacific/Auckland
(GMT+13:00) Nuku'alofa Pacific/Tongatapu

Contacts

Name Type Description
contact_id Integer Contact ID
name String contact first name or company name
lastname String contact last name. Used only for persons
contact_type String possible values are "person" or "company". If none specified "company" is used
id_code String code for company or person
bankaccount String Contact bank account
birthday Date (YYYY-mm-dd) can be without a year
position String working position. CEO, manager etc.
comments String Contact comment.
sex String Possible values are "NULL", "F", "M"
vatno String VAT number
timezone String timezone codes to use are shown here
manager_id Integer Contact manager ID.
is_supplier Boolean If the company is a supplier or not.
is_client Boolean If the contact is a client or not.
modified_date Datetime (YYYY-mm-dd HH:ii:ss) The date when contact was last modified.
addresses Array Array of objects containing the following address fields: country (3-letter ISO 3166 code), county, municipality, city, street, zipcode. Not used on company based API list requests.
means_of_contact Object Object containing any of the following fields: mobile, phone, email, website, skype, fax. Values can be strings or arrays if contact has multiple means of contact. Values will always be returned as arrays on view requests. Not used on company based API list requests.
tags Array Array of contact tags. Not used on list requests.
reference_no String Reference number for contact.
custom_fields Object Custom fields. Only filled on view requests.
is_deleted Boolean Is deleted. Use 'include_deleted = 1' in request object to get deleted objects to response as well.

Available actions are

list
modify
view
delete
Request URL
https://#companyname#.scoro.ee/api/contacts
Getting contacts list
https://#companyname#.scoro.ee/api/contacts/ Request
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial"
}
Response
{
    "status": "OK",
    "statusCode": "200",
    "messages": null,
    "data": [
        {
            "contact_id": "1",
            "name": "",
            "id_code": "12345678",
            "bankaccount": null,
            "birthday": null,
            "position": null,
            "comments": null,
            "sex": null,
            "vatno": null
        }
    ]
}
Adding new contact
https://#companyname#.scoro.ee/api/contacts/modify
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "name": "Testing 123",
        "lastname": "",
        "bankaccount": null,
        "birthday": "0000-00-00",
        "position": "",
        "comments": "",
        "sex": null,
        "id_code": null,
        "is_client": null,
        "is_supplier": null,
        "vatno": null
    }
}
Adding new contact
https://#companyname#.scoro.ee/api/contacts/modify
{
    "status": "OK",
    "statusCode": "200",
    "messages": null,
    "data": {
        "contact_id": "236",
        "name": "Testing 123",
        "id_code": "",
        "bankaccount": null,
        "birthday": null,
        "position": null,
        "comments": null,
        "sex": null,
        "vatno": null
    }
}

Contact relations

This API is deprecated. Use general Relations API instead.

This API can be used to list, modify and delete relations between companies and persons.

List requests: either company_id or person_id must be provided and the result will contain an array of related contact ID-s in the other field.
Modify requests: must provide contact ID in one field and an array of related contact ID-s in the other field.
Delete requests: can provide one contact ID or both ID-s to remove all relations from contact or just one specific relation.
Name Type Description
company_id Integer or Array Company ID(s)
person_id Integer or Array Person ID(s)

Available actions are

list
modify
delete
Getting list of related persons
https://#companyname#.scoro.ee/api/contactRelations/ Request
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "company_id": 1
    }
}
Response
{
    "status": "OK",
    "statusCode": "200",
    "messages": null,
    "data": {
        "person_id": [
            "2",
            "3",
            "4"
        ]
    }
}
Adding related company to person
https://#companyname#.scoro.ee/api/contactRelations/modify Request
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "person_id": 5,
        "company_id": [
            6
        ]
    }
}
Response
{
    "status": "OK",
    "statusCode": "200",
    "messages": null,
    "data": null
}
Deleting relation between company and person
https://#companyname#.scoro.ee/api/contactRelations/delete Request
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "person_id": 5,
        "company_id": 6
    }
}
Response
{
    "status": "OK",
    "statusCode": "200",
    "messages": null,
    "data": null
}

Relations

This API can be used to list, modify and delete relations between objects (for example companies and persons).

Every request must provide the type of relation to operate on. Supported relation types:
Modify requests: will add relations between object_id and values in related_objects
Delete requests: if related_objects is specified will delete only those relations, otherwise all relations are removed from object_id

Name Type Description
object_id Integer Main object ID
related_objects Object Object containing related objects ID-s for each type on list request. Array of ID-s on modify/delete request.
type String Relation objects type. Required on every request.

Available actions are

list
modify
delete
Getting list of company's related contacts
https://#companyname#.scoro.ee/api/relations/ Request
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "object_id": 1,
        "type": "contacts"
    }
}
Response
{
    "status": "OK",
    "statusCode": "200",
    "messages": null,
    "data": {
        "related_objects": {
            "company": [
                "2",
                "3"
            ],
            "person": [
                "4"
            ]
        }
    }
}
Adding related company to a company
https://#companyname#.scoro.ee/api/relations/modify Request
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "object_id": 5,
        "related_objects": [
            6
        ],
        "type": "contacts"
    }
}
Response
{
    "status": "OK",
    "statusCode": "200",
    "messages": null
}
Deleting relation between two contacts
https://#companyname#.scoro.ee/api/relations/delete Request
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "object_id": 7,
        "related_objects": [
            8
        ],
        "type": "contacts"
    }
}
Response
{
    "status": "OK",
    "statusCode": "200",
    "messages": null
}

Events & tasks

Name Type Description
activity_id Integer Activity ID
event_id Integer Event ID
event_type String Event type. Possible values: task, cal.
event_name String Event name.
description String Event description.
is_personal Boolean If event is personal or work related.
priority_id Integer Priority of the task. Possible values: 1 -> high, 2 -> normal, 3 -> low.
project_id Integer Related project ID.
company_id Integer Related company ID.
person_id Integer Related person ID.
invoice_id Integer Related invoice ID.
order_id Integer Related order ID.
quote_id Integer Related quote ID.
purchase_order_id Integer Related purchase order ID.
rent_order_id Integer Related rental order ID.
bill_id Integer Related bill ID.
start_datetime Datetime (YYYY-mm-dd HH:ii:ss) Events start time. Used only for calendar events.
end_datetime Datetime (YYYY-mm-dd HH:ii:ss) Events end time. Used only for calendar events.
full_day_event Boolean If this is a full day event.
duration_planned Time (HH:ii:ss) Events or tasks planned duration. Rounded to the nearest minute.
duration_actual Time (HH:ii:ss) Tasks actual duration. This field is read only - it is calculated based on task time entries.
billable_hours Time (HH:ii:ss) Events billable duration. Rounded to nearest minute.
datetime_due Datetime (YYYY-mm-dd HH:ii:ss) .
owner_id Integer User ID of the user that is responsible for the event.
assigned_to Integer User ID of the user performing the assigned task.
is_completed Boolean Is completed. Used only for tasks.
datetime_completed Datetime (YYYY-mm-dd HH:ii:ss) Tasks completion time. Used only for tasks. Has value if task is completed.
status_id Integer Deprecated Task status. Used only for tasks. Possible values: 1 -> in progress, 3 -> completed.
status String Event status. Possible values for events: busy, free, tentative, outofoffice. Possible values for tasks: task_status1, task_status2, task_status3, task_status4.
cal_user Array Users related with this event. Used only for calendar events. Populated only on view requests.
time_entries Array Array of tasks' time entries. Used only for tasks. Populated only on view requests.
resources Array Array of resources related to calendar event. Used only for calendar event. Populated only on view requests.
modified_date Datetime (YYYY-mm-dd HH:ii:ss) The date when event was last modified.
permissions Array Object user permissions. Used only for user based API
custom_fields Object Custom fields. Only filled on view requests.
is_deleted Boolean Is deleted. Use 'include_deleted = 1' in request object to get deleted objects to response as well.

Available actions are

list
modify
view
delete
Request URL
https://#companyname#.scoro.ee/api/events

Time entries

Name Type Description
time_entry_id Integer Time entry ID.
description String Description.
title String Time Entry title. It will be constructed dynamically based on description and activity id values.
user_id Integer Related user ID.
activity_id Integer Related activity ID.
invoice_line_id Integer Related invoice line ID.
start_datetime Datetime (YYYY-mm-dd HH:ii:ss) Planned start date and time.
end_datetime Datetime (YYYY-mm-dd HH:ii:ss) Planned end date and time.
duration Time (HH:ii:ss) Time entry duration. Rounded to the nearest minute.
billable_duration Time (HH:ii:ss) Billable duration for time entry. Only used if site has billable hours feature activated. Rounded to the nearest minute.
is_completed Boolean Is the time entry completed or not.
is_confirmed Boolean Is the time entry confirmed or not.
completed_datetime Datetime (YYYY-mm-dd HH:ii:ss) Date and time when the time entry was completed. Will be set to current time, if time entry is completed and no datetime provided.
is_deleted Boolean Is deleted. Use 'include_deleted = 1' in request object to get deleted objects to response as well.
deleted_date Datetime (YYYY-mm-dd HH:ii:ss) The date when object was deleted.

Event Resources

Name Type Description
resource_id Integer Event resource ID.
resource_name String Event resource name.
resource_color String Event resource colour set in Scoro. Format is in hex "#ffffff"
modified_date Datetime (YYYY-mm-dd HH:ii:ss) The date when resource was last modified.

Available actions are

list
view
Request URL
https://#companyname#.scoro.ee/api/eventsResources

Invoices

Name Type Description
payment_type String Payment type, possible values are banktransfer, cash, cardpayment, credit, barter
fine String Fine percent per day
quote_id Deprecated Integer Related quote ID.
order_id Deprecated Integer Related order ID.
credited_invoices Array Credited invoices ID-s. Multiple invoices can be linked with one credit invoice.
prepayment_sum Float Prepayment sum (only for view command).
real_estate_id Integer Related real estate ID.
reference_no String Invoice reference number.
id Integer Document ID
no Integer Document number.
discount Float Overall discount.
discount2 Float or None First additional discount.
discount3 Float or None Second additional discount.
sum Decimal (15,2) Total sum after discounts without VAT. This value is ignored on modify and calculated from rows instead.
vat_sum Decimal (15,2) Total VAT sum. This value is ignored on modify and calculated from rows instead.
vat Decimal(5,3) VAT percent. Only used if line based VAT setting is not activated.
vat_code_id Invoice default vat_code_id
company_id Integer ID of the related client.
person_id Integer ID of the related contact person.
company_address_id Integer If a company has multiple addresses, use this field to set which address is used on the document. If company_address_id is not specified, default address will be used.
interested_party_id Integer ID of the interested party. Only used if site has interested party feature activated.
interested_party_address_id Integer See company_address_id. Only used if site has interested party feature activated.
project_id Integer ID of the related project. If ID is -1 then each document line can have a different related project.
currency String Used currency. The default currency for site is used on modify if currency is missing or invalid.
owner_id Integer User ID of the user that is responsible for the document.
date Date (YYYY-mm-dd) Document date
deadline Date (YYYY-mm-dd) Document deadline
status String Status of the document (paid, unpaid)
description String Document description
account_id String Related company account. The account from the main request object is used on modify.
is_sent Boolean If document is sent. (Cannot unset when document is sent via Scoro)
lines Array Document lines. Lines will be null for list request and is only filled for view requests.
modified_date Datetime (YYYY-mm-dd HH:ii:ss) The date when document was last modified.
custom_fields Object Custom fields. Only filled on view requests.
is_deleted Boolean Is deleted. Use 'include_deleted = 1' in request object to get deleted objects to response as well.
deleted_date Datetime (YYYY-mm-dd HH:ii:ss) The date when object was deleted.

Available actions are

list
modify
view
delete
Request URL
https://#companyname#.scoro.ee/api/invoices

Invoice lines

Name Type Description
depot_amounts Array Array of objects containing the fields depot_id, amount, serial_no for each depot from which products should be taken.
id Integer Document line ID
product_id Integer ID of the product.
comment String Line comment.
comment2 String Second line comment. Only used if "Use additional comments on lines" setting is activated.
price Decimal (15,4) Unit price.
amount Decimal (15,2) Amount.
amount2 Decimal (15,2) Additional amount. Only used if "Use additional amount" setting is activated.
discount Float Line discount. Only used if "Use line based discount" setting is activated.
sum Decimal (15,2) Line sum without VAT.
vat Decimal (5,2) Line tax percent. Only used if "Use line based tax rates" setting is activated.
vat_code_id Integer Line tax id. Only used if "Use line based tax rates" setting is activated.
unit String Unit name.
finance_object_id Integer ID of the related accounting object. Only used if "Use accounting objects" setting is activated.
finance_account_id Integer ID of the related finance account. Only used if "Use finance accounts" setting is activated.
cost Decimal(15,4) Line cost. Only used if "Use margin" setting is activated.
supplier_id Integer ID of the contact supplying the product on this line. Only used if "Use margin" setting is activated.
project_id Integer ID of the related project.
custom_fields Object Custom fields. Only filled on view requests.

Prepayments

Name Type Description
fine String Fine percent per day
quote_id Integer Related quote ID.
order_id Integer Related order ID.
prepayment_percent Float Percent to pay in advance.
id Integer Document ID
no Integer Document number.
discount Float Overall discount.
discount2 Float or None First additional discount.
discount3 Float or None Second additional discount.
sum Decimal (15,2) Total sum after discounts without VAT. This value is ignored on modify and calculated from rows instead.
vat_sum Decimal (15,2) Total VAT sum. This value is ignored on modify and calculated from rows instead.
vat Decimal(5,3) VAT percent. Only used if line based VAT setting is not activated.
vat_code_id Invoice default vat_code_id
company_id Integer ID of the related client.
person_id Integer ID of the related contact person.
company_address_id Integer If a company has multiple addresses, use this field to set which address is used on the document. If company_address_id is not specified, default address will be used.
interested_party_id Integer ID of the interested party. Only used if site has interested party feature activated.
interested_party_address_id Integer See company_address_id. Only used if site has interested party feature activated.
project_id Integer ID of the related project. If ID is -1 then each document line can have a different related project.
currency String Used currency. The default currency for site is used on modify if currency is missing or invalid.
owner_id Integer User ID of the user that is responsible for the document.
date Date (YYYY-mm-dd) Document date
deadline Date (YYYY-mm-dd) Document deadline
status String Status of the document (paid, unpaid)
description String Document description
account_id String Related company account. The account from the main request object is used on modify.
is_sent Boolean If document is sent. (Cannot unset when document is sent via Scoro)
lines Array Document lines. Lines will be null for list request and is only filled for view requests.
modified_date Datetime (YYYY-mm-dd HH:ii:ss) The date when document was last modified.
custom_fields Object Custom fields. Only filled on view requests.
is_deleted Boolean Is deleted. Use 'include_deleted = 1' in request object to get deleted objects to response as well.
deleted_date Datetime (YYYY-mm-dd HH:ii:ss) The date when object was deleted.

Available actions are

list
modify
view
delete
Request URL
https://#companyname#.scoro.ee/api/invoices/prepayments

Prepayment lines

Name Type Description
id Integer Document line ID
product_id Integer ID of the product.
comment String Line comment.
comment2 String Second line comment. Only used if "Use additional comments on lines" setting is activated.
price Decimal (15,4) Unit price.
amount Decimal (15,2) Amount.
amount2 Decimal (15,2) Additional amount. Only used if "Use additional amount" setting is activated.
discount Float Line discount. Only used if "Use line based discount" setting is activated.
sum Decimal (15,2) Line sum without VAT.
vat Decimal (5,2) Line tax percent. Only used if "Use line based tax rates" setting is activated.
vat_code_id Integer Line tax id. Only used if "Use line based tax rates" setting is activated.
unit String Unit name.
finance_object_id Integer ID of the related accounting object. Only used if "Use accounting objects" setting is activated.
finance_account_id Integer ID of the related finance account. Only used if "Use finance accounts" setting is activated.
cost Decimal(15,4) Line cost. Only used if "Use margin" setting is activated.
supplier_id Integer ID of the contact supplying the product on this line. Only used if "Use margin" setting is activated.
project_id Integer ID of the related project.
custom_fields Object Custom fields. Only filled on view requests.

Receipt Groups

Receipts can only be added. Existing receipts can't be modified. This means the request must not contain id on modify requests.
Name Type Description
id Integer Document ID
date Date (YYYY-mm-dd) Receipt date.
contact_id Integer Related contact ID.
sum Decimal (15,2) Receipt sum.
currency String ISO 4217 currency code. System default is used if no currency given.
sales_doc_type String doc type for receipt. Possible values "invoices", "bills". Default "invoices".
receipt_account_id Integer Receipt account ID.
receipts Array Receipts.
modified_date Datetime (YYYY-mm-dd HH:ii:ss) The date when receipt group was last modified.
custom_fields Object Custom fields. Only filled on view requests.
is_deleted Boolean Is deleted. Use 'include_deleted = 1' in request object to get deleted objects to response as well.
deleted_date Datetime (YYYY-mm-dd HH:ii:ss) The date when object was deleted.

Available actions are

list
modify
delete
Request URL
https://#companyname#.scoro.ee/api/receipts
Sample list request for contact id 1
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "filter": {
        "contact_id": "1"
    }
}
Sample add new receiptGroup request
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "date": "2013-10-18",
        "contact_id": "12",
        "sum": "123.00",
        "currency": "EUR",
        "receipts": [
            {
                "date": "2013-10-18",
                "invoice_id": "96",
                "sum": "100.00"
            },
            {
                "date": "2013-10-18",
                "invoice_id": "102",
                "sum": "23.00"
            }
        ]
    }
}

Receipts

Name Type Description
receipt_id Integer Receipt ID.
date Date (YYYY-mm-dd) Receipt date.
invoice_id Integer Related invoice ID.
prepayment_id Integer Related prepayment invoice ID.
sum Decimal (15,2) Receipt sum.
sales_doc_type String doc type for receipt. Possible values "invoices", "bills". Default "invoices".
contact_id Integer Related contact ID.
contact_name String Related contact name.

Receipt Accounts

Receipt account information can only be viewed.
Name Type Description
id Integer Receipt account ID.
name String Name of the service provider.
type String Type of service provider.

Available actions are

list
Request URL
https://#companyname#.scoro.ee/api/receiptAccounts
Sample list request for receipt account with id 1
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "filter": {
        "id": "1"
    }
}

Quotes

Name Type Description
confirmed_date Datetime (YYYY-mm-dd HH:ii:ss) Quote confirmed date.
id Integer Document ID
no Integer Document number.
discount Float Overall discount.
discount2 Float or None First additional discount.
discount3 Float or None Second additional discount.
sum Decimal (15,2) Total sum after discounts without VAT. This value is ignored on modify and calculated from rows instead.
vat_sum Decimal (15,2) Total VAT sum. This value is ignored on modify and calculated from rows instead.
vat Decimal(5,3) VAT percent. Only used if line based VAT setting is not activated.
vat_code_id Invoice default vat_code_id
company_id Integer ID of the related client.
person_id Integer ID of the related contact person.
company_address_id Integer If a company has multiple addresses, use this field to set which address is used on the document. If company_address_id is not specified, default address will be used.
interested_party_id Integer ID of the interested party. Only used if site has interested party feature activated.
interested_party_address_id Integer See company_address_id. Only used if site has interested party feature activated.
project_id Integer ID of the related project. If ID is -1 then each document line can have a different related project.
currency String Used currency. The default currency for site is used on modify if currency is missing or invalid.
owner_id Integer User ID of the user that is responsible for the document.
date Date (YYYY-mm-dd) Document date
deadline Date (YYYY-mm-dd) Document deadline
status String Status of the document (approved, completed, declined, incomplete, pending, ready)
description String Document description
account_id String Related company account. The account from the main request object is used on modify.
is_sent Boolean If document is sent. (Cannot unset when document is sent via Scoro)
lines Array Document lines. Lines will be null for list request and is only filled for view requests.
modified_date Datetime (YYYY-mm-dd HH:ii:ss) The date when document was last modified.
custom_fields Object Custom fields. Only filled on view requests.
is_deleted Boolean Is deleted. Use 'include_deleted = 1' in request object to get deleted objects to response as well.
deleted_date Datetime (YYYY-mm-dd HH:ii:ss) The date when object was deleted.

Available actions are

list
modify
view
delete
Request URL
https://#companyname#.scoro.ee/api/quotes

Quote lines

Name Type Description
dates Object Object with dates as keys and amounts as values. Empty on list requests.
is_confirmed boolean Quote line confirmation state
id Integer Document line ID
product_id Integer ID of the product.
comment String Line comment.
comment2 String Second line comment. Only used if "Use additional comments on lines" setting is activated.
price Decimal (15,4) Unit price.
amount Decimal (15,2) Amount.
amount2 Decimal (15,2) Additional amount. Only used if "Use additional amount" setting is activated.
discount Float Line discount. Only used if "Use line based discount" setting is activated.
sum Decimal (15,2) Line sum without VAT.
vat Decimal (5,2) Line tax percent. Only used if "Use line based tax rates" setting is activated.
vat_code_id Integer Line tax id. Only used if "Use line based tax rates" setting is activated.
unit String Unit name.
finance_object_id Integer ID of the related accounting object. Only used if "Use accounting objects" setting is activated.
finance_account_id Integer ID of the related finance account. Only used if "Use finance accounts" setting is activated.
cost Decimal(15,4) Line cost. Only used if "Use margin" setting is activated.
supplier_id Integer ID of the contact supplying the product on this line. Only used if "Use margin" setting is activated.
project_id Integer ID of the related project.
custom_fields Object Custom fields. Only filled on view requests.

Orders

Name Type Description
quote_id Integer Related quote ID.
id Integer Document ID
no Integer Document number.
discount Float Overall discount.
discount2 Float or None First additional discount.
discount3 Float or None Second additional discount.
sum Decimal (15,2) Total sum after discounts without VAT. This value is ignored on modify and calculated from rows instead.
vat_sum Decimal (15,2) Total VAT sum. This value is ignored on modify and calculated from rows instead.
vat Decimal(5,3) VAT percent. Only used if line based VAT setting is not activated.
vat_code_id Invoice default vat_code_id
company_id Integer ID of the related client.
person_id Integer ID of the related contact person.
company_address_id Integer If a company has multiple addresses, use this field to set which address is used on the document. If company_address_id is not specified, default address will be used.
interested_party_id Integer ID of the interested party. Only used if site has interested party feature activated.
interested_party_address_id Integer See company_address_id. Only used if site has interested party feature activated.
project_id Integer ID of the related project. If ID is -1 then each document line can have a different related project.
currency String Used currency. The default currency for site is used on modify if currency is missing or invalid.
owner_id Integer User ID of the user that is responsible for the document.
date Date (YYYY-mm-dd) Document date
deadline Date (YYYY-mm-dd) Document deadline
status String Status of the document (approved, completed, declined, incomplete, pending)
description String Document description
account_id String Related company account. The account from the main request object is used on modify.
is_sent Boolean If document is sent. (Cannot unset when document is sent via Scoro)
lines Array Document lines. Lines will be null for list request and is only filled for view requests.
modified_date Datetime (YYYY-mm-dd HH:ii:ss) The date when document was last modified.
custom_fields Object Custom fields. Only filled on view requests.
is_deleted Boolean Is deleted. Use 'include_deleted = 1' in request object to get deleted objects to response as well.
deleted_date Datetime (YYYY-mm-dd HH:ii:ss) The date when object was deleted.

Available actions are

list
modify
view
delete
Request URL
https://#companyname#.scoro.ee/api/orders

Order lines

Name Type Description
dates Object Object with dates as keys and amounts as values. Empty on list requests.
id Integer Document line ID
product_id Integer ID of the product.
comment String Line comment.
comment2 String Second line comment. Only used if "Use additional comments on lines" setting is activated.
price Decimal (15,4) Unit price.
amount Decimal (15,2) Amount.
amount2 Decimal (15,2) Additional amount. Only used if "Use additional amount" setting is activated.
discount Float Line discount. Only used if "Use line based discount" setting is activated.
sum Decimal (15,2) Line sum without VAT.
vat Decimal (5,2) Line tax percent. Only used if "Use line based tax rates" setting is activated.
vat_code_id Integer Line tax id. Only used if "Use line based tax rates" setting is activated.
unit String Unit name.
finance_object_id Integer ID of the related accounting object. Only used if "Use accounting objects" setting is activated.
finance_account_id Integer ID of the related finance account. Only used if "Use finance accounts" setting is activated.
cost Decimal(15,4) Line cost. Only used if "Use margin" setting is activated.
supplier_id Integer ID of the contact supplying the product on this line. Only used if "Use margin" setting is activated.
project_id Integer ID of the related project.
custom_fields Object Custom fields. Only filled on view requests.

Expenses

Name Type Description
no String Document number.
id Integer Document ID
discount Float Overall discount.
discount2 Float or None First additional discount.
discount3 Float or None Second additional discount.
sum Decimal (15,2) Total sum after discounts without VAT. This value is ignored on modify and calculated from rows instead.
vat_sum Decimal (15,2) Total VAT sum. This value is ignored on modify and calculated from rows instead.
vat Decimal(5,3) VAT percent. Only used if line based VAT setting is not activated.
vat_code_id Integer Invoice default vat_code_id
company_id Integer ID of the related client.
person_id Integer ID of the related contact person.
company_address_id Integer If a company has multiple addresses, use this field to set which address is used on the document. If company_address_id is not specified, default address will be used.
project_id Integer ID of the related project. If ID is -1 then each document line can have a different related project.
currency String Used currency. The default currency for site is used on modify if currency is missing or invalid.
owner_id Integer User ID of the user that is responsible for the document.
date Date (YYYY-mm-dd) Document date
deadline Date (YYYY-mm-dd) Document deadline
status String Status of the document (paid, unpaid)
description String Document description
account_id String Related company account. The account from the main request object is used on modify.
lines Array Document lines. Lines will be null for list request and is only filled for view requests.
modified_date Datetime (YYYY-mm-dd HH:ii:ss) The date when document was last modified.
custom_fields Object Custom fields. Only filled on view requests.
is_deleted Boolean Is deleted. Use 'include_deleted = 1' in request object to get deleted objects to response as well.
deleted_date Datetime (YYYY-mm-dd HH:ii:ss) The date when object was deleted.

Available actions are

list
modify
view
delete
Request URL
https://#companyname#.scoro.ee/api/expenses

Expense lines

Name Type Description
id Integer Document line ID
product_id Integer ID of the product.
comment String Line comment.
comment2 String Second line comment. Only used if "Use additional comments on lines" setting is activated.
price Decimal (15,4) Unit price.
amount Decimal (15,2) Amount.
amount2 Decimal (15,2) Additional amount. Only used if "Use additional amount" setting is activated.
discount Float Line discount. Only used if "Use line based discount" setting is activated.
sum Decimal (15,2) Line sum without VAT.
vat Decimal (5,2) Line tax percent. Only used if "Use line based tax rates" setting is activated.
vat_code_id Integer Line tax id. Only used if "Use line based tax rates" setting is activated.
unit String Unit name.
finance_object_id Integer ID of the related accounting object. Only used if "Use accounting objects" setting is activated.
finance_account_id Integer ID of the related finance account. Only used if "Use finance accounts" setting is activated.
project_id Integer ID of the related project.
custom_fields Object Custom fields. Only filled on view requests.

Products

Name Type Description
product_id Integer Product ID
code String Product code.
name String Product name in the language specified in request object. This field is used for view and list requests only. Modify requests should put the names to the field "names" (see example).
price Decimal (15,4) Product price. Price list id can be specified in the "price_list" field of the request object. Default price list will be used if "price_list" field is not set.
buying_price Decimal (15,4) Product buying price.
description String Product description. Modify requests support descriptions in multiple languages (see example).
description2 String Product additional description. Modify requests support additional descriptions in multiple languages (same as description field).
tag String Product tag.
url String Product URL.
supplier_id Integer Product supplier ID. Only used if extra field "Supplier" is activated.
productgroup_id Integer Product group ID. Only used if "Use product extras" setting is activated.
is_active Boolean If product is active or deactivated.
is_service Boolean If product is service or not.
default_vat_code_id Integer Default vat code. This applies to both default sales tax and purchases tax if aforementioned
default_sales_tax_id Integer Default sales vat code. This only applies to sales documents.
default_purchases_tax_id Integer Default purchases vat code. This only applies to purchase documents.
accounting_object_id Integer Product default accounting object. Only used if "Use accounting objects" setting is activated.
depots_total_amount Decimal (15,4) Total amount in all depots. Only used if site has "Depot" feature. To modify depot amounts use the depot_amounts field.
depot_amounts Object Amounts for each depot (depot ID as key and amount as value). Only used if site has "Depot" feature. This will be null on list requests.
pictures Array Product pictures. Only used if "Use product extras" setting is activated. This will be null on list requests.
modified_date Datetime (YYYY-mm-dd HH:ii:ss) The date when project was last modified.
custom_fields Object Custom fields. Only filled on view requests.
is_deleted Boolean Is deleted. Use 'include_deleted = 1' in request object to get deleted objects to response as well.
deleted_date Datetime (YYYY-mm-dd HH:ii:ss) The date when object was deleted.

Available actions are

list
modify
view
delete
Request URL
https://#companyname#.scoro.ee/api/products
Sample modify request using price list id 1
https://#companyname#.scoro.ee/api/products/modify
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "product_id": "151",
        "code": "987654321",
        "price": "321.54",
        "price_list": "1",
        "names": {
            "est": "Toode1",
            "eng": "Product1"
        },
        "description": {
            "est": "Kirjeldus1",
            "eng": "Description1"
        }
    }
}
Sample view request using price list id 2
https://#companyname#.scoro.ee/api/products/modify
{
    "apiKey": "API_hash",
    "lang": "est",
    "company_account_id": "tutorial",
    "request": {
        "price_list": 2
    }
}
Sample modify request with depot amounts
https://#companyname#.scoro.ee/api/products/modify
{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "price": "123.45",
        "names": {
            "est": "Toode",
            "eng": "Product"
        },
        "depot_amounts": {
            "1": "5.00",
            "2": "2.00"
        }
    }
}

Product groups

Name Type Description
id Integer Product group ID
parent_group_id Integer Parent product group ID. 0 if this group has no parent group.
name String Group name in the language specified in request object.
comments String Productgroup description.
pcs_per_package Integer Products in this productgroup.
account_name String Account for external connections.

Available actions are

list
view
modify
Request URL
https://#companyname#.scoro.ee/api/productGroups

Price lists

Name Type Description
id Integer Price list ID
name String Price list name.
currency String Price list currency.

Available actions are

list
view
Request URL
https://#companyname#.scoro.ee/api/priceLists

Depot

Name Type Description
depot_id Integer Depot ID.
depot_name String Depot name.
comments String Depot comments/description.

Available actions are

list
view
Request URL
https://#companyname#.scoro.ee/api/depot

Projects

Name Type Description
project_id Integer Project ID
no Integer Project number.
project_name String Project name.
description String Project description.
company_id Integer Related company ID.
is_personal Boolean If project is personal or business related.
is_private Boolean If project is public or only for project members
color String Project color identifier. Format is in hex "#ffffff"
status String Project status. Possible values: pending, inprogress, cancelled, completed, future, additional1, additional2, additional3, additional4
manager_id Integer Project manager ID.
date Date (YYYY-mm-dd) Project start date.
deadline Date (YYYY-mm-dd) Project deadline.
duration Time (HH:ii:ss) Project estimated duration.
account_id String Related account. Empty if project is shared between accounts.
modified_date Datetime (YYYY-mm-dd HH:ii:ss) The date when project was last modified.
tags Array Array of project tags. Not used on list requests.
custom_fields Object Custom fields. Only filled on view requests.
is_deleted Boolean Is deleted. Use 'include_deleted = 1' in request object to get deleted objects to response as well.

Available actions are

list
modify
view
delete
Request URL
https://#companyname#.scoro.ee/api/projects

Users

Name Type Description
id Integer User ID.
username String Username.
firstname String First name.
lastname String Last name.
initials String Initials.
email String Email address.
is_active Boolean If user is active or deactivated.
birthday Date (YYYY-mm-dd) Users birthday.
category String User category. Possible values: user, admin.
position String User job/position.
modified_date Datetime (YYYY-mm-dd HH:ii:ss) The date when user was last modified.

Available actions are

list
view
Request URL
https://#companyname#.scoro.ee/api/users

VAT Codes

Name Type Description
vat_code_id Integer Tax rate ID
vat_code String Tax rate code
percent Decimal (5,3) Tax rate percent
vat_name String Tax rate name
is_sales Boolean Is sales type tax rate (can be used in sales type documents)
is_purchases Boolean Is purchase type rax rate (can be used in purchase type documents)

Available actions are

list
view
Request URL
https://#companyname#.scoro.ee/api/vatCodes

Accounting objects

Name Type Description
object_id Integer Accounting object ID
object_symbol String symbol
name String name
parent_group_name String parent group name

Available actions are

list
view
Request URL
https://#companyname#.scoro.ee/api/financeObjects