# Grinfi.io API

Complete API reference for Grinfi.io — the all-in-one LinkedIn & email outreach platform.
Use this API to manage your CRM contacts, run outreach automations, send messages, and integrate Grinfi with your own tools.

## Authentication
All requests require a Bearer token in the `Authorization` header.
1. Log in at [leadgen.grinfi.io](https://leadgen.grinfi.io/)
2. Go to [Settings → API Keys](https://leadgen.grinfi.io/settings/api-keys)
3. Copy your key and pass it as:
   ```
   Authorization: Bearer YOUR_API_KEY
   ```


## Pagination
List endpoints support `limit` (default 20) and `offset` (default 0) query parameters. Responses include `total` count and `has_more` boolean.

## Filtering
Most list endpoints accept a `filter` object. Supported value types:
| Type | Example | SQL equivalent | |------|---------|----------------| | Scalar | `"status": "ok"` | `= 'ok'` | | Array | `"status": ["ok", "pending"]` | `IN ('ok', 'pending')` | | Object | `"created_at": {">=": "2024-01-01"}` | `>= '2024-01-01'` | | `"is_null"` | `"email": "is_null"` | `IS NULL` | | `"is_not_null"` | `"email": "is_not_null"` | `IS NOT NULL` |
Supported operators: `=`, `!=`, `<`, `<=`, `>`, `>=`, `<>`

## Rate Limits
API requests are rate-limited per account. If you exceed the limit, you'll receive a `429` response. Use exponential backoff when retrying.


Version: 2.0.0
License: Copyright

## Servers

Production
```
https://leadgen.grinfi.io
```

## Security

### bearerAuth

API key from [Settings -> API Keys](https://leadgen.grinfi.io/settings/api-keys).


Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

[Grinfi.io API](https://api.grinfi.io/_bundle/openapi.yaml)

## Contacts

Manage your CRM contacts (leads). Search, create, update, and organize contacts across lists and pipeline stages.


### Find a contact

 - [POST /leads/api/leads/lookup-one](https://api.grinfi.io/openapi/contacts/findonecontact.md): Look up a single contact by LinkedIn ID, email address, or name + company combination. At least one identifier must be provided. This is useful for checking if a contact already exists before creating a new one.

### Search contacts

 - [POST /leads/api/leads/search](https://api.grinfi.io/openapi/contacts/searchcontacts.md): Search contacts using advanced filters with pagination and sorting. Use this to find contacts by any combination of fields — name, company, email status, pipeline stage, tags, and more.

### Get a contact

 - [GET /leads/api/leads/{uuid}](https://api.grinfi.io/openapi/contacts/getlead.md): Retrieve full details of a contact by their UUID.

### Update a contact

 - [PUT /leads/api/leads/{uuid}](https://api.grinfi.io/openapi/contacts/updatelead.md): Update one or more fields on an existing contact. Only include the fields you want to change.

### Delete a contact

 - [DELETE /leads/api/leads/{uuid}](https://api.grinfi.io/openapi/contacts/deletelead.md): Permanently delete a contact by UUID. This creates a background deletion job.

### Create or update a contact

 - [POST /leads/api/leads/upsert](https://api.grinfi.io/openapi/contacts/upsertcontact.md): Create a new contact in a list, or update an existing one if found. The contact is identified by linkedin_id. If the contact already exists and update_if_exists is true, their data will be updated. Optionally move the contact to the specified list with move_to_list.

### Bulk action on contacts

 - [PUT /leads/api/leads/mass-action](https://api.grinfi.io/openapi/contacts/leadsmassaction.md): Perform a bulk operation on contacts matching a filter. Supported actions include changing pipeline stage, assigning/removing tags, moving to a list, and deleting.

## Companies

Manage company records in your CRM. Companies can be linked to contacts and enriched with additional data from LinkedIn.


### List companies

 - [GET /leads/api/companies](https://api.grinfi.io/openapi/companies/listcompanies.md): Retrieve a paginated list of companies in your CRM. Supports filtering by name, domain, industry, and other fields.

### Create companies

 - [POST /leads/api/companies](https://api.grinfi.io/openapi/companies/createcompanies.md): Create one or more company records. Optionally assign them to lists and a data source.

### Get a company

 - [GET /leads/api/companies/{uuid}](https://api.grinfi.io/openapi/companies/getcompany.md): Retrieve full details of a company by UUID.

### Update a company

 - [PUT /leads/api/companies/{uuid}](https://api.grinfi.io/openapi/companies/updatecompany.md): Update one or more fields on an existing company.

### Delete a company

 - [DELETE /leads/api/companies/{uuid}](https://api.grinfi.io/openapi/companies/deletecompany.md): Permanently delete a company by UUID.

### Lookup companies

 - [POST /leads/api/companies/lookup](https://api.grinfi.io/openapi/companies/lookupcompanies.md): Find companies by LinkedIn ID, website URL, or name. Pass an array of lookup criteria — each item should contain at least one identifier.

### Get contacts by companies

 - [POST /leads/api/companies/leads](https://api.grinfi.io/openapi/companies/getcompanyleads.md): Retrieve all contacts belonging to the specified companies. Returns an object mapping company UUIDs to arrays of contacts.

### Enrich companies

 - [PUT /leads/api/companies/advanced-enrichment](https://api.grinfi.io/openapi/companies/enrichcompanies.md): Queue advanced enrichment for companies. Provide either a filter to select companies or an array of specific company UUIDs. Enrichment uses credits from your account balance.

## Lists

Organize contacts into lists. Every contact must belong to a list. Use lists to segment your audience for outreach campaigns.


### List all lists

 - [GET /leads/api/lists](https://api.grinfi.io/openapi/lists/listlists.md): Retrieve all contact lists in your account. Lists are used to organize contacts into groups for outreach campaigns.

### Create a list

 - [POST /leads/api/lists](https://api.grinfi.io/openapi/lists/createlist.md): Create a new contact list.

### Get a list

 - [GET /leads/api/lists/{uuid}](https://api.grinfi.io/openapi/lists/getlist.md): Retrieve details of a specific contact list.

### Update a list

 - [PUT /leads/api/lists/{uuid}](https://api.grinfi.io/openapi/lists/updatelist.md): Rename an existing contact list.

### Delete a list

 - [DELETE /leads/api/lists/{uuid}](https://api.grinfi.io/openapi/lists/deletelist.md): Permanently delete a contact list.

## Tags

Label contacts and companies with custom tags for easy filtering and segmentation.


### List tags

 - [GET /leads/api/tags](https://api.grinfi.io/openapi/tags/listtags.md): Retrieve all tags in your account.

### Create a tag

 - [POST /leads/api/tags](https://api.grinfi.io/openapi/tags/createtag.md): Create a new tag with optional color.

### Update a tag

 - [PUT /leads/api/tags/{uuid}](https://api.grinfi.io/openapi/tags/updatetag.md): Update a tag's name or color.

### Delete a tag

 - [DELETE /leads/api/tags/{uuid}](https://api.grinfi.io/openapi/tags/deletetag.md): Permanently delete a tag.

## Pipeline

Define and manage pipeline stages to track where each contact stands in your sales or outreach process.


### List pipeline stages

 - [GET /leads/api/pipeline-stages](https://api.grinfi.io/openapi/pipeline/listpipelinestages.md): Retrieve all pipeline stages. Filter by object type (lead or company) to get stages specific to contacts or companies.

### Create a pipeline stage

 - [POST /leads/api/pipeline-stages](https://api.grinfi.io/openapi/pipeline/createpipelinestage.md): Create a new custom pipeline stage.

### Update a pipeline stage

 - [PUT /leads/api/pipeline-stages/{uuid}](https://api.grinfi.io/openapi/pipeline/updatepipelinestage.md): Update a pipeline stage's name, category, or order.

### Delete a pipeline stage

 - [DELETE /leads/api/pipeline-stages/{uuid}](https://api.grinfi.io/openapi/pipeline/deletepipelinestage.md): Delete a custom pipeline stage.

## Custom Fields

Extend contact and company records with custom data fields. Store any additional information relevant to your workflow.


### List custom fields

 - [GET /leads/api/custom-fields](https://api.grinfi.io/openapi/custom-fields/listcustomfields.md): Retrieve all custom field definitions for contacts and companies.

### Create a custom field

 - [POST /leads/api/custom-fields](https://api.grinfi.io/openapi/custom-fields/createcustomfield.md): Define a new custom field for contacts or companies.

### Update a custom field

 - [PUT /leads/api/custom-fields/{uuid}](https://api.grinfi.io/openapi/custom-fields/updatecustomfield.md): Update a custom field's name or order.

### Delete a custom field

 - [DELETE /leads/api/custom-fields/{uuid}](https://api.grinfi.io/openapi/custom-fields/deletecustomfield.md): Permanently remove a custom field definition and all its values.

### Set a custom field value

 - [POST /leads/api/custom-field-values](https://api.grinfi.io/openapi/custom-fields/upsertcustomfieldvalue.md): Set (or update) a custom field value on a contact or company. Pass null as value to clear the field.

## Notes

Add internal notes to contacts or companies for your team's reference.


### List notes

 - [GET /leads/api/notes](https://api.grinfi.io/openapi/notes/listnotes.md): Retrieve notes with pagination.

### Create a note

 - [POST /leads/api/notes](https://api.grinfi.io/openapi/notes/createnote.md): Add a note to a contact or company.

### Update a note

 - [PUT /leads/api/notes/{uuid}](https://api.grinfi.io/openapi/notes/updatenote.md): Update the text of an existing note.

### Delete a note

 - [DELETE /leads/api/notes/{uuid}](https://api.grinfi.io/openapi/notes/deletenote.md): Permanently delete a note.

## Automations

Manage outreach automation sequences. Automations define multi-step workflows that send LinkedIn messages, emails, and perform other actions on a schedule.


### List automations

 - [GET /flows/api/flows](https://api.grinfi.io/openapi/automations/listflows.md): Retrieve all outreach automations in your account. Automations are multi-step sequences that send LinkedIn messages, emails, and other actions on a schedule.

### Get an automation

 - [GET /flows/api/flows/{flowUuid}](https://api.grinfi.io/openapi/automations/getflow.md): Retrieve full details of an automation by UUID.

### Update an automation

 - [PUT /flows/api/flows/{flowUuid}](https://api.grinfi.io/openapi/automations/updateflow.md): Update an automation's name, description, or schedule.

### Delete an automation

 - [DELETE /flows/api/flows/{flowUuid}](https://api.grinfi.io/openapi/automations/deleteflow.md): Permanently delete an automation. This cannot be undone.

### Start an automation

 - [PUT /flows/api/flows/{flowUuid}/start](https://api.grinfi.io/openapi/automations/startflow.md): Activate an automation so it begins processing contacts and executing outreach steps on its schedule.

### Stop an automation

 - [PUT /flows/api/flows/{flowUuid}/stop](https://api.grinfi.io/openapi/automations/stopflow.md): Pause an automation. Contacts already in progress will finish their current step.

### Archive an automation

 - [PUT /flows/api/flows/{flowUuid}/archive](https://api.grinfi.io/openapi/automations/archiveflow.md): Archive an automation. Archived automations cannot be started.

### Unarchive an automation

 - [PUT /flows/api/flows/{flowUuid}/unarchive](https://api.grinfi.io/openapi/automations/unarchiveflow.md): Restore an archived automation so it can be started again.

### Clone an automation

 - [POST /flows/api/flows/clone](https://api.grinfi.io/openapi/automations/cloneflow.md): Create a copy of an existing automation with a new name. The cloned automation will be in a stopped state.

### Get automation metrics

 - [POST /flows/api/flows/metrics](https://api.grinfi.io/openapi/automations/getflowmetrics.md): Retrieve performance metrics for one or more automations — contacts added, messages sent, replies received, etc.

### Add a contact to an automation

 - [POST /flows/api/flows/{flowUuid}/leads/{leadUuid}](https://api.grinfi.io/openapi/automations/addleadtoflow.md): Add an existing contact to an automation. The contact will enter the automation from the beginning of the sequence.

### Create a contact and add to automation

 - [POST /flows/api/flows/{flowUuid}/add-new-lead](https://api.grinfi.io/openapi/automations/addnewleadtoflow.md): Create a new contact and immediately add them to an automation. The contact is created in the specified list and starts the automation sequence. If skip_if_lead_exists is true, existing contacts won't be added again.

### Cancel contact from specific automations

 - [PUT /flows/api/flows/leads/{leadUuid}/cancel](https://api.grinfi.io/openapi/automations/cancelleadfromflows.md): Remove a contact from specific automations. The contact's progress in those automations will be cancelled.

### Cancel contact from all automations

 - [PUT /flows/api/flows/leads/{leadUuid}/cancel-all](https://api.grinfi.io/openapi/automations/cancelleadfromallflows.md): Remove a contact from all active automations at once.

## Tasks

Create and manage outreach tasks such as sending LinkedIn messages or emails. Tasks can be created manually or generated by automations.


### List tasks

 - [GET /flows/api/tasks](https://api.grinfi.io/openapi/tasks/listtasks.md): Retrieve outreach tasks with filtering. Tasks can be manual (created by you) or automatic (generated by automations). Filter by automation = manual or auto.

### Create a task

 - [POST /flows/api/tasks](https://api.grinfi.io/openapi/tasks/createtask.md): Create a manual outreach task. Common types: linkedin_send_message, linkedin_send_connection_request, linkedin_send_inmail, linkedin_like_latest_post, linkedin_endorse_skills.

### Get a task

 - [GET /flows/api/tasks/{uuid}](https://api.grinfi.io/openapi/tasks/gettask.md): Retrieve details of a specific task.

### Complete a task

 - [PUT /flows/api/tasks/{uuid}/complete](https://api.grinfi.io/openapi/tasks/completetask.md): Mark a manual task as completed. Only works for manual tasks.

### Cancel a task

 - [PUT /flows/api/tasks/{uuid}/cancel](https://api.grinfi.io/openapi/tasks/canceltask.md): Cancel a manual task. Only works for manual tasks.

## Sender Profiles

Sender profiles represent the LinkedIn and email accounts used to send outreach messages. Each profile links a LinkedIn browser and/or email mailbox.


### List sender profiles

 - [GET /flows/api/sender-profiles](https://api.grinfi.io/openapi/sender-profiles/listsenderprofiles.md): Retrieve all sender profiles. A sender profile represents a person (with linked LinkedIn account and/or email mailbox) who sends outreach messages.

### Create a sender profile

 - [POST /flows/api/sender-profiles](https://api.grinfi.io/openapi/sender-profiles/createsenderprofile.md): Create a new sender profile with a name and optional label.

### Get a sender profile

 - [GET /flows/api/sender-profiles/{uuid}](https://api.grinfi.io/openapi/sender-profiles/getsenderprofile.md): Retrieve details of a sender profile.

### Update a sender profile

 - [PUT /flows/api/sender-profiles/{uuid}](https://api.grinfi.io/openapi/sender-profiles/updatesenderprofile.md): Update a sender profile's name, label, or schedule.

### Delete a sender profile

 - [DELETE /flows/api/sender-profiles/{uuid}](https://api.grinfi.io/openapi/sender-profiles/deletesenderprofile.md): Permanently delete a sender profile.

### Enable a sender profile

 - [PUT /flows/api/sender-profiles/{uuid}/enable](https://api.grinfi.io/openapi/sender-profiles/enablesenderprofile.md): Enable a sender profile so it can be used in automations.

### Disable a sender profile

 - [PUT /flows/api/sender-profiles/{uuid}/disable](https://api.grinfi.io/openapi/sender-profiles/disablesenderprofile.md): Disable a sender profile. It will no longer be used in automations.

## LinkedIn Messages

Send and retrieve LinkedIn messages through your connected sender profiles.


### List LinkedIn messages

 - [GET /flows/api/linkedin-messages](https://api.grinfi.io/openapi/linkedin-messages/listlinkedinmessages.md): Retrieve LinkedIn messages from your unified inbox. Filter by contact, sender profile, conversation, message type (inbox/outbox), and status.

### Send a LinkedIn message

 - [POST /flows/api/linkedin-messages](https://api.grinfi.io/openapi/linkedin-messages/sendlinkedinmessage.md): Send a LinkedIn message to a contact through a sender profile. The message will be queued and sent via the linked LinkedIn account.

### Delete a LinkedIn message

 - [DELETE /flows/api/linkedin-messages/{uuid}](https://api.grinfi.io/openapi/linkedin-messages/deletelinkedinmessage.md): Delete a LinkedIn message record.

## Emails

Send and retrieve emails through your connected mailboxes.


### List emails

 - [GET /emails/api/emails](https://api.grinfi.io/openapi/emails/listemails.md): Retrieve emails from your unified inbox. Filter by contact, sender profile, mailbox, type (inbox/outbox), status, and date range.

### Get an email

 - [GET /emails/api/emails/{uuid}](https://api.grinfi.io/openapi/emails/getemail.md): Retrieve full details of an email by UUID.

### Delete an email

 - [DELETE /emails/api/emails/{uuid}](https://api.grinfi.io/openapi/emails/deleteemail.md): Delete an email record.

### Send an email

 - [POST /emails/api/emails/send-email](https://api.grinfi.io/openapi/emails/sendemail.md): Send a new email to a contact through a connected mailbox.

## Mailboxes

Manage email mailboxes (SMTP/IMAP, Gmail, Outlook) used for sending and receiving emails in outreach campaigns.


### List mailboxes

 - [GET /emails/api/mailboxes](https://api.grinfi.io/openapi/mailboxes/listmailboxes.md): Retrieve all email mailboxes (SMTP/IMAP, Gmail, Outlook) configured in your account.

### Create a mailbox

 - [POST /emails/api/mailboxes](https://api.grinfi.io/openapi/mailboxes/createmailbox.md): Add a new SMTP/IMAP mailbox with connection settings.

### Get a mailbox

 - [GET /emails/api/mailboxes/{uuid}](https://api.grinfi.io/openapi/mailboxes/getmailbox.md): Retrieve details of a specific mailbox.

### Update a mailbox

 - [PUT /emails/api/mailboxes/{uuid}](https://api.grinfi.io/openapi/mailboxes/updatemailbox.md): Update mailbox settings such as sender name, daily limits, or connection details.

### Delete a mailbox

 - [DELETE /emails/api/mailboxes/{uuid}](https://api.grinfi.io/openapi/mailboxes/deletemailbox.md): Delete a mailbox. Optionally reassign automations to another mailbox.

### Activate a mailbox

 - [PUT /emails/api/mailboxes/{uuid}/activate](https://api.grinfi.io/openapi/mailboxes/activatemailbox.md): Enable a mailbox so it can send and sync emails.

### Deactivate a mailbox

 - [PUT /emails/api/mailboxes/{uuid}/deactivate](https://api.grinfi.io/openapi/mailboxes/deactivatemailbox.md): Disable a mailbox. It will stop sending and syncing emails.

## AI Templates

Manage AI message templates for generating personalized outreach messages at scale.


### List AI templates

 - [GET /flows/api/ai-templates](https://api.grinfi.io/openapi/ai-templates/listaitemplates.md): Retrieve AI message templates for generating personalized outreach messages.

### Create an AI template

 - [POST /flows/api/ai-templates](https://api.grinfi.io/openapi/ai-templates/createaitemplate.md): Create a new AI template for generating outreach messages.