Statamic Teamtailor Sync

The Teamtailor Sync addon seamlessly integrates your Teamtailor ATS (Applicant Tracking System) with your Statamic website. It automates the process of pulling job vacancies from Teamtailor and creating corresponding native Statamic Entry records, keeping your career site's content always up to date with zero manual copy-pasting required.

Why use this Addon?

For businesses using Teamtailor to manage hiring but running their frontend on Statamic, managing open positions on both platforms can be a chore. This addon acts as a bridge:

• Zero Double-Data Entry: Create jobs in Teamtailor and let them automatically appear on your website.
• Native Experience: The synced jobs are stored safely as standard Statamic Collections and Entries, meaning you can loop through them using native Antlers tags and manage them just like any other content.
• Image Synchronization: It even downloads job banners and pictures directly to your local Asset container.

---

Features

• 🔄 Automated Synchronization: A single command runs a pull to sync all your active jobs.
• 🗂 Smart Upserts: Avoids duplicates by matching jobs by their internal teamtailor_id.
• 🖼 Local Assets Management: Automatically downloads external cover images to a self-hosted Asset container.
• 🎛 Control Panel Utility: A beautiful custom utility page inside the Statamic Dashboard allows content editors to trigger a sync with a single click.
• 🏷 Custom Antlers Tags: Displaying your synced jobs is as simple as adding {{ teamtailor:jobs limit="5" }} to your templates.

---

Technical Documentation & Setup

Requirements

• PHP 8.3 or higher
• Statamic 6.0 or higher
• A Teamtailor API Key (v1 JSON API)

1. Installation

Install the addon via Composer:

composer require risubrevis/teamtailor-sync

(Note: During local development, if you are linking it locally, ensure it is added to the repositories array in composer.json).

2. Configuration

Publish the environment variables to your project's .env file:

# Teamtailor credentials
TEAMTAILOR_API_KEY="your-secret-api-key"
TEAMTAILOR_BASE_URL="https://api.teamtailor.com/v1"
TEAMTAILOR_API_VERSION="20260329"

# Where downloaded images should be stored
TEAMTAILOR_ASSETS_CONTAINER="assets" 

3. Collection & Blueprints

When you run the synchronization for the first time, the addon will automatically create a new collection called jobs. A default blueprint job.yaml is provided and installed, containing fields for:

• title
• content
• location
• department
• teamtailor_id (hidden)
• job_status
• cover_image

4. Synchronization (Artisan Command)

To manually trigger the sync process from your server, run the following artisan command:

php artisan teamtailor:sync

Tip: You can use the --dry-run flag to see what changes would be made without actually modifying the disk.

Automated Sync via Laravel Scheduler

For fully automated updates natively in Laravel, add this to your routes/console.php (if using Laravel 11+) or app/Console/Kernel.php (for older versions):

use Illuminate\Support\Facades\Schedule;

Schedule::command('teamtailor:sync')->hourly();

Automated Sync via Server Crontab

Alternatively, you can skip the Laravel Scheduler entirely and set up a direct cron job at the system level for your server. Below are examples of how to run the sync every hour (0 * * * *):

Example 1: If your Statamic app is running inside a Docker container: (Make sure to replace statamic_app with the actual name of your PHP container)

0 * * * * docker exec statamic_app php artisan teamtailor:sync > /dev/null 2>&1

Example 2: If Statamic is running directly on the server (System PHP): (Make sure to provide the absolute path to your Statamic root directory)

0 * * * * /usr/bin/php /var/www/your-statamic-project/artisan teamtailor:sync > /dev/null 2>&1

5. Control Panel UI

Alternatively, Content Editors can trigger a sync manually at any time. Go to Statamic Control Panel > Utilities > Teamtailor Sync and click "Sync Jobs Now". The real-time output will be displayed on the page.

6. Displaying Jobs (Antlers Tags)

Use the included teamtailor tag set to seamlessly render entries in your frontend templates.

<div class="jobs-list">
    {{ teamtailor:jobs limit="3" sort="-date" }}
        <article>
            <h2>{{ title }}</h2>
            <p><strong>Location:</strong> {{ location }}</p>
            <p><strong>Department:</strong> {{ department }}</p>
            <a href="{{ url }}">Read more</a>
        </article>
    {{ /teamtailor:jobs }}
</div>

Parameters

• limit (int): Number of jobs to fetch. Set to 0 for no limit. Defaults to 0.
• sort (string): Field to sort by. Prefix with - for descending order (e.g., -date, title). Defaults to -date.

---

Support & Debugging

If something goes wrong during synchronization, check the Laravel logs located in storage/logs/laravel.log. The addon logs all operations and errors with the prefix [Teamtailor Sync]. It gracefully handles rate-limits and connectivity issues from the API.