Eligibility Request

Operation

sequenceDiagram participant Client participant Covage API participant Covage Backend Client->>Covage API: Request for offer families sold by Covage Covage API-->>Client: List of offer families Client->>Covage API: Eligibility request for a site to multiple offer families Covage API-->>Client: Eligibility request ID Covage API->>Covage Backend: Eligibility request for a site to multiple offers Covage Backend-->>Covage API: List of eligible offers for this address Client->>Covage API: Retrieve eligibility results Covage API-->>Client: Eligibility results Client->>Covage API: Offer details Covage API->>Covage Backend: Request for pack details with details and price Covage Backend-->>Covage API: Pack details Covage API-->>Client: Offer details

Lifecycle of an eligibility

flowchart LR A[<a href='/en/api-eligibilite-offres/#eligibility-request-for-a-site-to-multiple-offers'>Creation of an eligibility request</a>] -->B(acknowledged) B -->|Processing start| C(in_progress.elig) C -->D{Data\n Control\n OK ?} D -->|no| T[terminated_with_error] D -->|yes| F(in_progress.offer) F -->K{eligible ?} K -->|no| U[done.unable_to_provide] K -->|yes| G{Price calculation ?} G -->|no| H{On quote ?} H -->|yes| U H -->|no| R G -->|yes| P(in_progress.price) P -->R[done.ready]

Request for Offer Families Sold by Covage

Retrieving the offer families sold by Covage

GET /api/v1/catalog/category

Response

Name	Type	Description	Required
name	string	Name of the offer family ('BPE','BPEA')	Yes
type	string	Type of offer family ('OFFER_FAMILY')	Yes
description	string	Description of the offer family	No

Example

    {
        "name": "BPE",
        "type": "OFFER_FAMILY",
        "description": ""
    }

Eligibility Request for a Site to Multiple Offers

Creating an eligibility request to check the eligibility of an address for one or more offers.

POST /api/v1/product_offering_qualification

Request Field Parameters

Name	Type	Description	Required
external_id	string	External identifier for the request	No
project_id	string	Associated project identifier	No
product_offering_qualification_item	array	List of offer qualification items	Yes

Example

  {
  "external_id": "123",
  "project_id": "456",
  "product_offering_qualification_items": [...]
  }

Details for an Offer Qualification

Name	Type	Description	Required
offer_families	array	Requested offer families	Yes
eligibility_id	string	Eligibility identifier (from the address search API)	Yes
resolve_pricing	bool	Retrieve articles' prices (default is no)	No
address	object	Address details to verify	No

Example

  "product_offering_qualification_items": [
    {
      "offer_families": ["BPEA","BPE"],
      "eligibility_id": "{eligibility_id}",
      "resolve_pricing": false,
      "address": {}
    }]

Address Details

Name	Type	Description	Required
label	string	Address label	No
street_ext	string	Street extension	No
street_nr	string	Street number	No
city	object	City details	No
street	object	Street details	No

Example

"address": {
    "label": "4bis Rue Andrei Sakharov 76130 Mont-Saint-Aignan",
    "street_ext": "B",
    "street_nr": "4",
    "city": {},
    "street": {}
    }

City Details

Name	Type	Description	Required
city_id	string	City identifier (from the address search API)	No
insee_code	string	INSEE code of the city	No
city_name	string	City name	No
post_code	string	Postal code of the city	No

Example

"city": {
    "city_id": "76451",
    "insee_code": "76451",
    "city_name": "MONT ST AIGNAN",
    "post_code": "76130"
    }

Street Details

Name	Type	Description	Required
street_id	string	Street identifier (from the address search API)	No
street_name	string	Street name	No

Example

"street": {
    "street_id": "76451055R",
    "street_name": "Rue Andrei Sakharov"
    }

Full request example

{
  "external_id": "123",
  "project_id": "456",
  "product_offering_qualification_items": [
    {
      "offer_families": [
        "BPEA","BPE"
      ],
      "eligibility_id": "KHg6MS4wOTIxMDgxO3k6NDkuNDc0Mzk3MTtiOklNQi83NjQ1MS9DLzAwMTkp",
      "address": {
        "label": "4bis Rue Andrei Sakharov 76130 Mont-Saint-Aignan",
        "street_ext": "B",
        "street_nr": "4",
        "city": {
            "city_id": "76451",
            "insee_code": "76451",
            "city_name": "MONT ST AIGNAN",
            "post_code": "76130"
        },
        "street": {
            "street_id": "76451055R",
            "street_name": "Rue Andrei Sakharov"
        }
      }
    }
  ]
}

Response

Name	Type	Description
id	string	Eligibility request identifier
creation_date	string	Creation date

{
    "id": "2eaf7b5b-384d-4cb7-8d9b-09ac712354d7",
    "creation_date": "2025-04-04T10:07:24.274+02:00",
}

