Getting Started with the Grinfi API
The Grinfi Public API lets you seamlessly connect the platform to your own tools: CRM systems, internal dashboards,
no-code platforms (such as Make or Zapier), or custom scripts.
Almost everything you do in the Grinfi web app is also available over the API: managing contacts, running automations,
sending LinkedIn messages and emails, and setting up webhooks to track events in real time.
In this article, we'll go through the basics: how to create your first API key, make a test request, and what our API
can do in general.
Step 1. Create an API key
To get started, you'll need a unique access key:
1. Log in to your Grinfi account at leadgen.grinfi.io.
2. Open the general settings and go to Settings -> API Keys.
3. Copy an existing key or click the button to create a new one.
🟡 Important security and access details:
- Each API key is strictly tied to the team (workspace) that was active at the moment it was created. All requests
made with that key will have access to the contacts, automations, and messages of that team only.
- Keep your API key secret. Anyone who has access to it gains control over your account data. If a key is accidentally
compromised, delete it immediately and generate a new one.
Step 2. Make a request
The base URL for all API requests is https://leadgen.grinfi.io. Every request must include your key in the authorization
header: Authorization: Bearer YOUR_API_KEY.
To quickly check that the API works, try searching for contacts in your account with this cURL request:
curl -X POST "https://leadgen.grinfi.io/leads/api/leads/search" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filter": {}, "limit": 5, "offset":0}'
If everything is set up correctly, you'll get back JSON with the first five contacts from your CRM.
💡 Two things worth remembering when working with requests:
- Always send the Content-Type: application/json header. Requests in form-encoded format will not pass the system's
validation.
- Large data sets are returned page by page using the limit and offset parameters. The server response always includes
the total and has_more fields, so you know exactly when to stop paging through the results.
What the Grinfi API can do
Our API is logically divided into four main areas:
| Area | What it covers | | ---------------- |
---------------------------------------------------------------------------- | | CRM | Contacts, companies, lists, tags,
pipeline stages, custom fields, and notes. | | Outreach | Automations, tasks, and sender profiles. | | Messaging |
LinkedIn messages, emails, mailboxes, and attachments. | | Integrations | Webhook setup for receiving real-time event
notifications. |
The most popular API use cases:
- Syncing with your CRM: Create or update contacts along with custom fields using a single POST
/leads/api/leads/upsert call.
- Adding contacts to automations: Programmatically add contacts to a running sequence (for example, right after
someone fills out a lead form on your website).
- Sending messages directly: Send a LinkedIn message or an email to a specific contact straight from your own
workflow.
- Reacting to events in real time: Set up a webhook and get an HTTP call every time a contact replies, changes status,
or is enriched with new data.
- Bulk import and export: Upload CSV files to import a database in bulk, or queue exports of contacts and companies.
Frequently asked questions (FAQ)
I'm getting a 401 or 403 error. What should I do? It means the key is missing from the request, is invalid, or has
expired. Check that the Authorization: Bearer header is passed correctly, and generate a new key in the API Keys section
if needed.
Are there rate limits? Yes, which is why we recommend using pagination and setting a reasonable request rate. For bulk
data operations, it's far more efficient to use the dedicated mass-action endpoints and the CSV import/export tools
instead of looping through dozens of separate small calls.
Full documentation
This article is only a basic overview. The complete technical API reference, with all endpoints, detailed request
schemas, and server response examples, is available here: [Grinfi API Documentation].
