> 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.