# Hatvp — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search declarations of interests and assets from French public officials and lobbyists to track their financial disclosures and potential conflicts of interest. Filter by official name, function, geographic location, or browse statistics on transparency filings in France's public sector.

**Category:** Government & Public Data | **Website:** [hatvp.fr/](https://hatvp.fr/) | **Docs:** [parse.bot/marketplace/80aded73-925f-4e10-ac5f-b0de5f63d685/hatvp-fr-api](https://parse.bot/marketplace/80aded73-925f-4e10-ac5f-b0de5f63d685/hatvp-fr-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-hatvp-fr-api-80aded73/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_declaration_detail

Retrieve the full structured content of a specific declaration using its XML filename. The xml_filename is found in the open_data field from search results (only available for declarations with XML open data, typically DIA and DIAM document types). Returns the complete parsed XML as structured JSON.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `xml_filename` | string | Yes | XML filename from search results open_data field (e.g. 'lahmar-abdelkader-dia31320-depute-69.xml'). If no .xml extension provided, it is appended automatically. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-hatvp-fr-api-80aded73/get_declaration_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"xml_filename":"<string>"}'
```

### get_interests_declaration

Extract specifically the professional and mandate interests section of a declaration XML. Returns only interest-related fields such as consulting activities, management participations, and elected mandates. Best used with DIA (interests) declarations.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `xml_filename` | string | Yes | XML filename from search results open_data field (e.g. 'lahmar-abdelkader-dia31320-depute-69.xml'). If no .xml extension provided, it is appended automatically. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-hatvp-fr-api-80aded73/get_interests_declaration \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"xml_filename":"<string>"}'
```

### get_patrimony_declaration

Extract specifically the patrimony/assets sections (financial holdings, real estate, etc.) from a declaration XML. Returns only asset-related fields. Best used with DSP (patrimony) declarations.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `xml_filename` | string | Yes | XML filename from search results open_data field (e.g. '<lastname>-<firstname>-dsp<id>-<mandate>-<dept>.xml'). If no .xml extension provided, it is appended automatically. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-hatvp-fr-api-80aded73/get_patrimony_declaration \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"xml_filename":"<string>"}'
```

### get_statistics

Get aggregated statistics about published declarations on the HATVP portal, broken down by mandate type, department, and publication status. No parameters required.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-hatvp-fr-api-80aded73/get_statistics \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### list_lobbyists

Browse and search the registry of interest representatives (lobbyists). Returns organizations with their directors, collaborators, clients, affiliations, and activity sectors. Supports text search and pagination.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results to return. |
| `offset` | integer | No | Pagination offset (number of results to skip). |
| `query` | string | No | Search query to filter lobbyists by name, sector, directors, collaborators, or other fields. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-hatvp-fr-api-80aded73/list_lobbyists \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","offset":"<integer>","query":"<string>"}'
```

### search_by_function

Search for declarations filtered by public function type. Returns paginated results matching the specified mandate type.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `function_type` | string | Yes | Public function type to filter by. |
| `limit` | integer | No | Maximum number of results to return. |
| `offset` | integer | No | Pagination offset (number of results to skip). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-hatvp-fr-api-80aded73/search_by_function \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"function_type":"<string>","limit":"<integer>","offset":"<integer>"}'
```

### search_by_geographic_zone

Search for declarations by geographic zone using a French department code. Returns paginated results for officials in the specified department.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results to return. |
| `offset` | integer | No | Pagination offset (number of results to skip). |
| `zone` | string | Yes | French department code to filter by (e.g. '75' for Paris, '13' for Bouches-du-Rhône, '69' for Rhône, '971' for Guadeloupe). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-hatvp-fr-api-80aded73/search_by_geographic_zone \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","offset":"<integer>","zone":"<string>"}'
```

### search_declarations

Search for public official declarations by name, title, or department. Returns matching officials from the HATVP open data CSV with their metadata. At least one filter (query, name, title, department, type_mandat) is recommended to narrow results; omitting all filters returns all declarations. Pagination is manual via offset and limit.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `department` | string | No | Filter by department code (e.g. '75' for Paris, '13' for Bouches-du-Rhône). |
| `limit` | integer | No | Maximum number of results to return. |
| `name` | string | No | Filter by official's name (matches against first and last name). |
| `offset` | integer | No | Pagination offset (number of results to skip). |
| `query` | string | No | General search across name, first name, and title/position. |
| `title` | string | No | Filter by official's title or position (e.g. 'Député', 'Sénateur'). |
| `type_mandat` | string | No | Filter by mandate type. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-hatvp-fr-api-80aded73/search_declarations \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"department":"<string>","limit":"<integer>","name":"<string>","offset":"<integer>","query":"<string>","title":"<string>","type_mandat":"<string>"}'
```