Eligibility Request for a Site to Multiple Offers (synchronous)

POST /api/v1/product_offering_qualification/sync/

Identical to the asynchronous endpoint POST /api/v1/product_offering_qualification/, but returns results directly in the response without the polling mechanism.

Limitations

This endpoint has stricter rate limits. Prefer the asynchronous version for production use.

Parameters and response are identical to POST /api/v1/product_offering_qualification/.

List of eligibility requests

GET /api/v1/product_offering_qualification/

Lists or searches eligibility requests submitted by the client.

Available filters (query params):

Parameter	Type	Description
`state`	string	Filter by state (`pending`, `done`, `failed`…)
`external_id`	string	Filter by external identifier
`project_id`	string	Filter by project identifier
`creation_date_gt`	datetime	Requests created after this date (ISO 8601)
`creation_date_lt`	datetime	Requests created before this date (ISO 8601)

Response: Paginated list of eligibility requests (same fields as GET /product_offering_qualification/{id}/).

Retrieving Eligibility Results

Retrieving the eligibility results of an eligibility request.

GET /api/v1/product_offering_qualification/{id}

Request Field Parameters

Name	Type	Description	Required
id	string	Eligibility request identifier	Yes

Response

Name	Type	Description	Required
id	string	Eligibility request identifier	Yes
user	object	The user who created the eligibility request	Yes
creation_date	string	Request's creation date	Yes
external_id	string	External identifier for the request	No
project_id	string	Associated project identifier	No
effective_qualification_date	string	Effective eligibility date	No
href	string	Link to the resource	No
state	string	Current state of the request	Yes
state_change	array	State change history	Yes
product_offering_qualification_item_details	array	List of product offering qualification items	No

Example

{
    "id": "2eaf7b5b-384d-4cb7-8d9b-09ac712354d7",
    "user": {
        "email": "anonymous@example.fr",
        "first_name": "Ano",
        "last_name": "Nymous"
    },
    "creation_date": "2025-04-04T10:07:24.274+02:00",
    "external_id": "987654",
    "project_id": "456789",
    "effective_qualification_date": null,
    "href": "",
    "state": "done.ready",
    "state_change": [...],
    "product_offering_qualification_item_detail": [...]
}

User Details

Nom	Type	Description	Obligatoire
email	string	User's email adress	Yes
first_name	string	User's first name	Yes
last_name	string	User's last name	Yes

Exemple

    "user": {
        "email": "anonymous@example.fr",
        "first_name": "Ano",
        "last_name": "Nymous"
    }

State Change

Name	Type	Description	Required
change_reason	string	Reason for the state change	Yes
change_date	string	State change date	Yes
state	string	New state	Yes

Exemple

    "state_change": [
        {
            "change_reason": "",
            "change_date": "2025-04-04T10:07:24.276+02:00",
            "state": "acknowledged"
        },
        {
            "change_reason": "",
            "change_date": "2025-04-04T10:07:24.678+02:00",
            "state": "in_progress.elig"
        },
        {
            "change_reason": "",
            "change_date": "2025-04-04T10:07:24.791+02:00",
            "state": "in_progress.offer"
        },
        {
            "change_reason": "",
            "change_date": "2025-04-04T10:07:26.332+02:00",
            "state": "done.ready"
        }]

Offer Qualification Item Details

Nom	Type	Description	Obligatoire
id	string	Qualification Item's identifier	Yes
user	object	User who made the eligibility request	Yes
tarif_zone	string	Tarif zone	Yes
offer_families	array	Available offer families	Yes
zone_bpe	number	BPE Zone (ex: 1 corresponds to THD ZONE 1)	Yes
zone_bpea	number	BPEA Zone (ex: 3 corresponds to THD ZONE 3)	Yes
zone_dia	number	DIA Zone (ex: 2 correspond to THD ZONE 2)	Yes
estimated_delivery_date_BPE	string	Estimated delivery date BPE (ex: "T0 + 33 SEMAINES")	Yes
estimated_delivery_date_BPEA	string	Estimated delivery date BPEA (ex: "T0 + 33 SEMAINES")	Yes
estimated_delivery_date_DIA	string	Estimated delivery date DIA (ex: "T0 + 34 SEMAINES")	Yes
bandwidth_max	float	Maximum available bandwidth on the site	No
density	string	Zone density	Yes
place	object	Place details	Yes
address	object	Address details	No
guaranteed_until_date	string	Offer guaranteed up until this date	No
price	number	Product price	No
far	number	FAR price	No
fas	number	FAS price	No
state	string	Element's current state	Yes
state_change	array	State change history	Yes
product_offering_qualification_id	string	Parent eligibility request identifier	No
products_offering	array	List of eligible offers	Yes
resolve_pricing	boolean	Indicates whether pricing was resolved for this request	Yes

