Technical Integration Spec — TaskFlow to Nimbus CRM

Integration: TaskFlow (project app) to Nimbus CRM Prepared by: Priya Nair, Integrations Team Date: 5 June 2026 Version: 1.0 Status: Approved

---

1. Overview and systems

When a TaskFlow user marks a project as "won", TaskFlow should create or update the matching contact and deal in Nimbus CRM so the sales team sees the same record without re-keying it. TaskFlow is the source of truth for project data; Nimbus is the system of record for CRM contacts and deals.

System	Role	Owner	Environment(s)
TaskFlow	Source of truth for projects	Integrations Team	Staging, Production
Nimbus CRM	Downstream consumer (contacts, deals)	Vendor (Nimbus)	Sandbox, Production

2. Integration flow

When a project is marked "won" in TaskFlow, TaskFlow first creates or updates the contact in Nimbus using the contact's email as the match key. This call is synchronous because TaskFlow needs the returned Nimbus contact id before it can attach a deal. TaskFlow then creates the deal asynchronously, queuing the call so a slow Nimbus response does not block the user. Later, when the deal's stage changes inside Nimbus, Nimbus pushes a status webhook to TaskFlow so the project's status stays in step without TaskFlow polling.

3. Endpoints and operations

Operation	Direction	Sync / Async	Purpose	Request summary	Response summary
Upsert contact	TaskFlow to Nimbus	Sync	Create or update the contact by email	Name, email, company, phone	Nimbus contact id
Create deal	TaskFlow to Nimbus	Async	Open a deal linked to the contact	Contact id, deal name, value, stage	Nimbus deal id, status
Deal status webhook	Nimbus to TaskFlow	Async	Notify TaskFlow of a stage change	Deal id, new stage, timestamp	200 acknowledgement

4. Authentication

TaskFlow authenticates to Nimbus with a bearer token sent in the Authorization header. The token is issued from a dedicated Nimbus service account scoped to contacts and deals only, stored in TaskFlow's secrets manager, and rotated every 90 days. Inbound webhooks from Nimbus are verified by a signature header described in Section 9; TaskFlow rejects any webhook that fails signature verification.

5. Data field mapping

Source field	Target field	Notes
project.client_name	contact.full_name	Trimmed; required. If empty, the upsert is rejected and alerts.
project.client_email	contact.email	Lower-cased; used as the match key for upsert.
project.company	contact.company_name	Optional; sent as empty string if absent.
project.value_cents	deal.amount	Converted from integer cents to a decimal amount (divide by 100).
project.won_at	deal.close_date	Converted from a timestamp to an ISO date (date only, UTC).
(constant)	deal.stage	Always set to "Closed Won" on creation.

6. Error handling and retries

Condition	Classification	Action
Timeout or 5xx from Nimbus	Transient	Retry with exponential back-off, up to 5 attempts
422 validation error	Permanent	Do not retry; log the payload, alert the team, hold the record for review
429 rate limited	Transient	Back off per Section 8, then retry the queued call
Webhook signature invalid	Permanent	Reject with 401; do not process; log the source IP

Exhausted retries move the failed call to a dead-letter queue that is reviewed each morning, so no "won" project is silently lost.

7. Idempotency

Every create-deal call carries an idempotency key equal to the TaskFlow project id. Nimbus stores this key against the deal it creates, so if TaskFlow's queue retries the same call, Nimbus returns the existing deal id instead of opening a second deal. This guarantees one project produces at most one deal even when calls are retried.

8. Rate limits

Nimbus allows 120 requests per minute per service account. When TaskFlow receives a 429, it reads the Retry-After value, waits that long, and then resumes. Bulk back-fills (for example, importing historical won projects) are paced to 100 requests per minute to stay safely under the limit, with a short pause between batches.

9. Security

All calls use TLS; plain HTTP is refused. The Nimbus token is read from the secrets manager at runtime and is never written to logs or error messages. The service account is scoped to contacts and deals only, so a leaked token cannot touch billing or admin data. Inbound webhooks include a signature header computed over the raw body with a shared secret; TaskFlow recomputes the signature and rejects any mismatch. Contact email and phone are personal data and are handled per the data privacy policy, encrypted in transit and at rest.

10. Testing

Tested against the Nimbus sandbox with a dedicated test service account before promotion to production.

• Happy path: a "won" project creates the contact, returns an id, and creates one deal in the right stage
• Field mapping: value_cents converts correctly to a decimal amount and won_at to an ISO date
• Idempotency: replaying the same create-deal call returns the existing deal id and creates no duplicate
• Retry: a forced 5xx is retried and the deal is created once, with no duplicate
• Auth failure: an expired token is rejected cleanly and raises an alert
• Webhook: a stage-change webhook updates the project, and a tampered payload is rejected as unauthorised

---

Open questions and assumptions

• Assumes Nimbus matches contacts on email alone; if Nimbus later matches on phone too, the upsert rule in Section 5 must be revisited.
• Deletion is out of scope for version 1.0; archived projects are not removed from Nimbus.