Claude Templates / B-tier · Situational

Outreach

The GoHighLevel Integration Playbook

OAuth, contacts, conversations, opportunities — the GHL API gotchas up front.

GHL-INTEGRATION-PLAYBOOK.md · 16 sections · 2,182 words · 17 KB · markdown

What's inside

• //OAuth setup, token storage, and refresh handling
• //Contact upsert semantics and custom-field mapping
• //The Conversations API for reading and sending messages
• //Pipeline + opportunity creation
• //Tag and DND operations
• //The undocumented required-field gotchas that cause 4xx loops

Straight from the file

GHL is the dominant infrastructure layer for the BILT CRM customer base and most BILT portfolio marketing apps. Integrating cleanly with GHL is a recurring task — this playbook locks in the patterns and the landmines we've already paid for.

Table of contents

1. 0. Use this spec
2. 1. Architecture
3. 2. Schema
4. 3. OAuth 2.0 flow (end-user installs your app)
5. 4. Private Integration Token (PIT JWT) flow
6. 5. API Key (legacy v1) — DO NOT USE
7. 6. CRITICAL GOTCHA — userId requirement on create-post
8. 7. CRITICAL GOTCHA — destructive sync of boardids
9. 8. CRITICAL GOTCHA — media MIME types
10. 9. CRITICAL GOTCHA — instagramPostDetails not instagramPost
11. 10. Social publish — wire-platform normalizer
12. 11. Blog publish
13. 12. CRM sync (optional)
14. 13. Webhook receiver
15. 14. Common pitfalls
16. 15. Kickoff prompt

More outreach playbooks