Got a question? We’re here to answer! If you don’t see your question here and won’t find an answer in our manuals either, send an e-mail to api@merit.ee using a reference “Merit Palk API”.
WHERE IS THE SANDBOX?!
We don’t have a sandbox.
Just create a user (if you don’t have it already) and then create a test company in Merit Palk. Companies up to 2 employees can use our program with PRO functionality for free.
HOW TO START?
Just take Node.js example. Put your API ID and Key in. Play with different payloads. You’ll get this.
If you need and want, we can offer you a Merit Palk tutorial to get better acquainted with the program logic and with the basic payroll rules. Contact us api@merit.ee for more information using a reference “Merit Palk API”.
API ID AND KEY?
Yes. Log into Merit Palk and go to Settings > API Settings. Create an API Key. Use that key. Once your integration is working, you can create API credentials in the live database and start using those.
API ID and API Key are unique for every company and for every API connection. You should keep your API ID and Key secret and guard them as you would your regular account passwords. If you feel your ID and Key have been compromised, you can reset them and generate a new API ID and Key.
REQUEST PARAMETERS?
For every API request you make, you’ll need to include ApiID, timestamp and signature as request parameters. Signature is in Base64 format and is calculated using your ApiKey with HMAC-SHA-256, based on the ApiID+timestamp+RequestJSON.
REQUEST LIMITS?
There is no limit on the number of API requests per day. However, requests will be rate-limited if too many calls are made within a short period of time. Additionally, a maximum of 100 results will be returned for growing list methods.
GET OR POST?
All Merit Palk API requests are composed of JSON and delivered as an HTTP POST request to the endpoint URL.
IS THE SERVICE RUNNING?
Yes. Merit Palk has ~ 20 successful integrators. Every day we receive many requests. It’s online and running.
ERROR 400
The data sent to the API is not appropriate. Message tag will give you more info about what went wrong.
ERROR 401
Two possible reasons:
(1) Whether API ID or the signature was incorrect;
(2) Merit Palk user do not have a PRO license.
It could also be that someone has meanwhile changed the API ID and API Key for security reasons thus making the “old” IDs and Keys obsolete.
ERROR 404
Two possible reasons:
(1) The URL is invalid;
(2) You’re missing one of the required parameters.
URL has to be like this: “https://Palk.merit.ee/api/v1/” + endpoint + “?ApiId=” + APIID + “×tamp=” + TIMESTAMP + “&signature=” + APIKEY
HOW DO I KNOW IF THE REQUEST WAS SUCCESSFUL?
A successful response is represented as JSON with response code 200. In many cases, when needed and possible, a response will also include details of fulfilled requests.
ARE THERE ANY COSTS ADDED FOR API?
No extra fees are added for using API today, but you do need the Merit Palk PRO package. For testing purposes companies up to 2 employees can use our program with PRO functionality for free.
WHAT DOES TYPECODES, IMPORT CODES, IMPORT ID’S etc MEAN?
The TypeCodes or import ID’s are given in most cases by the user for different salary or withholding types they use OR for contracts if one employee has multiple contracts or company wants to use custom employee ID’s not their personal ID’s given by the State. In some cases (for example adding absences) Merit will provide TypeCodes for you.
Salaries, withholdings and contract Import ID’s have to be found prior to sending data via API in Merit Palk system. You can add import ID’s to the corresponding card in Merit Palk. For example, salary type import ID has to be added to that salary type card which you will be sending data for. See the detail description on how to create new salary and withholding types in Merit Palk in next paragraph.
All type codes and import IDs the user uses, have to be a number value (up to 13 numbers long), for example “0000123456789”. No letters or other symbols are allowed to use.
HOW TO CREATE SALARY AND WITHHOLDING TYPES IN MERIT PALK?
- You need to add suitable salary types to Merit Palk (Payroll > Salary types). You have an option of “Import ID” in the salary type details. This number must match with “Typecode” or “SalaryTypeImpCode” in cases where you send salary data .
- If the typecode is negative, it means this is withholding, and for that, you need to add withholding types to Merit Palk (Withholdings > Withholding types).
WHAT’S THE DIFFERENCE BETWEEN ENDPOINTS “SENDEMPLOYEES” AND “SENDPAYTERMS”?
API endpoint “Adding employees and their first contract” (aka “sendemployees”) are used to add new employees to Merit system and their first contracts together with their first base salary agreements info.
API endpoint “Creating base salary agreements” (aka “sendpayterms”) is used when the employee and their contract is already added to Merit and the base salary agreements gets updated overtime. Due to the fact, that there cannot be two agreements with the same start date, you cannot use this API endpoint, when you want to add first base salary agreement with the start date of a contract to the employee you added previously manually to Merit. When contract is added to Merit, the first base salary agreement is created – with the info provided by the user or with default info by the Merit.
CAN DATA BE DELETED OR OVERWRITTEN VIA API?
It has been asked very frequently from us and the answer is No.
Because the data you add or create via API will be related to so many other data in the program, so sometimes even the wrong order of deletion or change may cause mistakes and errors in you payroll calculations. That’s why at the moment, we have decided that all deletions and changes to the data must be made knowingly and manually in Merit Palk.
DO YOU SUPPORT EVENT-BASED TRIGGERS?
No, we do not support event-based triggers.
I DON’T SEE THE API ENDPOINT FOR MY NEEDS. DOES THAT MEAN I CAN’T USE MERIT PALK API?
If we don’t have the endpoint what you need already available, then definitely let us know by e-mailing us api@merit.ee using a reference “Merit Palk API”! Describe as detailed as possible what kind of endpoint you need and in what purpose.
We develop our API endpoints by our customers needs. We do not promise customers specific deadlines for the completion of endpoints, but we definitely will take your needs and propositions into consideration in making our development plans.
If we have some kind of report already available in Merit Palk, it is definitely easier to make an endpoint for that data set than make it for the new data sets which are not already available. Then we need to analyse if that kind of endpoints are possible even to provide.
HOW DO I KNOW IF SOMETHING CHANGES IN API MANUALS?
All changes that we have made and will make, will be added to our list of changes page.