Exemple

"product_offering_qualification_item_detail": [
    {
        "id": "a4517ca6-1f13-42a2-9359-4ff3cc21785b",
        "user": {
            "email": "anonymous@example.fr",
            "first_name": "Ano",
            "last_name": "Nymous"
        },
        "tarif_zone": "",
        "offer_families": ["BPEA","BPE"],
        "zone_bpe": 2,
        "zone_bpea": 2,
        "zone_dia": 2,
        "estimated_delivery_date_BPE": "T0 + 33 SEMAINES",
        "estimated_delivery_date_BPEA": "T0 + 33 SEMAINES",
        "estimated_delivery_date_DIA": "T0 + 34 SEMAINES",
        "bandwidth_max": 1000,
        "place":{},
        "address": {},
        "guaranteed_until_date": null,
        "price": 145.0,
        "far": 0.0,
        "fas": 0.0,
        "state": "done.ready",
        "state_change": [...],
        "product_offering_qualification_id": null,

Place Details

Name	Type	Description	Required
location	object	Geographical coordinates	Yes
building_ref	string	Building reference	No
eligibility_id	string	Eligibility identifier	Yes

Exemple

"place": {
    "location": {
        "x": 1.0741197,
        "y": 49.4629709
    },
    "building_ref": "",
    "eligibility_id": "KHg6MS4wNzQxMTk3O3k6NDkuNDYyOTcwOTtiOk5vbmUp"
    }

Address Details

Name	Type	Description	Required
label	string	Address label	No
street_ext	string	Street extension	No
street_nr	string	Street number	No
city	object	City details	No
street	object	Street details	No

Exemple

"address": {
    "label": "4bis Rue Andrei Sakharov 76130 Mont-Saint-Aignan",
    "street_ext": "B",
    "street_nr": "4",
    "city": {},
    "street": {}
    }

City Details

Name	Type	Description	Required
city_id	string	City identifier	No
insee_code	string	INSEE code of the city	No
city_name	string	City name	No
post_code	string	Postal code of the city	No

Exemple

"city": {
    "city_id": "76451",
    "insee_code": "76451",
    "city_name": "MONT ST AIGNAN",
    "post_code": "76130"
    }

Street Details

Name	Type	Description	Required
street_id	string	Street identifier	No
street_name	string	Street name	No

Exemple

"street": {
    "street_id": "76451055R",
    "street_name": "Rue Andrei Sakharov"
    }

Offer Details

Name	Type	Description	Required
product_id	string	Offer identifier (product_offering)	Yes
name	string	Product name	Yes
description	string	Product description	Yes
bandwidth	string	Product bandwidth	Yes
bandwidth_guarantee	string	Guaranteed Bandwidth	Yes
bandwidth_max	string	Maximum Bandwidth	Yes
commitment	string	Product commitment	Yes
offer_technology	string	Offer technology	Yes
offer_family	string	Offer family	Yes
tarif_zone	string	Tarif zone	Yes
price	string	Product's price	No
far	string	FAR's price	No
fas	string	FAS's price	No
on_quotation	boolean	Indicates if the product is on quotation	Yes

Exemple

"products_offering": 
    [{
    "product_id": "2173",
    "name": "BPEA 20M/100M_24 mois",
    "description": "BPEA 20M/100M",
    "bandwidth": "20M",
    "bandwidth_guarantee": 20.0,
    "bandwidth_max": 20.0,
    "commitment": "24MOIS",
    "offer_technology": "FIBDE",
    "offer_family": "BPEA",
    "tarif_zone": ""
    "price": null,
    "far": null,
    "fas": null,
    "on_quotation": false
    }]

Offers list

Retrieving a list of offers.

GET /api/v1/catalog/product_offering/

Offer Details

Retrieving the details of an offer.

GET /api/v1/product_offering/{id}

Offers list with prices

POST /api/v1/catalog/product_offering/

Retrieves a list of product offers by identifier, enriched with their pricing (far/fas/price).

Request body: List of offer identifiers (list[string])

["BPE_100M_24MOIS", "BPEA_20M_24MOIS"]

Response:

Field	Type	Description
`id`	string	Offer identifier
`name`	string	Offer name
`description`	string	Offer description
`bandwidth`	string	Bandwidth
`bandwidth_max`	float	Maximum bandwidth
`bandwidth_guarantee`	float	Guaranteed bandwidth
`commitment`	string	Commitment duration
`tarif_zone`	string	Pricing zone
`far`	float	Network access fee
`fas`	float	Service access fee
`price`	float	Monthly recurring price
`offer_family`	string	Offer family (`BPE`, `BPEA`, `DIA`…)
`offer_technology`	string	Offer technology
`last_update`	datetime	Last update date (ISO 8601)

Request Field Parameters

Name	Type	Description	Required
id	string	Offer identifier (product_offering)	Yes
zone	integer	Tarif zone (from eligibility)	No

Response

Name	Type	Description	Required
id	string	Offer identifier	Yes
href	string	Link to the resource	Yes
name	string	Offer name	Yes
description	string	Offer description	Yes
bandwidthe	string	Product bandwidth	Yes
bandwidth_guarantee	string	Guaranteed bandwidth	Yes
bandwidth_max	string	Maximum bandwidth	Yes
commitment	string	Offer commitment	Yes
tarif_zone	string	Tarif zone	Yes
far	number	FAR value	Yes
fas	number	FAS value	Yes
price	number	Offer price	Yes
recurring	boolean	Indicates if the offer is recurring	Yes
offer_family	string	Offer family	Yes
offer_technology	string	Offer technology	Yes
available_options	array	Available options for the offer	Yes
last_update	string	Last update date	Yes

Exemple

{
    "id": "1765",
    "href": "",
    "name": "BPE 20M _Zone dense_24 mois ",
    "description": "description",
    "bandwidth": "20M",
    "bandwidth_guarantee": 20.0,
    "bandwidth_max": 20.0,
    "commitment": "24MOIS",
    "tarif_zone": "DENSE",
    "far": 240.0,
    "fas": 360.0,
    "price": 155.0,
    "recurring": true,
    "offer_family": "BPE",
    "offer_technology": "FIBDE",
    "available_options": [...],
    "last_update": "2024-06-22T08:28:06Z"
}

Available Options Details

Name	Type	Description	Required
name	string	Option name	Yes
type	string	Option type	Yes
values	array	Values associated with the option	Yes

Exemple

{
    "name": "SECURISATIONCOLLECTE",
    "type": "Option",
    "values": []
}

Option Values Details

Name	Type	Description	Required
option_id	string	Option identifier	Yes
label	string	Option label	Yes
price	number	Option price	Yes
recurring	boolean	Indicates if the option is recurring	Yes

Exemple

{
    "option_id": "241",
    "label": "SECURISATION COLLECTE Active - Passive",
    "price": 10.0,
    "recurring": true
}

Request for available site connection types

Retrieving available site connection types

GET /api/v1/referential/site_connection/

Response

Nom	Type	Description	Obligatoire
available_site_connection_types	array	List of available site connection types	Yes

Example

{
    "available_site_connection_types": [
        "Standard ou non-catégorisé",
        "Centre commercial",
        "Datacenter",
        "Zone d'activité ZA",
        "Aéroport",
        "Zone maritime",
        "Centre de santé ou hôpital",
        "Etablissement haute sécurité",
        "Etablissement patrimoine",
        "Prison",
        "Cimetière"
    ]
}

List of eligibility items

GET /api/v1/product_offering_qualification_item/

Lists or searches eligibility items (individual site-level results).

Available filters (query params):

Parameter	Type	Description
`state`	string	Filter by state
`density`	string	Filter by density (prefix, e.g. `T`)
`building_ref`	string	Filter by building reference (prefix)
`offer_technologies`	string	Filter by technology (comma-separated values)
`creation_date_gt`	datetime	Items created after this date (ISO 8601)
`creation_date_lt`	datetime	Items created before this date (ISO 8601)
`search`	string	Free-text search
`sort`	string	Sort field

Response: Paginated list of items (same fields as GET /product_offering_qualification_item/{id}/).

Eligibility item detail

GET /api/v1/product_offering_qualification_item/{id}/

Retrieves the detail of an individual eligibility item.

URL parameter:

Name	Type	Required	Description
`id`	UUID	✅	Item identifier

Response:

Field	Type	Description
`id`	UUID	Unique identifier
`creation_date`	datetime	Creation date (ISO 8601)
`density`	string	Zone density
`offer_families`	array	Requested offer families
`offer_families_eligibility`	array	Eligible offer families
`offer_technologies`	array	Eligible technologies
`zone_bpe`	string	BPE pricing zone
`zone_bpea`	string	BPEA pricing zone
`zone_dia`	string	DIA pricing zone
`estimated_delivery_date_BPE`	string	Estimated delivery date for BPE
`estimated_delivery_date_BPEA`	string	Estimated delivery date for BPEA
`estimated_delivery_date_DIA`	string	Estimated delivery date for DIA
`bandwidth_max`	float	Maximum available bandwidth
`place`	object	Location (coordinates, `building_ref`, `eligibility_id`)
`address`	object	Postal address
`state`	string	Item state
`product_offering_qualification_id`	UUID	Parent eligibility request identifier
`guaranteed_until_date`	datetime	Eligibility validity date