Skip to content
Product Documentation
/
Portfolio Management and...
Last updated

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

Authenticate
Create Portfolio
Add/Import Records
Retrieve Portfolio or Records
Delete Records or Portfolio

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

Yes
Retrieve Portfolio or Records
Optimise Portfolio?
Run Matching Service
Run Deduplication Service
Run Enrichment Service
Retrieve Job Status/Results

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

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

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:

⚙️ 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

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

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.

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.

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.

  • 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

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:

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

Delete records from a portfolio:

POST /{apiVersion}/datastudio/portfolios/{portfolioId}/records/delete
Previous page