# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/hatvp/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/hatvp/get-declaration-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/hatvp/get-interests-declaration \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/hatvp/get-patrimony-declaration \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/hatvp/get-statistics \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/hatvp/list-lobbyists \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/hatvp/search-by-function \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/hatvp/search-by-geographic-zone \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/hatvp/search-declarations \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"department":"<string>","limit":"<integer>","name":"<string>","offset":"<integer>","query":"<string>","title":"<string>","type_mandat":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.