Overview
The Groundhogg REST API allows you to programmatically access and manage contacts, tags, broadcasts, flows, and more. It’s ideal for developers who want to integrate external platforms or build custom tools on top of Groundhogg.
Authentication Options
Groundhogg supports two main methods of authentication for external requests:
WordPress Application Passwords (Recommended)
- Go to Users → Profile (for the user you want to authenticate with)
- Generate a new Application Password
- Use your username:application_password as Basic Auth in your request
Groundhogg API Keys (legacy support or custom implementations)
- Go to Groundhogg → Settings → API
- Generate an API key/secret pair
Further detailed authentication instructions are included in the REST API Playground.
Use the REST API Playground
For local testing, try the built-in REST API Playground:
- Go to Groundhogg → Tools → REST API Playground
- Choose an endpoint, HTTP method, and enter parameters
- Preview and send real requests using your current admin session
- View the full response, status codes, and errors
It’s a fast way to learn the API without using Postman or writing code.
When to Use the REST API vs PHP API
Use the REST API when:
- You’re integrating Groundhogg with an external system (e.g. Zapier, your own app)
- You need to send data to Groundhogg from a different server or domain
- You want to build a headless or JavaScript-based frontend
Use the PHP API when:
- You’re building a WordPress plugin or theme that runs on the same site
- You want tighter performance and access to WordPress hooks
- You don’t need cross-site communication
Troubleshooting Tips
401 Unauthorized?
Check that you’re using valid credentials and correct auth method. For App Passwords, the user must have proper permissions.
403 Forbidden?
The authenticated user might not have permission for that endpoint. Make sure you’re logged in as an admin.
Wrong data or nothing returned?
Double-check your request method (GET, POST, etc.), and confirm required fields like email or id are included.
CORS errors?
If calling the API from a browser on a different domain, you may need to configure CORS headers manually via plugin or server rules.
FAQs
Q: Where is the API documentation?
A: The full list of endpoints is available in your site at:/wp-json/gh/v4/
Or use the REST API Playground to browse and test them.
Q: Is authentication required for all endpoints?
A: Yes — all Groundhogg endpoints require an authenticated user with the proper capabilities.
Q: Can I use the API from a JavaScript frontend?
A: Yes, but you’ll need to manage CORS and authentication properly. WordPress App Passwords are the simplest solution for this. Never expose API keys or App passwords to the public!
Q: Is there rate limiting?
A: Not by default, but your host, CDN, or security plugin may impose limits. Always handle errors gracefully and avoid overloading your server.
Was this helpful?
Let us know if this document answered your question. That’s the only way we can improve.