> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spott.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Timesheet Portal

> Publish contract placements from Spott to Timesheet Portal, so timesheets, pay and invoicing run there, and see the timesheets back on the placement.

**Timesheet Portal** is a pay and bill platform for recruitment agencies. It handles the
timesheets, invoicing and payments for your placed contractors.

The integration **sends a contract placement from Spott to Timesheet Portal** in one go: the
client, the contact who approves the timesheets, the candidate, the consultant, the placement
details and the rates. Nobody retypes the placement. The timesheets your contractors then
submit in Timesheet Portal **come back to the placement in Spott**, so you see what was worked
without logging in to a second system.

With the integration you can:

* **Connect your Timesheet Portal account once** for the whole workspace.
* **Publish a contract placement** straight from the placement record, and **update** it later.
* **Review and complete** the client, contact, candidate, consultant, placement and rate
  details before they are sent.
* **See the timesheets** from Timesheet Portal on the placement's **Timesheets** tab.

Timesheet Portal sits alongside [RSM InTime](https://docs.spott.io/docs/integrations/rsm-intime.md). A workspace can
connect both, and publish a placement to either or to both.

## Connect Timesheet Portal

An admin connects Timesheet Portal once for the whole workspace. You need API credentials
from Timesheet Portal first, created against a **System Administrator** user there.

### Create the API credentials in Timesheet Portal

1. In Timesheet Portal, go to **Settings → Account → API**.
2. On the **Private applications** tab, click **+ New application**.
3. Give it a name, for example *Spott*, choose a System Administrator as the **API user**,
   make sure it is **Enabled**, and click **Save**.
4. Copy the **Client ID**. Then click **Click to show secret** and copy the **Client secret**.

![A private application in Timesheet Portal's API settings, with the API user, the Enabled toggle, the Client ID and the Click to show secret button](https://mintcdn.com/spott-docs/l6JwVI3-rQeuJzjF/images/integrations/timesheet-portal-api-application.webp?fit=max\&auto=format\&n=l6JwVI3-rQeuJzjF\&q=85\&s=a8ced29a5d5bf9e129de925fadd161d7)

### Connect in Spott

1. Go to **Settings → Integrations** and select **Timesheet Portal**.
2. Click **Enable**. The **Connect Timesheet Portal** dialog opens.
3. Fill in:
   * **Account name**: the subdomain of your Timesheet Portal URL. If you log in at
     `acme.timesheetportal.com`, it is `acme`. Letters, numbers and hyphens only.
   * **Client ID** and **Client Secret**: the credentials you just copied.
4. Click **Connect**.

![The Connect Timesheet Portal dialog with the Account name, Client ID and Client Secret fields](https://mintcdn.com/spott-docs/l6JwVI3-rQeuJzjF/images/integrations/timesheet-portal-connect.webp?fit=max\&auto=format\&n=l6JwVI3-rQeuJzjF\&q=85\&s=b3fd18961f99a1bb2607867ad8f38060)

Spott checks the credentials against your account and stores them for the workspace. The
**Workspace** row then shows **Connected**. If the details are wrong, you see "Could not
connect Timesheet Portal. Check the account name and credentials and try again."

A workspace connects one Timesheet Portal account. To switch accounts, choose **Disconnect
Timesheet Portal** from the menu on the **Workspace** row, then connect again.

> [!NOTE]
>
> Only workspace admins can connect or disconnect this integration. Publishing placements is
> open to anyone who may edit placements.

## Publish a placement

Only **contract** placements can be published, including their extensions. Contingent and
retained placements have no timesheets, so the option does not appear on them.

Check two things on the placement first:

* **It has a rate card.** Without one, **Publish to Timesheet Portal** is greyed out. Choose
  **Create rate card** in the same menu, see [set up a rate card](https://docs.spott.io/docs/placements/timesheets.md#1-set-up-a-rate-card).
* **Each rate has a pay code that exists in Timesheet Portal.** The codes live in Timesheet
  Portal under **Settings → Timesheets → Rates & Units**, for example `STD` or `OT1`. Pick the
  matching **Pay code** on each rate with **Edit rate card**.

### Start the publish

1. Open the contract placement.
2. Click the **⋮** menu at the top right of the **Placement** card.
3. Choose **Publish to Timesheet Portal**.

![The placement menu with Publish to Timesheet Portal below Publish to RSM InTime](https://mintcdn.com/spott-docs/l6JwVI3-rQeuJzjF/images/integrations/timesheet-portal-publish-menu.webp?fit=max\&auto=format\&n=l6JwVI3-rQeuJzjF\&q=85\&s=e73d634d1c6c74744ad2e518aa5eddf3)

### Complete the form

The form has six tabs. Spott fills in everything it already knows. Work through them with
**Review next tab** and **Previous tab**, or click a tab to jump to it. When a required field is
empty, the form shows **Field is required** and takes you to the first tab with a gap.

| Tab | What it covers |
| - | - |
| **Company** | The client: name, company registration number, tax number, billing email, accounting code, currency and invoicing address |
| **Contact** | The person at the client who **approves the timesheets** for this placement. Timesheet Portal stores them as an approver |
| **Candidate** | The contractor: name, email, employment type, job title, mobile, join date, date of birth, address and currency. The company details are only needed when the contractor invoices through their own company |
| **Consultant** | The consultant on the placement |
| **Placement** | The description, start date, end date or **Ongoing**, purchase order number and cost centre code, plus the timesheet frequency, invoicing frequency and IR35 status |
| **Rates** | The rates from the placement's rate card: name, rate code, pay rate and charge rate |

A contact and a consultant are always required, and so are the placement's description and
start date. For the timesheet frequency, invoicing frequency and IR35 status, leave **Use the
Timesheet Portal default** unless this placement is different.

The **Rates** tab is read-only: "These rates come from the placement's rate card. Edit the rate
card to change what is published." A rate card can send at most **20** rates, and each rate
code can appear on it only once.

![The Rates tab of the Publish to Timesheet Portal form, with the rate name, rate code, pay rate and charge rate](https://mintcdn.com/spott-docs/l6JwVI3-rQeuJzjF/images/integrations/timesheet-portal-rates-tab.webp?fit=max\&auto=format\&n=l6JwVI3-rQeuJzjF\&q=85\&s=66a2f494f5500cd89dea38c40ec8ae8b)

### New and linked records

The first time you publish, Spott **creates** the client, contact, candidate and consultant in
Timesheet Portal and links each one to its Spott record. Later placements for the same people
reuse that link, so they are not created twice.

Spott does **not** match records that already exist in Timesheet Portal, by name, email or
otherwise. Each client, contact, candidate and consultant you publish for the first time is
created as a **new record** in Timesheet Portal, even when the same company or person is
already there. To reuse an existing Timesheet Portal record instead, contact support before
you publish.

A record that is already linked is **not updated** from Spott. Its tab says so and asks you to
edit it in Timesheet Portal instead.

### Publish

Click **Publish** on the **Rates** tab. Spott confirms with "Placement published to Timesheet
Portal", and the placement exists in Timesheet Portal, linked to its client, approver,
contractor and consultant.

From then on the menu shows **Update in Timesheet Portal** instead. Use it to push later
changes, for example new rates. It updates the same placement in Timesheet Portal rather than
creating another one. The placement itself shows no badge or link to Timesheet Portal; the
menu item is how you tell it was published.

## What happens next

* **Timesheets** are filled in and approved in Timesheet Portal. About once an hour, Spott
  collects them and shows them on the placement's **Timesheets** tab, with their status:
  **Draft**, **Submitted**, **Approved**, **Rejected** or **Void**. They can only be changed
  in Timesheet Portal. Spott does not mark them as read-only, but it refuses a change to one:
  you get a general error message when you save.
* **Invoicing** runs in Timesheet Portal. Timesheets that come from Timesheet Portal cannot be
  invoiced from Spott, so the same hours are never billed twice. Invoices you create in
  Timesheet Portal do not show in Spott.

## Troubleshooting

| Message | What to do |
| - | - |
| **The Rate Code … could not be found** | A pay code on the rate card does not exist in Timesheet Portal. Check **Settings → Timesheets → Rates & Units** there, fix the code with **Edit rate card**, and publish again |
| **This placement needs a rate card before it can be published to Timesheet Portal** | Create a rate card on the placement first |
| **The rate card uses the code … more than once** | Give each rate line its own code |
| **The rate card has … rates, but Timesheet Portal accepts at most 20** | Remove rates until 20 or fewer are left |
| **The … linked to Timesheet Portal no longer exists there** | The linked record was deleted in Timesheet Portal. Contact support to remove or replace the link |
| **That Timesheet Portal … is already linked to another Spott record** | Two Spott records point at the same Timesheet Portal record. Contact support to correct the link |
| **Timesheet Portal rejected the stored connection** | The stored credentials no longer work. Disconnect and connect again with fresh credentials |
| **Timesheet Portal is temporarily unavailable** or **is rate limiting requests** | Wait a moment and try again |
| **Another Timesheet Portal publish is already in progress** | Someone is publishing at the same time. Try again once it finishes |

## Frequently asked

* **Who can connect the integration?** A workspace admin, from **Settings → Integrations**.
* **What is my account name?** The subdomain of your Timesheet Portal URL: `acme` for
  `acme.timesheetportal.com`.
* **Why is Publish to Timesheet Portal greyed out?** The placement has no rate card yet.
* **Why is there no Publish to Timesheet Portal at all?** The placement is not a contract
  placement, or Timesheet Portal is not connected for the workspace.
* **Do I need to publish every placement?** Yes. Only placements you publish are sent. Nothing
  goes to Timesheet Portal automatically.
* **Can I invoice Timesheet Portal timesheets from Spott?** No. Invoice them in Timesheet
  Portal, which keeps the same hours from being billed twice.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.