# DataStudio API Endpoints

The DataStudio API provides a comprehensive set of endpoints to help you manage and optimise your business portfolios.

The Data Studio Suite provides a set of endpoints to:

- Authenticate
- Create, retrieve, update, and delete portfolios
- Add, import, retrieve, and delete records within a portfolio
- Run advanced services such as matching, deduplication, and enrichment
- Retrieve the status and results of asynchronous operations


Below is a flow diagram guide on how to use these endpoints.

## Flow Diagram: Portfolio Management


```mermaid
%%{ init: { "theme": "default" } }%%
flowchart TD
  A[Authenticate]
  B[Create Portfolio]
  C[Add/Import Records]
  D[Retrieve Portfolio or Records]
  J[Delete Records or Portfolio]

  A --> B
  B --> C
  C --> D
  D --> J
```

> *Diagram summary (accessibility): Authenticate, create a portfolio, add or import records, retrieve portfolio or record data, and then delete records or the portfolio when required.*


## Flow Diagram: Portfolio Optimisation


```mermaid
%%{ init: { "theme": "default" } }%%
flowchart TD
  D[Retrieve Portfolio or Records]
  E{Optimise Portfolio?}
  F[Run Matching Service]
  G[Run Deduplication Service]
  H[Run Enrichment Service]
  I[Retrieve Job Status/Results]

  D --> E
  E -- Yes --> F
  F --> G
  F --> H
  G --> I
  H --> I
  I --> D
```

> *Diagram summary (accessibility): From portfolio data retrieval, decide whether to optimize; if yes, run matching, then deduplication and/or enrichment, retrieve job status/results, and loop back to portfolio retrieval.*


## 1. Authenticate

Before using any of the endpoints, you must authenticate. This ensures you have the necessary permissions to access the data.

### Example Request


```http
POST /v1/authenticate
```

**NOTE**: All subsequent requests require a bearer token in the Authorization header.

## 2. Portfolio Management

After authentication, you can:

- Create a new portfolio
- Add or import records
- Retrieve or update portfolio details


Portfolios are the core structure for organizing your business records.

### Example Requests


```http
Create a Portfolio
POST /v1/datastudio/portfolios

Return Portfolio by Id 
GET /v1/datastudio/portfolios/{portfolioId}

Create Records in a Portfolio
POST /v1/datastudio/portfolios/{portfolioId}/records
```

**API Example Requests:**

- [Create a portfolio](https://doc.creditsafe.com/datastudio/datastudio/portfolio/createportfolio)
- [Retrieve portfolio by portfolio Id](https://doc.creditsafe.com/datastudio/datastudio/portfolio/getportfolio)
- [Create records](https://doc.creditsafe.com/datastudio/datastudio/portfolio-records/createrecords)


## ⚙️ Additional Notes on Record Management

### Record Addition Limits

When adding records directly to a portfolio:

- You can add **up to 300 records per request**.


[Create Records Endpoint Documentation](https://doc.creditsafe.com/datastudio/datastudio/portfolio-records/createrecords)

### Importing Records via CSV

To bulk upload records:

- Maximum file size: **50 MB**
- Supported formats: `csv`, `gzip`, `tar`, `gztar`
- The first row must contain **headers** that match the expected field names.


You can find the full list of supported CSV headers and formatting guidance in the official documentation:

[Import Records Endpoint Documentation](https://doc.creditsafe.com/datastudio/datastudio/portfolio-records-import/importrecords)

## 3. Portfolio Optimisation

Once your portfolio is populated, you can use optimization endpoints to improve data quality and gain insights:

- **Matching:** Link your records to Creditsafe’s unique company identifiers.
- **Deduplication:** Identify and resolve duplicate records.
- **Enrichment:** Enhance your records with additional company data.


Each optimization service is asynchronous; you start a job and then poll for its status and results.

## 4. Matching, Deduplication, and Enrichment

If this is the first time your portfolio and its records are being processed, it is recommended to follow the steps in this order: **Matching → Deduplication → Enrichment**.

### Matching

Matching should be performed first. For best results, it is advised to match against the Creditsafe Safe Number.

- **Start the matching process:**
Initiate matching using the relevant endpoint for your portfolio.
- **Check matching status:**
Use the `executionId` provided in the initial response to check the status of the matching process.


For more details, refer to the [matching documentation](https://doc.creditsafe.com/datastudio/datastudio/matching).

### Deduplication

After matching, you can run deduplication to sanitise your data before enrichment. In the request body, you can specify how you want to identify duplicates.

- **Start the deduplication process:**
`POST /{apiVersion}/datastudio/portfolios/{portfolioId}/duplicates/identify`
This will begin the process of finding duplicates in your portfolio.
- **Check deduplication status:**
Use the `executionId` returned from the `POST` request to check the status:
`GET /{apiVersion}/datastudio/portfolios/{portfolioId}/duplicates/{executionId}`
This endpoint will provide a link to a file containing all identified duplicates.
- **Remove duplicates:**
Once duplicates are identified, run the removal process by passing the portfolio ID to the appropriate endpoint.


For more information on deduplication, see the [deduplication documentation](https://doc.creditsafe.com/datastudio/datastudio/deduplication).

### Enrichment

Once deduplication is complete, you can use the enrichment process to enhance your records with additional data.

- **Start enrichment:**
Pass the `portfolioId` in the path, set the enrichment type to `GLOBAL_DATA_ENRICHMENT`, and provide a request body specifying the fields to enrich.
Details on the request body and available fields can be found in the [enrichment documentation](https://doc.creditsafe.com/datastudio/datastudio/enrichment/startenrichment).
- **Check enrichment status and retrieve results:**
After starting enrichment, you can check the status and retrieve the resulting file via a link provided in the response.


## 5. Retrieve Job Status and Results

For asynchronous operations (matching, deduplication, enrichment), use the provided `executionId` to check job status and retrieve results.

### Example Request


```http
GET /v1/datastudio/portfolios/{portfolioId}/enrich/{executionId}
```

## 6. Delete Records or Portfolio

You can remove individual records or delete entire portfolios as needed to keep your data organized and up-to-date.

**Delete a portfolio:**


```http
DELETE /{apiVersion}/datastudio/portfolios/{portfolioId}
```

**Delete records from a portfolio:**


```http
POST /{apiVersion}/datastudio/portfolios/{portfolioId}/records/delete
```