Skip to content

Grinfi.io API (2.0.0)

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
  2. Go to 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.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL
https://grinfi.io
Grinfi.io Support
support@grinfi.io
License
Copyright
Languages
Servers
Production
https://leadgen.grinfi.io

Contacts

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

Operations

Delete a contact

Request

Permanently delete a contact by UUID. This creates a background deletion job.

Security
bearerAuth
Path
uuidstringrequired

Resource UUID.

curl -i -X DELETE \
  'https://leadgen.grinfi.io/leads/api/leads/{uuid}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Contact deleted.

Response
No content

Create or update a contact

Request

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.

Security
bearerAuth
Bodyapplication/jsonrequired
leadobjectrequired
lead.​linkedin_idstringrequired

LinkedIn profile URL or member ID.

Example: "john-doe-123456"
lead.​first_namestring
Example: "John"
lead.​last_namestring
Example: "Doe"
lead.​company_namestring
Example: "Acme Inc"
lead.​ln_idstring or null
lead.​sn_idstring or null
lead.​linkedinstring or null
lead.​emailstring(email)
Example: "john@acme.com"
lead.​aboutstring
lead.​domainstring

Company domain for email discovery.

Example: "acme.com"
lead.​headlinestring or null
lead.​positionstring or null
lead.​raw_addressstring or null
custom_fieldsobject

Custom field values as key-value pairs.

Example: {"field_position":"CTO","field_experience":"10 years"}
list_uuidstringrequired

Target list UUID.

Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
update_if_existsboolean

Update the contact if it already exists.

Default true
move_to_listboolean

Move existing contact to the specified list.

Default false
curl -i -X POST \
  https://leadgen.grinfi.io/leads/api/leads/upsert \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "lead": {
      "linkedin_id": "john-doe-123456",
      "first_name": "John",
      "last_name": "Doe",
      "company_name": "Acme Inc",
      "email": "john@acme.com"
    },
    "list_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "update_if_exists": true
  }'

Responses

Contact created or updated.

Bodyapplication/json
uuidstring
Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
team_idinteger
user_idinteger or null
sender_profile_uuidstring or null
list_uuidstring
data_source_uuidstring or null
pipeline_stage_uuidstring
company_uuidstring or null
namestring or null
Example: "John Doe"
first_namestring or null
Example: "John"
last_namestring or null
Example: "Doe"
company_namestring or null
Example: "Acme Inc"
company_ln_idstring or null
positionstring or null
Example: "VP of Sales"
headlinestring or null
Example: "VP of Sales at Acme Inc"
aboutstring or null
avatar_urlstring or null
ln_idstring or null

LinkedIn member ID.

sn_idstring or null

Sales Navigator ID.

linkedinstring or null
Example: "john-doe-123456"
facebookstring or null
twitterstring or null
work_emailstring or null
Example: "john@acme.com"
personal_emailstring or null
work_phone_numberstring or null
personal_phone_numberstring or null
connections_numberinteger or null
followers_numberinteger or null
primary_languagestring or null
supported_languagesArray of strings or null
has_open_profileinteger or null
has_verified_profileinteger or null
has_premiuminteger or null
experienceArray of objects or null
postsArray of objects or null
educationsArray of objects or null
skillsArray of strings or null
raw_addressstring or null
Example: "San Francisco, CA, USA"
locationArray of objects or null
tagsArray of strings or null

Tag UUIDs.

statusstring
Example: "ok"
linkedin_statusstring
Example: "active"
email_statusstring or null
unread_countsArray of objects
last_automation_approve_atstring or null(date-time)
created_atstring or null(date-time)
updated_atstring or null(date-time)
Response
application/json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "team_id": 0,
  "user_id": 0,
  "sender_profile_uuid": "string",
  "list_uuid": "string",
  "data_source_uuid": "string",
  "pipeline_stage_uuid": "string",
  "company_uuid": "string",
  "name": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Acme Inc",
  "company_ln_id": "string",
  "position": "VP of Sales",
  "headline": "VP of Sales at Acme Inc",
  "about": "string",
  "avatar_url": "string",
  "ln_id": "string",
  "sn_id": "string",
  "linkedin": "john-doe-123456",
  "facebook": "string",
  "twitter": "string",
  "work_email": "john@acme.com",
  "personal_email": "string",
  "work_phone_number": "string",
  "personal_phone_number": "string",
  "connections_number": 0,
  "followers_number": 0,
  "primary_language": "string",
  "supported_languages": [
    "string"
  ],
  "has_open_profile": 0,
  "has_verified_profile": 0,
  "has_premium": 0,
  "experience": [
    { … }
  ],
  "posts": [
    { … }
  ],
  "educations": [
    { … }
  ],
  "skills": [
    "string"
  ],
  "raw_address": "San Francisco, CA, USA",
  "location": [
    { … }
  ],
  "tags": [
    "string"
  ],
  "status": "ok",
  "linkedin_status": "active",
  "email_status": "string",
  "unread_counts": [
    { … }
  ],
  "last_automation_approve_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Bulk action on contacts

Request

Perform a bulk operation on contacts matching a filter. Supported actions include changing pipeline stage, assigning/removing tags, moving to a list, and deleting.

Security
bearerAuth
Bodyapplication/jsonrequired
typestringrequired

Action type: contact_change_pipeline_stage, contact_assign_tag, contact_remove_tag, contact_move_to_list, contact_delete, contact_mark_read.

Example: "contact_change_pipeline_stage"
payloadobject

Action-specific payload.

Example: {"pipeline_stage_uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}
filterobjectrequired

Filter to select contacts.

Example: {"ids":["uuid-1","uuid-2"]}
filter.​allboolean
filter.​idsArray of strings
Example: ["uuid-1","uuid-2"]
curl -i -X PUT \
  https://leadgen.grinfi.io/leads/api/leads/mass-action \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "contact_change_pipeline_stage",
    "payload": {
      "pipeline_stage_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "filter": {
      "ids": [
        "uuid-1",
        "uuid-2"
      ]
    }
  }'

Responses

Action dispatched.

Bodyapplication/json
countinteger
dataArray of objects
Response
application/json
{
  "count": 0,
  "data": [
    {}
  ]
}

Companies

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

Operations

Lists

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

Operations

Tags

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

Operations

Pipeline

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

Operations

Custom Fields

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

Operations

Notes

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

Operations

Automations

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

Operations

Tasks

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

Operations

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.

Operations

LinkedIn Messages

Send and retrieve LinkedIn messages through your connected sender profiles.

Operations

Emails

Send and retrieve emails through your connected mailboxes.

Operations

Mailboxes

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

Operations

AI Templates

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

Operations