Scoro API v1

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:

• Billing for your application or service
• Custom import tools (SalesForce, QuickBooks, CSV, etc.)
• Revenue analysis
• Service URL

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

Full url depends on the info requested.

Sample URL

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

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

• Field types for quote_id and order_id in Invoices are deprecated and will be type of Array in v2 API

Changes from version 18.1

• Field duration added to Projects

Changes from version 17.2

• Field deleted_date added to Invoices, Prepayments, Quotes and Orders
• Field is_sent added to Invoices, Prepayments, Quotes and Orders

Changes from version 16.5

• Field person_id added to Invoices, Prepayments, Quotes and Orders
• resource_colour named to resource_color in Event Resources
• real_estate_id added to Invoices
• dates added to Order lines
• modified_date added to Receipt Groups
• full_address added to Contacts addresses
• invoice_line_id added to Time Entries

Changes from version 16.4

• Fields is_private, tags and color added to Projects

Changes from version 16.3

• Fields company_address_id and interested_party_address_id added to Invoices, Prepayments, Quotes and Orders
• Field is_deleted added to Events, Time entries, Projects,Invoices, Prepayments, Quotes, Orders, Bills and Products model.
  Use parameter "include_deleted = 1" in the request object to include them in the result.
• For "view" actions, using /view/#id in request URL is mandatory.
• Field custom_fields added to Invoice lines, Prepayment lines, Quote lines, Order lines and Bill lines model.

Changes from version 16.2

• Field accounting_object_id added to Products model.

Changes from version 16.1

• Field reference_no added to Contacts model.
• Field datetime_completed added to Events model.

Changes from version 15.4

• Added Event resources model and resources field to Events model.
• Additional check to salesdocs (invoices, prepayments, quotes, orders, bills) when creating new entry. company_id must now refer to an existing contacts id.
• Added time to modified_date fields.

Changes from version 15.3

• Field timezone added to Contacts model.
• Field owner_id is now required for Invoices, Orders, Quotes models.

Changes from version 15.2

• Field credited_invoices added to Invoices model. Multiple invoice ID-s can be linked with credit invoice. Field credited_invoice_id is removed.
• Field is_completed added to Events model. Field status_id is deprecated and will be removed in future versions.
• Added Time entries model and time_entries field to Events model.
• Fields duration_actual and billable_hoursin Events model are now read-only for tasks and calculated based on tasks time entries.
• Added Relations API. Contact relations is deprecated.

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:

• lang - language for results
• apiKey OR user_token- a unique key used for authentication
• company_account_id - specifies which company account's data is used

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:

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

{
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {}
}

{
    "status": "ERROR",
    "statusCode": "401",
    "messages": {
        "error": [
            "Missing Api Key"
        ]
    }
}

Bad request parameters

{
    "apiKey": "wrong",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {}
}

{
    "status": "ERROR",
    "statusCode": "403",
    "messages": {
        "error": [
            "Wrong Api Key"
        ]
    }
}

There was a problem on our end

{
    "apiKey": "API_hash",
    "lang": "abc",
    "company_account_id": "tutorial",
    "request": {}
}

{
    "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

{
    "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

{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial"
}

{
    "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
        }
    ]
}

{
    "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
    }
}

{
    "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
    }
}

{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "company_id": 1
    }
}

{
    "status": "OK",
    "statusCode": "200",
    "messages": null,
    "data": {
        "person_id": [
            "2",
            "3",
            "4"
        ]
    }
}

{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "person_id": 5,
        "company_id": [
            6
        ]
    }
}

{
    "status": "OK",
    "statusCode": "200",
    "messages": null,
    "data": null
}

{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "person_id": 5,
        "company_id": 6
    }
}

{
    "status": "OK",
    "statusCode": "200",
    "messages": null,
    "data": null
}

{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "object_id": 1,
        "type": "contacts"
    }
}

{
    "status": "OK",
    "statusCode": "200",
    "messages": null,
    "data": {
        "related_objects": {
            "company": [
                "2",
                "3"
            ],
            "person": [
                "4"
            ]
        }
    }
}

{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "object_id": 5,
        "related_objects": [
            6
        ],
        "type": "contacts"
    }
}

{
    "status": "OK",
    "statusCode": "200",
    "messages": null
}

{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "request": {
        "object_id": 7,
        "related_objects": [
            8
        ],
        "type": "contacts"
    }
}

{
    "status": "OK",
    "statusCode": "200",
    "messages": null
}

{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "filter": {
        "contact_id": "1"
    }
}

{
    "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"
            }
        ]
    }
}

{
    "apiKey": "API_hash",
    "lang": "eng",
    "company_account_id": "tutorial",
    "filter": {
        "id": "1"
    }
}

{
    "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"
        }
    }
}

{
    "apiKey": "API_hash",
    "lang": "est",
    "company_account_id": "tutorial",
    "request": {
        "price_list": 2
    }
}

{
    "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"
        }
    }
}