> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a data source (API)

> Register your database in Reporter, test the connection, and read the tables and fields that your templates can use.

Give Reporter a database to read, and confirm that Reporter reaches the tables that your templates use.

## Participants

***

* **Your institution.** Your system that calls the Reporter API.
* **Reporter.** Stores the data source, tests the connection and reads the structure of your database.
* **Your database.** The PostgreSQL or MongoDB database that holds the data for your reports.

## Before you start

***

* You have a bearer token that Access Manager issues for Reporter.
* Reporter can reach your database over the network.
* You have a database user for Reporter. Give this user read access only.

## Diagram

***

![Connect a data source](https://mintcdn.com/lerian-49cb71fc/KypD0TIKUCqZ014J/images/en/d2/id-reporter-connect-a-data-source.svg?fit=max\&auto=format\&n=KypD0TIKUCqZ014J\&q=85\&s=ee71a73cc608fec535f0c8e4b3d80e9b)

## Steps through the API

***

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Reporter | Lerian API | [`GET /v1/data-sources`](https://docs.lerian.studio/en/reference/products/reporter/list-data-sources) | List the data sources that Reporter knows. |
| 2 | Reporter | Your institution | Response | | Reporter returns a page of data sources. The page can also show read-only data sources that the platform provides for your Lerian product databases. |
| 3 | Your institution | Reporter | Lerian API | [`POST /v1/data-sources`](https://docs.lerian.studio/en/reference/products/reporter/create-data-source) | Send `configName`, `type`, `host`, `port`, `databaseName`, `username` and `password`. Add `sslMode` to choose the TLS mode. |
| 4 | Reporter | Your institution | Response | | Reporter returns the data source with its `id`. The response does not show the password. |
| 5 | Your institution | Reporter | Lerian API | [`POST /v1/data-sources/{dataSourceId}/test-connection`](https://docs.lerian.studio/en/reference/products/reporter/test-data-source-connection) | Ask Reporter to test the connection. |
| 6 | Reporter | Your database | Connection | | Reporter opens a short connection to your database and checks that the database answers. |
| 7 | Reporter | Your institution | Response | | Reporter returns `status` `connected` or `failed`, a message and `latencyMs`. |
| 8 | Your institution | Reporter | Lerian API | [`GET /v1/data-sources/{dataSourceId}/schema`](https://docs.lerian.studio/en/reference/products/reporter/get-data-source-schema) | Ask for the tables and fields of the data source. |
| 9 | Reporter | Your database | Connection | | Reporter reads the tables or collections and their fields. |
| 10 | Reporter | Your institution | Response | | Reporter returns each table with its fields and their types. Use these names in your templates and filters. |

## Rules

***

* The `configName` is the name that your templates and filters use. It has 1 to 100 letters, digits, underscores or hyphens. It is unique among your data sources.
* When you send neither `sslMode` nor `sslCaBase64`, Reporter uses `require`.
* When you change `host`, `port`, `username`, `databaseName`, `type`, `sslMode`, `options` or `sslCaBase64`, send the `password` again.
* Reporter refuses to change, delete or test a read-only platform data source. You can read its schema.

## How you know it finished

***

The connection test returns `connected`, and the schema lists the tables and fields that your templates read.

## What can go wrong

***

| Situation | What you see | What to do |
| - | - | - |
| The `configName` is in use or reserved | `409` or `400`, with a code and a message | Choose another name. |
| A field breaks a rule | `400` with `RPT-0017` and a message that names the field | Correct the field and send the request again. |
| The test fails | `200` with `status` `failed` and a message | Check the network path, the TLS settings and the credentials. Then test again. |

## Related

***

* [Generate and download a report](https://docs.lerian.studio/en/diagrams/lerian-products/reporter-generate-a-report.md)
* [Connect Reporter to Midaz](https://docs.lerian.studio/en/products/reporter/connecting-reporter-to-midaz.md)
* [Reporter developer quick start](https://docs.lerian.studio/en/reference/products/reporter/reporter-developer-quick-start.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.