Skip to content

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(<i>acknowledged</i>) B -->|Processing start| C(<i>in_progress.elig</i>) C -->D{Data\n Control\n OK ?} D -->|no| T[<i>terminated_with_error</i>] D -->|yes| F(<i>in_progress.offer</i>) F -->K{eligible ?} K -->|no| U[<i>done.unable_to_provide</i>] K -->|yes| G{Price calculation ?} G -->|no| H{On quote ?} H -->|yes| U H -->|no| R G -->|yes| P(<i>in_progress.price</i>) P -->R[<i>done.ready</i>]

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",
}

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
bandwidth_max	float	Max offer bandwidth	Yes
place	object	Place details	Yes
address	object	Adress details	No
guaranteed_until_date	string	Offer guaranteed up until this date	Yes
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	Product offering qualification identifier	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_type_bpe": "FTTO",
        "zone_type_bpea": "FTTO",
        "zone_bpe": 2,
        "zone_bpea": 2,
        "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}

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/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"
    ]
}

Eligibilites export

The eligibilites exporting process consists of three steps:

1. Starting the CSV export

POST /api/v1/product_offering_qualification_item/export/csv/

Starts the eligibilites export to the CSV format. This operation is limited to one request per user every 5 minutes.

Response

Field	Type	Description
task_id	string	Export task identifier

Example

{ 
    "task_id": "550e8400-e29b-41d4-a716-446655440000" 
}

2. Checking export state

GET /api/v1/product_offering_qualification_item/export/{task_id}/status/

Allows following the state of the export.

URL parameters

Parameter	Type	Description
task_id	string	Export task identifier

Response

Field	Type	Description
task_id	string	Export task identifier
success	boolean	Task's state (null if task is still ongoing)
started	datetime	Start date
stopped	datetime	End date

The success field in the response can have three different values:

Value	Description
`null`	The task is still on-going or hasn't started yet
`true`	The task succesfully concluded and the CSV file is ready
`false`	The task failed

Response

{
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "success": true,
    "started": "2025-07-08T10:30:00Z",
    "stopped": "2025-07-08T10:31:00Z"
}

3. Downloading the file

GET /api/v1/product_offering_qualification_item/export/{task_id}/download/

Downloads the CSV file after exporting is complete.

URL parameters

Parameter	Type	Description
task_id	string	Export task identifier

Response

The CSV file containing the exported data.

Response Headers

Header	Value
Content-Type	text/csv

Errors

HTTP code	Description
401	User lacks authentication
403	Request rejected
404	Task or file not found
429	Too many requests (rate limit reached)