FAQ

Can I use the API to delete projects or clients?
No - Runn doesn't support deleting projects or clients using the API as there is a large cascading effect from deleting. Please use the Runn web app and to confirm your choice before deleting any data.

Can I use the API to delete people?
Yes - API v1 supports deleting people but this will fail when the person has existing assignments or actuals to preserve historical reports. You can override this behaviour using the force query flag.

Can I just delete one day of a multi-day assignment?
No. You'll need to delete the whole assignment, and then recreate the remaining segments. There is no API equivalent to the “split assignment” functionality in the UI

I have an assignment that is retrievable via the API but it is not shown in the Runn app. Why is this?
Single day assignments that are on the same date as a public holiday are invisible in the UI. The hours of the assignment are disregarded in all in-app calculations. The reason they remain is incase someone deleted/moved a public holiday, the assignment is still there.

I'm receiving a 404 Not Found error message when using your API endpoints.
A 404 means you are sending your request to the wrong URL. Please check in "Settings > API" in the Runn app to confirm the URL you should use to access the Runn API.

Can I update contracts or people costs from a specific date via API?
Yes. You can create a new contract with the updated cost, with a startDate of when you want it to apply from.

How do I get the current role of a person?
Role details are contained in a person's contract.

Does the API allow for updating a contract?
No. This should align as if the contract details change, it's a new contract. For example, if a role changes, or cost changes, or hours per day, etc- a new contract with those details starting on a specific date is now in place. So the API will then automatically end the existing contract the day before the new one starts and now the new contract is in place. ​ If you need to correct a mistake in a contract, for example you the salary was entered incorrect initially. Then you can create a new contract with the same starting date and the existing one and this will overwrite it.

Additionally, you can now delete contracts, so if an existing contract is still incorrect you can delete and create a new one.

My API request stopped working. Why?

• Runn's API endpoints are rate limited. Learn more
• Your API token may have expired. Check your Settings > API screen.

How do I create an assignment with a duration of 10 hours, 8 on the first day and 2 on the second day?
You can use POST /assignments. Runn assignments have a constant number of hours per day. If you want 8 hours on day #1 and 2 hours on day #2, then you must create 2 separate assignments.

Our time sheets are entered in another system. How do I import them into Runn?
Read our Actuals Guide to learn about the different ways you can import these into Runn.

What is the best way to use the modifiedAfter to get all the available changes for our actuals?

1. If you need all of your historical actuals you'll need to page through all the results using the "cursor" parameter to get these. It's worth noting, the Runn API returns results ordered by the oldest createdAt date first. Keep track of the newest "updatedAt" value returned as you go.

When you finally get a "nextCursor" with the "null" value, do another GET with the "modifiedAfter" set to the latest "updatedAt" value without the "cursor" parameter in case there has been some updates since you started fetching your initial batch.

2. From then onwards, to get the latest changes, you can use a GET with the "modifiedAfter" query parameter always appended using the newest "updatedAt" value you have stored. That way only any new or modified actuals will be returned.

Say it's been 24 hours since you last checked for updates. So you do a GET with the "modifiedAfter" query parameter using the latest "updatedAt" value that you previously stored. If there are more than one page of results you'll need to page through all the results as before (so you'd have both a "modifiedAfter" and a "cursor" parameter in your request after the first page of results). Again, do another GET with the "modifiedAfter" query parameter using the latest "updatedAt" value at the end (without the "cursor" parameter) to be sure you've got any updates since you started paging through the latest updates.

Repeat step 2 every time you want to check for the latest changes.

If a record is changed or created whilst there are still pages available can I expect that record to appear within the set of pages being iterated through via the nextCursor, or would I need to make a new request without the nextCursor attribute?

Updates won't always been in the later pages. You'll need to make an additional request with the "modifiedAfter" parameter set to the newest "updatedAt" value and without the "cursor" parameter set.

Is it possible to set the time off type when creating Time offs through the API?
Yes. See our Time offs Endpoint Guide to learn more about which time offs you can create and which are set automatically.

Can I extract the project revenue and project cost information per month via the API?
This can be done with the API manually — we do not currently have a reporting API that does these calculations.

You will need to extract the project rates, people contract costs, the assignments and the actuals.

Ensure you calculate the values for each day separately (e.g. how many hours of assignments, how many hours of actuals, rates and costs on 2023-02-21, 2023-02-22, 2023-02-23) and then combine them into the correct periods.

Calculation Rules

1. Assignments have start and end dates that cover weekends, so they should be excluded unless “non_working_day = true”.
2. On days an assignment exists, but no corresponding actual exists, we calculate revenue/costs based on the assignment. When an actual exists, we use the actual value.
3. Scheduled Leaves can be ignored - we treat work as still occurring when it clashes with an assignment
4. Public Holidays cannot be ignored - when a public holiday for a person falls on the same day as an assignment, we 0 the value of the assignment that day. Unless the assignment has “non_working_day = true”
5. All past days of placeholder assignments are treated as 0

We understand this is a complex calculation, and we are committed to creating a reporting API in the future.

How do I get the cost per hour for a specific person?
This can be done with the API manually - we do not currently have a reporting API that does this calculation.

To calculate this, you can retrieve a person's contract(s) and check which contract is active at the time of assignment or actual and use that rate. If there is no contract then use the "Default Hourly Cost" for the role.