Leadfeeder API
    • Leadfeeder API
    • Authentication
    • Getting Started
    • Rate Limits
    • Relationships
    • Company ID Lifecycle
    • Service Users
    • OpenAPI Specification Access
    • List of NACE / WZ codes
    • List of Industries
    • AI & MCP
      • Overview of the Leadfeeder MCP Server
      • Quickstart
      • Connect your AI tool
      • Authentication and permissions
    • Account
      • List Accounts
    • Companies
      • Retrieve Companies
      • Create Company Enrichment Job
      • Estimate Company Enrichment Job
      • Get Company Enrichment Job Status
      • Retrieve Company IPs
      • Match Companies
      • Search Companies
      • Search Company Signals
      • Get Company Details
      • Update a Company
      • Company Financial Reports
      • Remove Company from Lists
      • Add Company to Lists
      • Unassign Tags from Company
      • Assign Tags to Company
    • Contacts
      • Retrieve Contacts
      • Create Find Contact Data Job
      • Estimate Find Contact Data Job
      • Get Find Contact Data Job Status
      • Search Contacts
      • Get Contact Details
      • Update a Contact
      • Remove Contact from Lists
      • Add Contact to Lists
    • Web Visits
      • How to Create Custom Feed
      • Custom Feed - Filter Reference
      • Search Web Visits
      • Retrieve Visitor Companies
      • Retrieve Custom Feeds
      • Create a Custom Feed
      • Retrieve Custom Feeds Folders
      • Delete a Custom Feed
      • Get Custom Feed Details
      • Update Custom Feed
      • Retrieve Goals
      • Create a Goal
      • Delete a Goal
      • Get Goal Details
      • Update a Goal
      • Retrieve Web Visits Tracker Script
    • Campaigns
      • Retrieve Campaigns
      • Get Campaign Details
      • Update Campaign
      • Retrieve Campaign Stats
    • IP
      • Enrich Company IP Address
    • Buyer Personas
      • Retrieve Buyer Personas
      • Create a Buyer Persona
      • Delete a Buyer Persona
      • Get Buyer Persona Details
      • Update a Buyer Persona
    • Ideal Customer Profiles
      • Retrieve Ideal Customer Profiles
      • Create an Ideal Customer Profile
      • Retrieve Company ICP Matches
      • Delete an Ideal Customer Profile
      • Get Ideal Customer Profile Details
      • Update an Ideal Customer Profile
    • Tags
      • Retrieve Tags
      • Create Tag
      • Create Batch Add Tags Job
      • Get Batch Add Tags Job
      • Create Batch Remove Tags Job
      • Get Batch Remove Tags Job
      • Delete Tag
      • Get Tag Details
      • Update Tag
    • Lists
      • Retrieve Lists
      • Create a List
      • Create Batch Add to List Job
      • Get Batch Add to List Job
      • Create Batch Remove from List Job
      • Get Batch Remove from List Job
      • Retrieve Company List Memberships
      • Retrieve Contact List Memberships
      • Delete List
      • Get List Details
      • Update List
      • Retrieve List Items
    • Custom Fields
      • Retrieve Custom Fields
      • Create Custom Field
      • Delete Custom Field
      • Get Custom Field Details
      • Update Custom Field
    • Users
      • Get Current User
    • Settings
      • Get Cookie Consent Settings
      • Update Cookie Consent Settings
      • Get Data Processing Settings
      • Update Data Processing Settings
    • Usage
      • Get Endpoints Usage
    • Reference Data
      • Get Countries with Regions
      • Get Geo Suggestions
      • Get Industries
    • CRM
      • Create Connect CRM Record Job
      • Get Connect CRM Record Job
      • Create CRM Contact Job
      • Get CRM Contact Job
      • Create CRM Lead Job
      • Get CRM Lead Job
      • Create CRM Organization Job
      • Get CRM Organization Job
      • Update CRM Connection
      • Get CRM Contact
      • Get CRM Lead
      • Get CRM Organization
      • List CRM Users
      • Create Disconnect CRM Record Job
      • Get Disconnect CRM Record Job
      • Create Enrich CRM Record Job
      • Get Enrich CRM Record Job
    • Subscriptions
      • Create a Purchase Link
      • Get Purchase Options
    • Schemas
      • AccountCompanyV1
      • AccountSummaryV1
      • AccountV1
      • ApiUsageV1
      • BatchAddTagsJobV1
      • BatchAddToListJobV1
      • BatchRemoveFromListJobV1
      • BatchRemoveTagsJobV1
      • BuyerPersonaRequestV1
      • BuyerPersonaV1
      • CRMConnectionV1
      • CRMContactV1
      • CRMLeadV1
      • CRMOrganizationV1
      • CRMUserV1
      • CampaignLocationV1
      • CampaignSettingsV1
      • CampaignStatsV1
      • CampaignSummaryV1
      • CampaignV1
      • CompaniesAdvancedSearchFilterItem
      • CompanyFinancialsV1
      • CompanyIndustryV1
      • CompanyIpV1
      • CompanyMatchV1
      • CompanyLocationV1
      • CompanySummaryV1
      • CompanyV1
      • ContactFilterGroupsV1
      • ConnectedListV1
      • ConnectCRMRecordJobV1
      • ContactV1
      • CookieConsentSettingsV1
      • ContactPreviewV1
      • ContactSummaryV1
      • CountryV1
      • CustomFeedFolderV1
      • CustomFieldV1
      • CreateCRMContactJobV1
      • DataProcessingSettingsV1
      • CreateCRMLeadJobV1
      • EnrichedIpV1
      • CreateCRMOrganizationJobV1
      • ErrorObjectV1
      • CustomFeedRequestV1
      • GeoSuggestionV1
      • CustomFeedV1
      • IpAddressExtendedV1
      • DisconnectCRMRecordJobV1
      • CRMSuggestionV1
      • GoalCreateRequestV1
      • EnrichCRMRecordJobV1
      • IpLocationV1
      • GoalUpdateRequestV1
      • CRMGroupConnectionV1
      • EnrichmentJobV1
      • LocationV1
      • MaskedCompanySummaryV1
      • FindContactDataJobV1
      • IcpRequestV1
      • NetworkV1
      • MaskedContactSummaryV1
      • UserV1
      • GoalV1
      • TagV1
      • VisitLocationV1
      • ICPV1
      • WebVisitsTrackerScriptV1
      • ListV1
      • SignalV1
      • PurchaseLinkV1
      • SubscriptionV1
      • PurchaseOptionsV1
      • WebVisitV1

    Service Users

    A Service User lets an application or AI agent connect to the Leadfeeder API or MCP server without a person signing in. You create it by choosing "Dedicated service user" when you register an OAuth app in Developer Access. The app then acts as its own identity, and it keeps working when employees join or leave.
    This guide covers the API and the MCP server.

    When to use a Service User#

    When you create an OAuth app, you choose who it "Acts as".
    People who connect itDedicated service user
    Who makes the callsEach person who connects the app signs in and grants their own accessThe app's own service user, named after the app
    Sign-in neededYesNo
    Redirect URIsRequiredNot used
    Account accessThe accounts of the person who connectedEvery account in your company, including accounts created later
    If a person leavesTheir access stopsNot affected
    Best forApps people connect to with their own loginShared AI agents, background jobs, automations and partner apps that call the API or MCP server
    WARNING
    This choice is permanent. You select "Acts as" when you create the app, and it cannot be changed afterwards. If you need the other mode, create a new app.

    What a Service User is and is not#

    • It is created for you when you create the app and removed when you delete the app.
    • It has no password and cannot sign in to Leadfeeder.
    • It does not appear in team management and does not use a seat.
    • Calls are attributed to the app, not to a person.
    • Credits are charged normally to the account the call is made on.

    Before you start#

    You need the Applications Management permission. If you do not see Developer Access under Settings > Company, ask a company admin to grant it.

    Step 1: Create the app#

    1.
    Go to Settings > Company > Developer Access.
    2.
    Create a new application and give it a clear name, for example "Marketing Copilot agent" or "Nightly high-intent list sync". The service user uses this name, and it is how activity is identified.
    3.
    Under Acts as, select Dedicated service user. The redirect URI fields disappear because nobody signs in.
    4.
    Select the scopes the app needs. Choose the minimum. For example, an agent that answers questions about website visitors needs web_visits:read and companies:read. A job that also adds companies to a list needs lists:write. Add contacts:read only when it needs personal contact details.
    5.
    Save the app.

    Step 2: Store the credentials#

    Copy the Client ID and Client Secret. Store the secret in your secrets manager. Do not put it in code, chat messages or logs.
    Anyone with both values can act as the app within its scopes.

    Step 3: Request an access token#

    The app uses the OAuth 2.0 client credentials flow. Send the Client ID and Client Secret to the token endpoint. You can send them in the request body or in a Basic authorization header.
    Token endpoint: https://api.leadfeeder.com/v1/oauth/token
    Credentials in the request body:
    Credentials in a Basic header:
    Scopes are space separated. The token only gets the scopes you request that the app is also allowed to use. Request the scopes you need explicitly so the token stays as narrow as possible.
    The response contains an access token:
    {
      "access_token": "YOUR_ACCESS_TOKEN",
      "token_type": "Bearer",
      "expires_in": 3600,
      "scope": "web_visits:read companies:read"
    }
    Access tokens last 1 hour. There is no refresh token. When a token expires, request a new one with the same call. Most OAuth libraries and automation tools do this for you when you select "client credentials".

    Step 4: Call the API#

    Send the token as a bearer token. Start by listing the accounts the service user can reach:
    Most endpoints need an account_id. Use an ID from that response. For example, to read the companies that visited your website:

    Use it with the MCP server#

    Tools such as Microsoft Copilot Studio and other agent platforms that support OAuth client credentials can connect to the Leadfeeder MCP server with the same Client ID and Client Secret. This is how a shared marketing agent can answer questions about your website visitors for the whole team.
    SettingValue
    Server URLhttps://mcp.leadfeeder.com/mcp
    Token URLhttps://mcp.leadfeeder.com/token
    Grant typeClient credentials
    Client authenticationClient secret in the body or in a Basic header
    ScopesThe scopes you selected for the app
    Everyone who uses the agent shares the one connection. People are not asked to sign in.

    Account access#

    A service user can use every account in your company, including accounts you create later. You do not need to update the app when a new account is added. It cannot reach accounts that belong to other companies.

    Manage and remove the app#

    • Check the mode. The app details in Developer Access show whether the app acts as people who connect it or as a dedicated service user.
    • Stop access. Delete the app. This removes the service user and revokes every token the app has issued. Use this when an agency contract ends.
    • Secret exposed. Delete the app and create a new one, then update the credentials in your tool.

    Troubleshooting#

    ProblemWhat to check
    The token request is rejectedCheck the Client ID and Client Secret, and that the app was created as "Dedicated service user". Apps set to "People who connect it" are for sign-in flows.
    The API returns insufficient_scopeThe token does not include the scope that endpoint needs. For example, adding companies to a list needs lists:write. Add the scope to the app and request a new token.
    The API returns invalid_tokenThe token expired or is invalid. Request a new one.
    An account is missingCall GET /v1/accounts with the token and confirm the account belongs to the same company as the app.
    You cannot create a dedicated service userYou need the Applications Management permission. Ask a company admin.

    FAQ#

    Can I switch an existing app to a dedicated service user?
    No. Create a new app and choose "Dedicated service user".
    Does it use a seat or a license?
    No. Service users do not appear in team management or seat counts.
    Does it still use credits?
    Yes. Credits are charged to the account the call is made on, the same as for any other API or MCP call.
    Do I need a Service User for a personal script?
    Not necessarily. A personal API key or a normal OAuth app is simpler for one marketer's own script. Use a Service User when more than one person depends on the connection, or when it must outlive any single employee.
    Is a Service User the same as an API key?
    No. An API key belongs to a person. A Service User belongs to the app and is limited to the scopes you select.
    Modified at 2026-11-16 09:52:53
    Previous
    Company ID Lifecycle
    Next
    OpenAPI Specification Access
    Built with