> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theswarm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Common questions about The Swarm API — v3 migration, data coverage, queries, credits, and data quality.

## v3 Migration

<AccordionGroup>
  <Accordion title="What's changing in v3?">
    v3 is built on a refreshed dataset with \~98% fewer duplicate and corrupted profiles. The team-network Network Mapper has been renamed to **Relationships** and is **free** to call. A separate partner-only **Network Mapper** endpoint replaces the v2 partner network endpoint. Two fields are removed from Fetch Profile (`connections`, `notes`), and new profile fields are added (`hiring`, `open_to_work`, `start_date_confidence`, `current_company_logo_url`, plus `company.logo_url` on each experience entry).

    Full details: [Migrating to v3](/docs/getting-started/migrating-to-v3).
  </Accordion>

  <Accordion title="Is v3 live? When will v2 stop working?">
    v3 is now live. v2 endpoints will be deprecated on **July 15, EOD UTC**.
  </Accordion>

  <Accordion title="Which endpoints move to v3?">
    Only 8 endpoints move to v3: profile/company search and fetch, Relationships, Network Mapper (Partner), and the two status endpoints. Everything else (Social, on-demand Refresh, Team, Credits, MCP) stays on its current path. See the [endpoint mapping table](/docs/getting-started/migrating-to-v3#endpoint-mapping).
  </Accordion>

  <Accordion title="Can I still use v2 IDs in v3?">
    Some v2 IDs have been removed in v3, and some profiles re-added under new IDs. If a v2 ID no longer exists in v3, the Fetch endpoint returns a standard 404. See [Migrating to v3](/docs/getting-started/migrating-to-v3) for the transition behavior.
  </Accordion>
</AccordionGroup>

## General

<AccordionGroup>
  <Accordion title="Where do I get an API key?">
    Generate your key from **Team Settings → API**. Full walkthrough in the [Quickstart](/docs/getting-started/quickstart).
  </Accordion>

  <Accordion title="What's the rate limit?">
    See [Rate Limiting](/docs/api-reference/rate-limiting) for current limits.
  </Accordion>

  <Accordion title="If we give you a list of profiles, can you refresh them weekly or monthly?">
    Yes. Our on-demand scraping system supports scheduled refreshes for selected profiles on a weekly or monthly basis. See [Refresh a Profile](/docs/on-demand/refresh-profile).
  </Accordion>

  <Accordion title="Are null values returned?">
    Null values are omitted by default.
  </Accordion>

  <Accordion title="How often do you refresh the data?">
    Data is sourced from multiple vendors, each with their own update schedules. Job changes are detected continuously — see [Daily Job Changes](/docs/signals/daily-job-changes) for freshness targets (90% updated within 7 days of a change).
  </Accordion>

  <Accordion title="What does the `sources` field in connections mean?">
    Each connection lists one or more `sources`, each with an `origin` describing how the connection was discovered.

    <Note>
      **Heads up — two different origin vocabularies.** The values below describe the **response-side** `connections[].sources[].origin` field. If you're building a **query** against `team_connections.origins`, that field uses a different value set — see [the Relationships examples](/docs/examples/relationships-endpoint#filtering-by-team-connection-origin) for the query vocabulary.
    </Note>

    In **v3**, accepted response-side `origin` values:

    * **`linkedin_connection`** — connection imported from LinkedIn
    * **`work_overlap`** — derived from shared work history (overlapping employer + dates)
    * **`education_overlap`** — derived from shared education (same school + graduation year)
    * **`shared_investor`** — derived from shared investors (shared portfolio companies)
    * **`email_contact`** — imported from email contacts
    * **`calendar_events`** — imported from calendar events
    * **`manual_import`** — connections added manually by a team member

    **In v2**, each `source` also carries a `network` field (e.g. `google`, `linkedin`, `investor-data`) alongside `origin`. v3 returns only `origin`.
  </Accordion>
</AccordionGroup>

## Data & Coverage

<AccordionGroup>
  <Accordion title="How often is new data available?">
    Fresh data is available daily. Job changes typically range from 10k–50k profiles per day.
  </Accordion>

  <Accordion title="How does The Swarm handle duplicate profiles?">
    We use an internal deduplication algorithm to merge duplicates. **v3 eliminated \~98% of the duplicate and corrupted profiles** that existed in v2.
  </Accordion>

  <Accordion title="How accurate are job changes?">
    We target accuracy within **14 days** of a job change. **90% of the database is updated within 7 days** of a detected change. See [Daily Job Changes](/docs/signals/daily-job-changes) for the full freshness model.
  </Accordion>

  <Accordion title="Will IDs be consistent across data loads?">
    Within a major version, yes — IDs are persistent for both people and companies. v3 introduced new IDs for some profiles; see [Migrating to v3](/docs/getting-started/migrating-to-v3).
  </Accordion>

  <Accordion title="Do you provide phone numbers?">
    No. Phone numbers are not on the roadmap.
  </Accordion>

  <Accordion title="Do you provide gender or diversity insights?">
    No. We do not track gender, ethnicity, or other diversity-related data.
  </Accordion>

  <Accordion title="Do you have employment type in your dataset?">
    No. Employment type is not part of the default public profile, so coverage in ethical sources is very limited.
  </Accordion>

  <Accordion title="Are LinkedIn URLs standardised?">
    Yes. LinkedIn URLs are generated from the username, ensuring consistency.
  </Accordion>

  <Accordion title="Do you have LinkedIn job descriptions?">
    Yes. If a person has a job description on LinkedIn, it's available in our data.
  </Accordion>

  <Accordion title="Are company logos available?">
    Yes. In v3, the profile includes `profile_info.current_company_logo_url` for the current company, and each experience entry includes `experience[].company.logo_url`. Both are CDN URLs.
  </Accordion>

  <Accordion title="What are the new `hiring` and `open_to_work` fields?">
    Both are booleans on `profile_info`. `hiring` signals the profile is actively hiring; `open_to_work` signals they're open to new opportunities. See [Profile](/docs/enrichment-data/profile).
  </Accordion>

  <Accordion title="What is `start_date_confidence`?">
    A string field on each experience entry indicating the confidence of the start date. Values: `validated` or `low`.
  </Accordion>

  <Accordion title="How does The Swarm protect user privacy?">
    We comply with industry standards and privacy regulations. For data subject requests, see [Data Subject Requests](/docs/miscellaneous/data-subject-requests).
  </Accordion>

  <Accordion title="Can data be exported in bulk?">
    Yes. Flat files are delivered in batches (typically 100,000 records). See [Flat Files](/docs/flat-files/overview).
  </Accordion>
</AccordionGroup>

## API & Usage

<AccordionGroup>
  <Accordion title="What format does the API return?">
    JSON.
  </Accordion>

  <Accordion title="How is API credit usage calculated?">
    Credits are charged based on **results returned**, not requests made:

    * **Profile/Company fetch** — 1 credit per record returned
    * **Search** — Free
    * **[Relationships](/docs/endpoints/v3/relationships)** (team network) — Free
    * **[Network Mapper](/docs/endpoints/v3/network-mapper)** (partner) — 1 credit per non-empty response
    * **[Refresh a Profile](/docs/on-demand/refresh-profile)** — 3 credits per profile returned
    * **Get Profile/Company Posts** — 1 credit per 10 posts returned (rounded up, max 10/call)
    * **Get Comments / Reactions / Reshares** — flat 1 credit per call
    * **Failed requests** (non-200) — Free

    Full breakdown: [Credits & Usage](/docs/api-reference/credits-usage). Plans and overage rates: [How API Credits Work](https://help.theswarm.com/en/articles/14301925-how-api-credits-work).
  </Accordion>

  <Accordion title="If I search then fetch the IDs, am I charged twice?">
    No. Search is **free**. You're only charged for the results returned by the Fetch call (1 credit per profile or company record).
  </Accordion>

  <Accordion title="Where can I see my credit usage?">
    Your current usage is visible on the [Subscription page](https://app.theswarm.com/team-settings/subscription) (credits used, remaining, and estimated overage). For a breakdown by request type, see the [API Usage](https://app.theswarm.com/team-settings/api) section of Team Settings. Programmatic access: [`GET /credits/usage`](/docs/api-reference/credits-usage).
  </Accordion>

  <Accordion title="Can I cap API spend at my plan's included credits?">
    Yes. Turn on **Overage protection** in the [API settings](https://app.theswarm.com/api#overage-protection). It's off by default — when on, credit-consuming endpoints pause with a `402` once you hit your monthly limit, and no overage charges occur. See [Overage protection](/docs/api-reference/credits-usage#overage-protection).
  </Accordion>

  <Accordion title="How big is a single fetch response?">
    Up to **1000 IDs per call** for Fetch Profile / Fetch Company. Search also returns up to 1000 IDs per page.
  </Accordion>

  <Accordion title="How do I search profiles in my own network?">
    Use the `in_network_only: true` parameter in [Search Profiles](/docs/endpoints/v3/search-profiles), or use the dedicated [Relationships](/docs/endpoints/v3/relationships) endpoint which is free and returns connection details.
  </Accordion>

  <Accordion title="Can I search by connection strength or list membership?">
    Not directly. Fetch profiles with the relevant fields and apply filtering in your downstream processing.
  </Accordion>

  <Accordion title="How do I retrieve data for specific IDs?">
    Use [`POST /v3/profiles/fetch`](/docs/endpoints/v3/fetch-profile) for profiles or [`POST /v3/companies/fetch`](/docs/endpoints/v3/fetch-company) for companies.
  </Accordion>

  <Accordion title="What's the difference between Relationships and Network Mapper?">
    * **[Relationships](/docs/endpoints/v3/relationships)** — returns profiles connected to your own team. Free, synchronous response. Available to all API keys.
    * **[Network Mapper](/docs/endpoints/v3/network-mapper)** — maps connections across the **partner** network. 1 credit per non-empty response. Requires partner permission (returns 403 otherwise).
  </Accordion>

  <Accordion title="Can I filter Relationships results by sync origin?">
    Yes. The profile document includes a nested `team_connections.origins` field — query it with a [nested query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-nested-query.html) inside the OpenSearch DSL `query`, typically scoped to your `team_connections.team_id`. Accepted values (provisional, may change): `csv`, `plugin`, `overlaps`, `google`, `google-calendar`, `user-profile`, `manual-csv`, `education-overlaps`, `investor-overlaps`, `manual-url`. See [Relationships endpoint examples](/docs/examples/relationships-endpoint#filtering-by-team-connection-origin).

    Note: this is the **query-side** vocabulary. The response-side `connections[].sources[].origin` field uses a different set of values — see the [sources field FAQ](#what-does-the-sources-field-in-connections-mean).
  </Accordion>

  <Accordion title="Can I add or remove connectors via the API?">
    **Add Connector** is generally available and works with any API key — see [Add Connector](/docs/team-management/connector). **Removal** is not yet automated; contact [support@theswarm.com](mailto:support@theswarm.com).
  </Accordion>

  <Accordion title="Can I programmatically create new Swarm accounts?">
    Yes, with a **partner-level** API key. Contact [support@theswarm.com](mailto:support@theswarm.com) to discuss partner access.
  </Accordion>

  <Accordion title="Can I filter profiles based on job tenure?">
    Not as a single field, but you can derive tenure from the `experience[].start_date` and `experience[].end_date` fields in the Fetch response. In v3, `experience[].start_date_confidence` indicates how reliable the start date is.
  </Accordion>

  <Accordion title="Do you have filters for company revenue?">
    No. Revenue data is not currently planned.
  </Accordion>
</AccordionGroup>

## Data Quality

<AccordionGroup>
  <Accordion title="Are employment records always linked to company IDs?">
    Not always. Smaller companies may lack persistent IDs.
  </Accordion>

  <Accordion title="How is full-name formatting handled?">
    Names are user-generated on LinkedIn, so variations exist. Full names may include middle names or initials.
  </Accordion>

  <Accordion title="Can I see what data changed in a profile?">
    Not directly, but timestamps indicate when updates occurred. The `current_job_updated_at` field is the primary signal for job-change tracking — see [Daily Job Changes](/docs/signals/daily-job-changes).
  </Accordion>

  <Accordion title="What do the various timestamp fields mean?">
    Example: Sarah was a Client Success Manager at Company A. She moved to Company B in January 2024 with the same title. In March 2024 she updated her public profiles. In July she was promoted to Senior Client Success Manager — published immediately.

    Sarah's timestamps:

    * **`current_job_updated_at`** — the moment The Swarm detected a change in her primary job. `2024-03-08T...` between March and July, then `2024-07-15T...` after the promotion.
    * **`latest_company_change_at`** — start date (rounded to full months) of the latest company change: `2024-01-01` (when she actually started at Company B).
    * **`latest_role_change_at`** — start date of the latest title change: `2024-07-01`.
    * **`job_start_date`** — the greater of `latest_company_change_at` and `latest_role_change_at`.
    * **`updated_at`** — technical timestamp of the last update to any field on the profile.
  </Accordion>

  <Accordion title="How do you detect fake profiles?">
    We don't currently detect or filter fake profiles. We do filter out empty profiles (those missing basic information).
  </Accordion>

  <Accordion title="Is there a completeness score for profiles?">
    Not a single field. The number of LinkedIn job experiences is available and can help assess completeness. Profiles vary in richness — Name and Company are the minimum required for a profile to be retained, and profiles can be enriched over time.
  </Accordion>

  <Accordion title="Why do some company records lack LinkedIn or website data?">
    We only keep companies with high-quality extracted data. We're continuously expanding company coverage.
  </Accordion>

  <Accordion title="Can I expect better work-email coverage soon?">
    Yes. We're actively working on improvements aimed at increasing work-email availability to up to 80%.
  </Accordion>

  <Accordion title="Why is the education degree field an array?">
    Some people hold multiple degrees. In most cases the array contains a single value.
  </Accordion>

  <Accordion title="Why are some profiles outdated?">
    Our job-change tracking is continuously improving and some gaps exist in historical data. See [Daily Job Changes](/docs/signals/daily-job-changes) for our current freshness targets.
  </Accordion>
</AccordionGroup>