Batch Screenings

Create and manage batch screening jobs to process multiple companies simultaneously, enabling document collection and questionnaire screening at scale.

Overview

Batch screenings allow you to execute screening workflows across multiple companies in a single operation. Each batch job consists of:

• A batch job - The parent container tracking overall progress
• Companies - List of companies to process (1-100 companies per batch)
• Subtasks - Configurable workflow steps executed for each company

Supported Subtask Types

Batch screening jobs support two subtask types that can be combined:

1. Document Collection (document_collection)

Automatically discovers and collects relevant ESG documents, websites and files for each company. For example, this process automatically finds and retrieves the company's public annual reports, sustainability reports, and other ESG-related documents from their website and public sources.

Configuration:

• subtask_type: Must be "document_collection"
• redo_document_collection_task (boolean, default: false) - When set to true, archives all previously collected documents for the companies before running document collection again. This is useful when you want to start a fresh collection for the companies.

Example:

{
  "subtask_type": "document_collection",
  "redo_document_collection_task": false
}

2. Questionnaire Screening (questionnaire_screening)

Screens companies against a specified questionnaire, generating answers based on collected documents. For a more detailed explanation of what a questionnaire is check out our core concepts.

Configuration:

• subtask_type: Must be "questionnaire_screening"
• questionnaire_id: UUID of the questionnaire to use (required)
• question_ids: Optional list of specific question UUIDs to answer (if null, all questions are answered)
• min_file_threshold: Minimum number of files required to proceed with screening (default: 5, minimum: 1)

Example:

{
  "subtask_type": "questionnaire_screening",
  "questionnaire_id": "123e4567-e89b-12d3-a456-426614174000",
  "question_ids": null,
  "min_file_threshold": 5
}

Creating a Batch Screening Job

Endpoint: POST /workspaces/{workspace_id}/batch-screenings

Authentication: Requires platform authentication or Briink API key

Request Body:

{
  "companies": [
    {
      "company_name": "Tesla Inc.",
      "custom_id": "PORTFOLIO-001"
    },
    {
      "company_name": "Apple Inc.",
      "company_homepage": "apple.com",
      "company_location": "California",
      "custom_id": "PORTFOLIO-002"
    },
    {
      "company_id": "123e4567-e89b-12d3-a456-426614174001"
    }
  ],
  "subtasks": [
    {
      "subtask_type": "document_collection"
    },
    {
      "subtask_type": "questionnaire_screening",
      "questionnaire_id": "123e4567-e89b-12d3-a456-426614174000",
      "question_ids": null,
      "min_file_threshold": 5
    }
  ],
  "name": "Q1 2024 ESG Batch Screening",
  "description": "Quarterly ESG assessment for portfolio companies"
}

API Reference: For the complete and always up-to-date endpoint specification, see the Batch Screenings API Reference documentation.

Note: Each company must provide either company_id OR company_name. If using company_id, you cannot provide any of company_name,company_homepage, company_location or custom_id.

Note: Custom_id is used to simplify the mapping downstream of the Briink company_id to your custom_id. The custom_id by itself will have no usage in our system.

Note: The company_location field passes location information to improve company identification and enrichment:

• Can include any combination of city, state, address, or country
• Helps disambiguate companies with similar names
• Improves the accuracy of company profile enrichment

Response Schema (Status 202 - Accepted)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "STARTED",
  "total_tasks": 3,
  "completed_tasks": 0,
  "failed_tasks": 0,
  "workspace_id": "123e4567-e89b-12d3-a456-426614174001",
  "questionnaire_id": "123e4567-e89b-12d3-a456-426614174002",
  "name": "Q1 2024 ESG Batch Screening",
  "description": "Quarterly ESG assessment for portfolio companies",
  "creator_id": "123e4567-e89b-12d3-a456-426614174003",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "completed_at": null,
  "started_tasks": [
    {
      "id": "task-uuid-1",
      "company_id": "company-uuid-1",
      "custom_id": "PORTFOLIO-001"
    },
    {
      "id": "task-uuid-2",
      "company_id": "company-uuid-2",
      "custom_id": "PORTFOLIO-002"
    }
  ]
}

Batch Job Status Values

Note on Processing Time: Batch screening jobs are long-running processes, especially when processing a large number of companies or when document collection is enabled. Processing time varies based on:

• Number of companies in the batch
• Enabled subtasks (document collection, questionnaire screening)
• Availability of source documents

Recommended Polling Strategy:

• Poll the batch job status endpoint at reasonable intervals (e.g., every 30-60 seconds)
• Implement exponential backoff for polling to reduce API load
• Monitor individual company subtask statuses for detailed progress tracking

Company Deduplication

When submitting companies by name, Briink automatically performs deduplication to match against existing companies in your workspace. The system analyzes the provided company_name and attempts to map it to known entities in the database using case-insensitive name matching. Providing the optional company_homepage parameter significantly improves deduplication accuracy by adding a domain-based verification step—if a company with a matching name and homepage already exists, it will be reused rather than creating a duplicate. If no match is found with both name and homepage, the system attempts a fallback match using only the company name. If still no match is found, a new company profile is created and enriched with additional metadata. To bypass deduplication entirely and ensure you're working with a specific existing company, provide the company_id directly instead of using name-based lookup.

