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:

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].