Align Integration

Illumera integrates with Align — a client-feedback and project management platform — to keep your projects, team members, and time entries in sync without manual data entry.

Overview

When connected, Illumera automatically mirrors key data into your Align organization:

• Projects — every Illumera project is created (or updated) in Align as soon as it is saved.
• Talent — when a contractor accepts an engagement, Illumera provisions them as a user in Align and adds them to the project.
• Time entries — talent logs hours in Illumera; those entries are pushed to Align and submitted for company-side approval.
• Staffing wiki — when a project becomes active, Illumera writes a structured staffing plan page into the project's Align wiki, listing all open roles with hours and duration.

The integration is designed for government contracting companies that use Align as their authoritative time-tracking and client-delivery system. Illumera acts as the talent marketplace and engagement layer; Align handles time approval, invoicing, and project financials.

Prerequisites

Before connecting:

• An active Align account for your organization.
• An organization-scoped API key from Align. Project-scoped keys are rejected — they cannot create projects, invite users, or register webhooks across the organization.
• The Company Admin role in Illumera (or Platform Admin).

Why organization-scoped keys only?

Project-scoped keys are limited to a single project's endpoints. Illumera needs to create new projects, provision users, and receive organization-wide webhook events, which all require an organization-scoped key.

Connecting

Step 1 — Mint an API key in Align

1. Log in to Align at https://app.alignsoft.us.
2. Navigate to Admin → Developer Keys (direct link).
3. Click Create Key.
4. Set the scope to Organization (not Project).
5. Copy the key — it is shown only once.

Step 2 — Paste the key into Illumera

1. In the Illumera platform, go to your Company Settings → Integrations.
2. Find the Align section and click Connect.
3. Paste your API key and click Save.

Illumera immediately:

• Validates the key against Align's /me endpoint.
• Confirms it is organization-scoped (rejects it if not).
• Registers a webhook subscription in Align pointing at Illumera's inbound webhook endpoint.
• Stores the key encrypted at rest using AES-256-GCM.

Step 3 — Confirm "Connected" status

Once saved, the Align section shows:

Field	Meaning
Status	Connected — key is valid and webhook is registered
Key	Last four characters of the key on file
Organization ID	Your Align organization UUID
Last synced	Timestamp of the most recent successful sync operation

If status shows Error, see Troubleshooting below.

What Syncs

Illumera action	Result in Align
Project created or updated	Align project created (or updated) with timeBillingEnabled: true
Engagement accepted by talent	Talent provisioned as an Align user (developer role); added as a project member
Time entry logged and submitted in Illumera	Time entry pushed to Align project and submitted for approval
Project becomes active	Staffing wiki page written to the Align project with all open roles
Time entry approved in Align	Illumera time entry status updated to approved via webhook
Time entry rejected in Align	Illumera time entry status updated to rejected with rejection reason
Time entry locked in Align	Illumera status updated to locked
Time entry invoiced in Align	Illumera status updated to invoiced
Engagement ended	Talent removed from the Align project member list

What does not sync

Historical data (projects and entries that existed before the connection was made) is not backfilled. Only changes made after connecting are synced.

Time Entry Workflow

Talent logs hours in Illumera against their active engagement. Here is the complete lifecycle:

1. Draft — talent creates a time entry for a specific work date and minute count. It is saved locally and pushed to Align in draft state.
2. Submitted — talent clicks Submit. Illumera marks the entry submitted and triggers a submit action in Align, making it visible to company approvers.
3. Approved — a company approver approves the entry in Align. Align fires a time.approved webhook; Illumera updates the entry to approved.
4. Rejected — a company approver rejects the entry in Align with a reason. Align fires time.rejected; Illumera updates the entry to rejected and surfaces the rejection reason to talent.
5. Locked — Align locks the entry for invoicing. Illumera marks it locked; it can no longer be edited.
6. Invoiced — Align marks the entry as invoiced. Illumera marks it invoiced.

Handling rejections: When a time entry is rejected, talent sees the rejection reason in their Illumera dashboard and can submit an adjustment entry — a corrected replacement entry that references the original. Adjustment entries are clearly labelled and pushed to Align with the same flow.

Sync Status Dashboard

Navigate to Admin → Align Sync to view the live sync status for any company. Three tables are shown:

Outbox queue

Each row represents a pending or completed sync operation.

Column	Meaning
Entity type	project, user, project_member, time_entry, wiki_page
Status	pending → processing → done / failed
Attempts	Number of delivery attempts so far
Error	Last error message (if any)
Next retry	When the worker will next attempt this item

What to do when a row is in failed state: Click Retry Failed to reset all failed items back to pending. The worker will process them on the next tick. If they continue to fail, check the error column — common causes are a missing or revoked API key, a rate limit spike, or a dependency ordering issue (e.g. the user wasn't synced before the project member).

Webhook deliveries

Each row is an inbound event received from Align.

Column	Meaning
Event name	e.g. time.approved, time.rejected
Status	received → processed / failed
Received at	Timestamp
Error	Handler error message (if failed)

Reconciliation discrepancies

Nightly, Illumera compares approved minute and cost totals between its database and Align. Any delta larger than noise (>$1) is recorded here.

Column	Meaning
Field	approved_minutes or approved_cost_cents
Illumera value	What Illumera's database holds
Align value	What Align's API returned
Detected at	Timestamp of the reconciliation run

Resolving discrepancies: A discrepancy usually means an entry was approved in Align but the webhook was missed (or failed). Re-run the sync or manually verify the entry in both systems.

Disconnecting

To disconnect Align:

1. Go to Company Settings → Integrations → Align.
2. Click Disconnect.

Disconnecting:

• Marks the connection disconnected in Illumera's database.
• Deregisters the webhook subscription from Align (best-effort).
• Stops all future sync operations for this company.

What is preserved: Existing data in Align is not deleted. Illumera's entity link table (which maps Illumera IDs to Align IDs) is retained so that a future reconnection can resume without creating duplicate records.

To reconnect later, repeat the Connecting steps with a valid organization-scoped API key.

Troubleshooting

Symptom	Likely cause	Fix
"This API key is project-scoped"	API key was minted with Project scope	Mint a new key at Align with Organization scope
"Align API key validation failed: 401"	Key is invalid or revoked	Mint a fresh key in Align and reconnect
"Webhook registration failed"	Organization lacks webhook permissions	Contact your Align organization admin to enable webhooks, then reconnect
Status shows Error after reconnecting	New key is valid but an outbox item previously failed with the old key	Click Retry Failed in the sync dashboard
Reconciliation shows approved_minutes mismatch	time.approved webhook was missed or failed	Verify the entry in Align; use Retry Failed if a webhook delivery shows failed
Time entry stuck in submitted in Illumera	Webhook not received from Align	Check the Webhook deliveries table; if empty, verify the webhook URL is reachable from Align