Run a saved segment

Run a saved segment again on today's data, with the same answer as a new one and the segment beside it.

The segment a save answered with, by its id, run again: the same answer as POST /v1/{country_code}/segments — filters as interpreted, count, exportable_count, facets, sample, prospecting, sources — with the stored segment under segment. The count is today's, and its windows count from today, so head_office_moved_within_days: 182 covers the 182 days before sources.relative_to, not before the day it was saved.

A segment saved with sole traders lists them under its stored acknowledgement, repeated as prospecting.acknowledgement; you do not send it again. facet_limit goes in the query string, ?facet_limit=20, 1 to 100 and 10 by default; any other value is 400 invalid_request, and nothing is counted.

read -rs FIRMUS_KEY && export FIRMUS_KEY

curl -s -H "Authorization: Bearer $FIRMUS_KEY" \
  "https://api.firmus.sh/v1/fr/segments/1?facet_limit=20"

One call — on Free, one of the month's 1 000 lookups. A segment of another organization and an id that never existed are both 404 not_found, and cannot be told apart. A server that cannot count segments yet answers 503 segment_index_unavailable, and counts nothing.

GET/v1/{country_code}/segments/{id}Scope read

Parameters

Parameter	In	Type	Required	Example
country_code	path	string	Yes	fr
id	path	integer	Yes	1
facet_limit	query	integer	No	1

Request

bash

curl -H "Authorization: Bearer $FIRMUS_KEY" \
  "https://api.firmus.sh/v1/fr/segments/1"

Fields

segmentobject
- idinteger
- namestring
- filtersobject
  - activitystring[]optional
    - []stringoptional
  - legal_formstring[]optional
    - []stringoptional
- include_sole_tradersboolean
- acknowledgementobjectnullable
  - versionstring
  - acknowledged_atstring
  - acknowledged_bystring
  - textstringoptional
- created_atstring
- updated_atstring
filtersobject
- activityobject[]optional
  - []objectoptional
    - codestring
    - levelstring
    - labelstringnullable
- legal_formobject[]optional
  - []objectoptional
    - codestring
    - levelstring
    - labelstringnullable
countinteger
exportable_countinteger
facetsobject
- departementobject
  - valuesobject[]
    - []objectoptional
      valuestring
      labelunspecifiednullable
      countinteger
  - otherinteger
- activity_divisionobject
  - valuesobject[]
    - []objectoptional
      valuestring
      labelstringnullable
      countinteger
  - otherinteger
- workforceobject
  - valuesobject[]
    - []objectoptional
      valuestring
      labelstring
      countinteger
  - otherinteger
- legal_formobject
  - valuesobject[]
    - []objectoptional
      valuestring
      labelstring
      countinteger
  - otherinteger
sampleobject[]
- []objectoptional
  - registry_numberstring
  - namestring
  - legal_formobject
    - codestringnullable
    - labelstringnullable
  - registered_onstringnullable
  - activityobject
    - codestringnullable
    - schemestringnullable
    - labelstringnullable
  - workforceobject
    - codestringnullable
    - labelstringnullable
    - yearintegernullable
  - size_categoryobject
    - codestringnullable
    - labelstringnullable
    - yearintegernullable
  - head_office_addressobject
    - addressstringnullable
    - postal_codestringnullable
    - citystringnullable
    - departementstringnullable
  - sourcesobject
    - registrystring
    - data_updated_atstringnullable
    - head_office_data_updated_atstringnullable
    - legalunspecifiednullable
prospectingobject
- include_sole_tradersboolean
- acknowledgementobjectnullable
  - versionstring
  - acknowledged_atstring
  - acknowledged_bystring
  - textstringoptional
- lists_partially_disclosedboolean
- noticestring
sourcesobject
- registrystring
- legalunspecifiednullable
- indexobject
  - built_atstring
  - patched_atstringnullable
  - fed_throughstring
- relative_tostring

Responses

Runs a saved segment again on today's index: the same answer as POST, with the segment. Its relative windows count from today. One call.

