Pipedrive Integration
The platform integrates with Pipedrive CRM to automatically create and track deals when quotes are generated.
Overview
When a dissertation submission is processed and a quote is calculated, the pipedriveClient Lambda function creates a deal in Pipedrive with the contact information, document analysis results, and quote details. This allows the PhD Advantage team to manage the editing pipeline from quote through delivery.
Configuration
| Setting | Value |
|---|---|
| API Token | Stored in SSM: /dissertation-editor/pipedrive/api-token |
| Pipedrive Instance | phd-advantage.pipedrive.com |
| Webhook ID | 1345147 |
| Feature Flag | ENABLE_PIPEDRIVE_DEALS environment variable on processSubmission |
Feature Flag
Deal creation can be toggled using the ENABLE_PIPEDRIVE_DEALS environment variable on the processSubmission Lambda function. When set to false, the submission is processed and a quote is generated, but no Pipedrive deal is created. This is useful during development and testing.
Pipeline Configuration
All deals are created in Pipeline 1 with the following stages:
| Stage | Description |
|---|---|
| Quote sent | Initial stage. Deal created automatically when quote is generated. |
| Payment pending | Client has reviewed the quote; awaiting payment. |
| Received payment | Payment received; project ready to begin. |
| Project in-process | Editor is actively working on the dissertation. |
| QC review | Quality control review of the edited document. |
| Awaiting full payment | Final balance due (if applicable). |
| Documents returned | Edited dissertation delivered to the client. Deal is marked as won. |
Deal Creation
When pipedriveClient is invoked, it creates a deal with the following data:
Deal Fields
| Field | Source |
|---|---|
| Title | "{name} - Dissertation {serviceType}" |
| Value | Quote total amount |
| Currency | USD |
| Person (contact) | Created or matched by email |
| Stage | Pipeline 1, Stage 1 (Quote sent) |
Custom Field Mappings
The deal includes custom fields populated from the document analysis and quote:
| Custom Field | Source Value | Description |
|---|---|---|
| Text WC | analysis.textWordCount |
Word count of the main body text |
| Refs WC | analysis.refsWordCount |
Word count of the references section |
| Tables | analysis.tables |
Number of tables in the document |
| Figures | analysis.figures |
Number of figures in the document |
| FM | analysis.frontMatter |
Number of front matter pages |
| Subtotal | quote.subtotal |
Quote subtotal before admin fee |
| Admin Fee | quote.adminFee |
Administrative fee amount |
| Total | quote.total |
Final quote total |
| Service Type | serviceType |
The selected editing service |
| Submission ID | submissionId |
Platform submission ID for cross-reference |
Webhook
Pipedrive sends webhook events to POST /webhooks/pipedrive for all deal events (*.deal). The webhook is configured with ID 1345147.
Currently, the webhook handler logs events to CloudWatch for monitoring. Future enhancements may include:
- Updating submission status in DynamoDB when a deal stage changes
- Sending notifications when payment is received
- Triggering document delivery workflows
See Webhook API for endpoint details.
Contact Management
The pipedriveClient function handles Pipedrive person (contact) records:
- Searches for an existing person by email address.
- If found, associates the deal with the existing person.
- If not found, creates a new person with the name, email, and phone from the submission.
This prevents duplicate contacts when a returning client submits a new dissertation.
Error Handling
If the Pipedrive API call fails (rate limit, network error, invalid token), the pipedriveClient function throws an error. The processSubmission orchestrator catches this and still marks the submission as completed with the quote data. The Pipedrive deal URL will be absent from the submission record, and the error is logged to CloudWatch.
This means a Pipedrive outage does not block the user from receiving their quote.