flowchart TD
    Start([Start: Company Input]) --> CheckID{company_id<br/>provided?}

    CheckID -->|Yes| GetByID[Retrieve company by ID]
    GetByID --> End([Return Company])

    CheckID -->|No| CheckName{company_name<br/>provided?}
    CheckName -->|No| Error[Raise ValueError:<br/>Either company_id or<br/>company_name required]

    CheckName -->|Yes| CheckHomepage{company_homepage<br/>provided?}

    CheckHomepage -->|Yes| SearchNameAndHomepage[Search by name + homepage<br/>]
    SearchNameAndHomepage --> FoundNameHomepage{Found?}

    FoundNameHomepage -->|Yes| End
    FoundNameHomepage -->|No| SearchNameOnly[Search by name only<br/>Returns first match found]

    CheckHomepage -->|No| SearchNameOnly
    SearchNameOnly --> FoundName{Found?}

    FoundName -->|Yes| End
    FoundName -->|No| CreateCompany[Create new company<br/>with provided details]

    CreateCompany --> End

    style CheckID fill:#e1f5ff
    style CheckName fill:#e1f5ff
    style CheckHomepage fill:#e1f5ff
    style FoundNameHomepage fill:#ffe1e1
    style FoundName fill:#ffe1e1
    style CreateCompany fill:#fff4e1
    style End fill:#e1ffe1
    style Error fill:#ffcccc

Updating Batch Screening Job Metadata

Endpoint: PUT /workspaces/{workspace_id}/batch-screenings/{batch_job_id}

Authentication: Requires platform authentication or Briink API key

Update the name and/or description of an existing batch screening job.

Request Body:

{
  "name": "Updated Q1 2024 ESG Batch Screening",
  "description": "Updated: Quarterly ESG assessment including climate risk"
}

Note: At least one field must be provided.

Response Schema

Returns the updated batch job object (same schema as creation response).

Updating Batch Screening Job Subtasks

Endpoint: POST /workspaces/{workspace_id}/batch-screenings/{batch_job_id}/subtasks

Authentication: Requires platform authentication or Briink API key

Update or replace the subtasks configuration for all tasks in a batch screening job. This allows you to modify the workflow steps (document collection, questionnaire screening) for the entire batch. This will retrigger all tasks, even if they previously have been completed, e.g. if a single task has already had the subtask questionnaire_screening it would be triggered again.

Request Body:

{
  "subtasks": [
    {
      "subtask_type": "document_collection"
    },
    {
      "subtask_type": "questionnaire_screening",
      "questionnaire_id": "123e4567-e89b-12d3-a456-426614174000",
      "question_ids": ["789e4567-e89b-12d3-a456-426614174000"],
      "min_file_threshold": 3
    }
  ]
}

Note: The subtasks array must contain at least one subtask configuration. Each subtask follows the same schema as during batch job creation.

Response Schema

Returns the updated batch job object (same schema as creation response).

Python SDK Example

from briink_sdk import BriinkClient
from uuid import UUID

client = BriinkClient(api_key="your-api-key")

# Create a batch screening job
batch_job = client.batch_screenings.create(
    workspace_id=UUID("your-workspace-id"),
    companies=[
        {
            "company_name": "Tesla Inc.",
            "company_homepage": "tesla.com"
        },
        {
            "company_id": UUID("existing-company-id")
        }
    ],
    subtasks=[
        {
            "subtask_type": "document_collection",
        },
        {
            "subtask_type": "questionnaire_screening",
            "questionnaire_id": UUID("your-questionnaire-id"),
            "min_file_threshold": 5
        }
    ],
    name="ESG Batch Assessment",
    description="Q1 2024 portfolio screening"
)

print(f"Batch job created: {batch_job.id}")
print(f"Status: {batch_job.status}")
print(f"Total tasks: {batch_job.total_tasks}")

# Update batch job metadata
updated_job = client.batch_screenings.update(
    workspace_id=UUID("your-workspace-id"),
    batch_job_id=batch_job.id,
    name="Updated ESG Assessment",
    description="Expanded scope to include climate risk"
)

# Update batch job subtasks
updated_job = client.batch_screenings.update_subtasks(
    workspace_id=UUID("your-workspace-id"),
    batch_job_id=batch_job.id,
    subtasks=[
        {
            "subtask_type": "questionnaire_screening",
            "questionnaire_id": UUID("your-questionnaire-id"),
            "question_ids": [UUID("specific-question-id")],
            "min_file_threshold": 3
        }
    ]
)

Best Practices

1. Company Identification: When you have an existing company_id, use it directly for faster processing and guaranteed accuracy. Use company_name + company_homepage when creating new companies to ensure proper deduplication.

2. Subtask Ordering: The subtask document_collectionwill always be performed before questionnaire_screening if both are provided to ensure documents are collected before screening begins. Both subtasks can be triggered by themselves as well.

3. Batch Size: Currently batches are limited to 100 companies at once, please reach out to us if you require a higher limit.

4. Question Filtering: Use question_ids when you only need answers to specific questions, reducing processing time and cost.

Additional Endpoints

For retrieving, listing, and managing batch screening jobs, see:

• GET /workspaces/{workspace_id}/batch-screenings - List all batch jobs
• GET /workspaces/{workspace_id}/batch-screenings/{batch_job_id} - Get specific batch job with tasks
• GET /workspaces/{workspace_id}/batch-screenings/{batch_job_id}/{batch_job_task_id} - Get specific task details
• DELETE /workspaces/{workspace_id}/batch-screenings/{batch_job_id} - Delete a batch job