{
  "segment": {
    "id": 1,
    "name": "Software",
    "filters": {
      "activity": [
        "62"
      ]
    },
    "include_sole_traders": true,
    "acknowledgement": {
      "version": "sole-traders-2026-11-01",
      "acknowledged_at": "2026-10-30T08:00:00Z",
      "acknowledged_by": "api_key:7",
      "text": "The customer is the controller of any prospecting of the sole traders (entrepreneurs individuels) this segment lists, who are natural persons: it informs each of them under article 14 of the GDPR when it first uses their data, and it honours their opposition to prospecting."
    },
    "created_at": "2026-11-01T09:00:00Z",
    "updated_at": "2026-11-01T09:00:00Z"
  },
  "filters": {
    "activity": [
      {
        "code": "62",
        "level": "division",
        "label": "Programmation, conseil et autres activités informatiques"
      }
    ]
  },
  "count": 4,
  "exportable_count": 3,
  "facets": {
    "departement": {
      "values": [
        {
          "value": "75",
          "label": null,
          "count": 3
        },
        {
          "value": "69",
          "label": null,
          "count": 1
        }
      ],
      "other": 0
    },
    "activity_division": {
      "values": [
        {
          "value": "62",
          "label": "Programmation, conseil et autres activités informatiques",
          "count": 4
        }
      ],
      "other": 0
    },
    "workforce": {
      "values": [
        {
          "value": "11",
          "label": "10 à 19 salariés",
          "count": 2
        },
        {
          "value": "00",
          "label": "0 salarié",
          "count": 1
        },
        {
          "value": "21",
          "label": "50 à 99 salariés",
          "count": 1
        }
      ],
      "other": 0
    },
    "legal_form": {
      "values": [
        {
          "value": "5710",
          "label": "SAS, société par actions simplifiée",
          "count": 3
        },
        {
          "value": "1000",
          "label": "Entrepreneur individuel",
          "count": 1
        }
      ],
      "other": 0
    }
  },
  "sample": [
    {
      "registry_number": "100000017",
      "name": "BETA CONSEIL",
      "legal_form": {
        "code": "5710",
        "label": "SAS, société par actions simplifiée"
      },
      "registered_on": "2020-03-02",
      "activity": {
        "code": "62.02A",
        "scheme": "naf2008",
        "label": "Conseil en systèmes et logiciels informatiques"
      },
      "workforce": {
        "code": "21",
        "label": "50 à 99 salariés",
        "year": 2023
      },
      "size_category": {
        "code": "PME",
        "label": "Petite ou moyenne entreprise",
        "year": 2023
      },
      "head_office_address": {
        "address": "2 PLACE BELLECOUR",
        "postal_code": "69002",
        "city": "LYON",
        "departement": "69"
      },
      "sources": {
        "registry": "insee_sirene",
        "data_updated_at": "2026-10-01T00:00:00Z",
        "head_office_data_updated_at": "2026-10-01T00:00:00Z",
        "legal": null
      }
    },
    {
      "registry_number": "100000033",
      "name": "JEAN DUPONT",
      "legal_form": {
        "code": "1000",
        "label": "Entrepreneur individuel"
      },
      "registered_on": "2020-03-02",
      "activity": {
        "code": "62.01Z",
        "scheme": "naf2008",
        "label": "Programmation informatique"
      },
      "workforce": {
        "code": "00",
        "label": "0 salarié",
        "year": 2023
      },
      "size_category": {
        "code": "PME",
        "label": "Petite ou moyenne entreprise",
        "year": 2023
      },
      "head_office_address": {
        "address": "1 RUE DE LA PAIX",
        "postal_code": "75008",
        "city": "PARIS",
        "departement": "75"
      },
      "sources": {
        "registry": "insee_sirene",
        "data_updated_at": "2026-10-01T00:00:00Z",
        "head_office_data_updated_at": "2026-10-01T00:00:00Z",
        "legal": null
      }
    },
    {
      "registry_number": "100000009",
      "name": "ALPHA LOGICIEL",
      "legal_form": {
        "code": "5710",
        "label": "SAS, société par actions simplifiée"
      },
      "registered_on": "2020-03-02",
      "activity": {
        "code": "62.01Z",
        "scheme": "naf2008",
        "label": "Programmation informatique"
      },
      "workforce": {
        "code": "11",
        "label": "10 à 19 salariés",
        "year": 2023
      },
      "size_category": {
        "code": "PME",
        "label": "Petite ou moyenne entreprise",
        "year": 2023
      },
      "head_office_address": {
        "address": "1 RUE DE LA PAIX",
        "postal_code": "75008",
        "city": "PARIS",
        "departement": "75"
      },
      "sources": {
        "registry": "insee_sirene",
        "data_updated_at": "2026-10-01T00:00:00Z",
        "head_office_data_updated_at": "2026-10-01T00:00:00Z",
        "legal": null
      }
    }
  ],
  "prospecting": {
    "include_sole_traders": true,
    "acknowledgement": {
      "version": "sole-traders-2026-11-01",
      "acknowledged_at": "2026-10-30T08:00:00Z",
      "acknowledged_by": "api_key:7",
      "text": "The customer is the controller of any prospecting of the sole traders (entrepreneurs individuels) this segment lists, who are natural persons: it informs each of them under article 14 of the GDPR when it first uses their data, and it honours their opposition to prospecting."
    },
    "lists_partially_disclosed": false,
    "notice": "Built from INSEE Sirene. It does not reflect an opposition to prospecting recorded only in the RNE (diffusionCommerciale), which Firmus does not read yet. Partially disclosed companies are counted but never listed."
  },
  "sources": {
    "registry": "insee_sirene",
    "legal": null,
    "index": {
      "built_at": "2026-11-01T03:00:00Z",
      "patched_at": "2026-11-01T08:47:00Z",
      "fed_through": "2026-11-01T08:46:12Z"
    },
    "relative_to": "2026-11-01"
  }
}

Try it

Calls the real API with a demo key. No account, no signup.

country_code

facet_limit