> For the complete documentation index, see [llms.txt](https://docs.powens.com/api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.powens.com/api-reference/products/data-aggregation/account-ownership-certificate.md).

# Account ownership certificate

> **This feature is not activated by default on your domain. Please contact us to request access.**

The account ownership certificate is a PDF document, generated on demand, that attests to two facts about a single connection:

* the end user gave express consent, on a specific date and time, for their account information to be accessed;
* according to the information retrieved, that end user is linked to a given list of payment accounts.

It is intended to be handed to a third party — a bank, a credit institution, a public administration or an auditor — as proof that the account data was legitimately obtained. The certificate is issued by Powens as the regulated entity, not by the account-servicing institution.

The document is built from the same data exposed by the [Account Ownerships](https://docs.powens.com/api-reference/products/data-aggregation/account-ownerships) endpoint of the Bank ID Check product, and is generated when the request is made. It is not stored: each call produces a fresh document bearing the current issue date.

> **Note:** not to be confused with [`GET /certificate/{type}`](https://docs.powens.com/api-reference/api-setup/configuration), which returns a technical certificate belonging to your domain.

### Prerequisites

The certificate names the account holder, and that information is recorded by the Bank ID Check product **at synchronization time**. A connection therefore needs to have been synchronized while Bank ID Check was enabled on your domain, by a connector that supports it. Otherwise no holder is on record and the request fails with `no account holder found`.

Enabling Bank ID Check afterwards is not enough on its own: the connection has to be synchronized again for the holder to be recorded.

Three configuration keys control the content of the document. They are set through the [Configuration](https://docs.powens.com/api-reference/api-setup/configuration) endpoint and apply to the whole domain.

| Configuration key                 | Type   | Default      | Description                                                                                                                           |
| --------------------------------- | ------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `connection_certificate.language` | String | `fr`         | Language of the certificate, which also determines the issuing entity and the legal template used. Accepted values are `es` and `fr`. |
| `root.client_name`                | String | Empty string | Your company name, as it should appear on the certificate as the requesting party. Required.                                          |
| `root.cif`                        | String | Empty string | Your company tax identification number. Required when the language is `es`, ignored otherwise.                                        |

Example configuration for a Spanish domain:

{% code overflow="wrap" %}

```
{  
    "connection_certificate.language": "es",  
    "root.client_name": "YOUR COMPANY SL",  
    "root.cif": "B00000000"
}
```

{% endcode %}

### API endpoints

### Get the certificate

**GET** `https://{domain}.biapi.pro/2.0/users/{user_id}/connections/{connection_id}/certificate`

Generate and download the account ownership certificate for a connection.

**Path Parameters**

| Name           | Type            | Required | Description                   |
| -------------- | --------------- | -------- | ----------------------------- |
| user\_id       | Integer or "me" | Yes      | ID of the related user.       |
| connection\_id | Integer         | Yes      | ID of the related connection. |

This endpoint takes no query parameter and no request body. The language cannot be selected per request: it is read from your domain configuration.

**Response**

**200 OK** — the response body is the PDF document itself, with `Content-Type: application/pdf`. No `Content-Disposition` header is returned, so you are free to name the file as you wish when storing or serving it.

**400 Bad Request** — the certificate could not be produced. See the Errors section below for the list of possible reasons.

**Example**

{% code overflow="wrap" %}

```
curl -sS "https://$DOMAIN.biapi.pro/2.0/users/me/connections/$CONNECTION_ID/certificate" \  -H "Authorization: Bearer $USER_TOKEN" \  -o certificate.pdf
```

{% endcode %}

The endpoint accepts a user token, a manager token, or a signed request.

### Certificate content

Most of the document is a fixed legal template. The following elements vary:

| Element                   | Source                                                                                                |
| ------------------------- | ----------------------------------------------------------------------------------------------------- |
| Requesting party's name   | The `root.client_name` configuration key.                                                             |
| Requesting party's tax ID | The `root.cif` configuration key. Spanish certificate only.                                           |
| End user's name           | The account holder, as returned in `parties[].identity.full_name` by the Account Ownerships endpoint. |
| Consent date and time     | The `created` date of the connection, to the second.                                                  |
| List of accounts          | The IBAN of every enabled checking account on the connection.                                         |
| Card numbers              | The PAN associated with those accounts. Spanish certificate only.                                     |
| Issue date                | The date on which the request is made.                                                                |

Only **checking accounts** that are enabled and carry an IBAN are listed. Savings, securities and other account types are not included.

#### Languages

The two versions are not translations of one another: the certifying entity differs, and so does the regulatory framing.

| Language | Issuing entity                                                                                                         | Accounts listed   |
| -------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `es`     | Unnax Regulatory Services, EDE, S.L. — electronic money institution registered with the Bank of Spain under code 6719. | IBAN and card PAN |
| `fr`     | Powens, SAS — registered with the Paris Trade and Companies Register under number 749 867 206.                         | IBAN only         |

### Webhook

The `CONNECTION_CERTIFICATE_AVAILABLE` event is emitted after a connection has been synchronized for the first time, when a certificate can be requested for it. You do not need to poll the endpoint.

Register it like any other event, as described in the [Webhooks](https://docs.powens.com/documentation/integration-guides/webhooks) guide.

{% code overflow="wrap" %}

```
{  "id_connection": 123,  "method": "GET",  "url": "/users/456/connections/123/certificate"}
```

{% endcode %}

> **Note:** the event indicates that the connection is eligible for a certificate, not that generation is guaranteed to succeed. A connection whose accounts turn out to be jointly held will emit the event and then return an error on download. Handle the error cases below.

### Errors

All failures are returned as `400` with the `badRequest` code and a `description` field explaining the cause.

| Description                                                     | Cause and resolution                                                                                                                            |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `unsupported language: …, languages are: es, fr`                | The `connection_certificate.language` key holds a value other than `es` or `fr`. Correct the key; there is no fallback.                         |
| `config: root.client_name is empty, provide your client's name` | The `root.client_name` key has no value. Set it to your company name.                                                                           |
| `config: root.cif is empty, provide your cif`                   | The language is `es` and the `root.cif` key has no value. Set your tax identification number.                                                   |
| `no checking account enabled on this connection`                | The connection has no enabled checking account. Either the connector returned none, or the end user did not select any during consent.          |
| `one or many accounts have multiple owners`                     | At least one account is jointly held. A certificate cannot name a single holder for a joint account, so none is issued.                         |
| `no account holder found`                                       | No holder could be determined for any account. Usually means Bank ID Check is not enabled on your domain, or the connector does not support it. |
| `no iban found`                                                 | A holder was identified, but none of the checking accounts carries an IBAN.                                                                     |

The three configuration errors are evaluated before any account data is read, so a misconfigured domain always reports the missing key rather than a data problem behind it.

### Notes and limitations

* **One language per domain.** The language is a domain-wide setting, so a single domain cannot issue both Spanish and French certificates.
* **Nothing is stored.** Two requests made on different days produce documents bearing different issue dates. If you need to keep a copy for audit purposes, store the PDF on your side when you download it.
* **No electronic signature.** The document is not digitally signed or time-stamped; it carries the issuing entity's letterhead and footer.
* **Joint accounts are not certified.** This is deliberate rather than a degraded mode, and it affects a meaningful share of real connections. Make sure your integration handles the error gracefully.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.powens.com/api-reference/products/data-aggregation/account-ownership-certificate.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.