Companies API¶

The Companies API manages SME (Small and Medium Enterprise) profiles within a tenant. Each company includes standard business details and an optional carbon profile for enhanced grant matching.

All company endpoints are tenant-scoped -- a user can only access companies belonging to their own tenant.

Endpoints¶

POST /companies¶

Create a new company profile for the current tenant.

Authentication: Required

RequestResponse (201)curl

{
  "name": "GreenTech Solutions GmbH",
  "description": "Renewable energy consulting firm",
  "country": "DE",
  "nace_codes": ["M71", "D35"],
  "employee_count": 45,
  "annual_revenue": 5200000,
  "founding_year": 2018,
  "region": "Bavaria",
  "city": "Munich",
  "website": "https://greentech-solutions.de",
  "contact_email": "info@greentech-solutions.de",
  "scope1_emissions": 120.5,
  "scope2_emissions": 85.3,
  "reduction_target_percent": 50,
  "reduction_target_year": 2030,
  "certifications": ["ISO_14001", "SBTi_COMMITTED"]
}

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant_id": "660e8400-e29b-41d4-a716-446655440000",
  "name": "GreenTech Solutions GmbH",
  "description": "Renewable energy consulting firm",
  "country": "DE",
  "nace_codes": ["M71", "D35"],
  "employee_count": 45,
  "annual_revenue": 5200000.0,
  "founding_year": 2018,
  "region": "Bavaria",
  "city": "Munich",
  "website": "https://greentech-solutions.de",
  "contact_email": "info@greentech-solutions.de",
  "is_active": true,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": null,
  "scope1_emissions": 120.5,
  "scope2_emissions": 85.3,
  "scope3_emissions": null,
  "scope1_sources": {},
  "scope2_sources": {},
  "scope3_categories": {},
  "reduction_target_percent": 50.0,
  "reduction_target_year": 2030,
  "net_zero_target_year": null,
  "certifications": ["ISO_14001", "SBTi_COMMITTED"],
  "carbon_profile_completed": false,
  "has_carbon_baseline": false,
  "total_emissions": 205.8,
  "carbon_readiness_score": 0.65
}

curl -X POST https://api.carbonconnect.io/api/v1/companies \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GreenTech Solutions GmbH",
    "country": "DE",
    "nace_codes": ["M71", "D35"],
    "employee_count": 45
  }'

Request Body (CompanyCreate):

Field	Type	Required	Description
`name`	string	Yes	Company name (1-500 chars)
`country`	string	Yes	ISO country code (2-3 chars)
`description`	string	No	Company description
`nace_codes`	string[]	No	NACE industry codes
`sic_codes`	string[]	No	SIC industry codes
`legal_form`	string	No	Legal entity form
`employee_count`	integer	No	Number of employees (>= 0)
`annual_revenue`	float	No	Annual revenue in EUR (>= 0)
`founding_year`	integer	No	Year founded (1800-2100)
`region`	string	No	Geographic region
`city`	string	No	City
`postal_code`	string	No	Postal code
`website`	string	No	Website URL
`contact_email`	string	No	Contact email
`registration_number`	string	No	Business registration number

Carbon Profile Fields:

Field	Type	Required	Description
`scope1_emissions`	float	No	Scope 1 direct emissions (tCO2e/year)
`scope2_emissions`	float	No	Scope 2 indirect emissions (tCO2e/year)
`scope3_emissions`	float	No	Scope 3 value chain emissions (tCO2e/year)
`scope1_sources`	object	No	Breakdown of Scope 1 sources
`scope2_sources`	object	No	Breakdown of Scope 2 sources
`scope3_categories`	object	No	GHG Protocol Scope 3 categories breakdown
`reduction_target_percent`	float	No	Emission reduction target (0-100%)
`reduction_target_year`	integer	No	Target year for reduction (2020-2100)
`net_zero_target_year`	integer	No	Net zero target year (2020-2100)
`certifications`	string[]	No	Sustainability certifications
`carbon_profile_completed`	boolean	No	Whether carbon profile is complete
`has_carbon_baseline`	boolean	No	Whether a carbon baseline exists

Carbon Readiness Score

The response includes a computed carbon_readiness_score (0.0 to 1.0) based on profile completeness:

30% -- Baseline emissions data (Scope 1 + 2)
15% -- Scope 3 data
20% -- Reduction targets
15% -- Net zero target
20% -- Certifications (5% per certification, max 20%)

Status Codes:

Code	Description
201	Company created
401	Not authenticated
422	Validation error

GET /companies¶

List all companies for the current tenant with pagination and optional filters.

Authentication: Required

Response (200)curl

{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tenant_id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "GreenTech Solutions GmbH",
      "country": "DE",
      "nace_codes": ["M71", "D35"],
      "is_active": true,
      "created_at": "2025-01-15T10:30:00Z",
      "total_emissions": 205.8,
      "carbon_readiness_score": 0.65
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "pages": 1
}

curl -X GET "https://api.carbonconnect.io/api/v1/companies?page=1&page_size=20&country=DE" \
  -H "Authorization: Bearer <token>"

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number (>= 1)
`page_size`	integer	20	Items per page (1-100)
`country`	string	--	Filter by ISO country code
`is_active`	boolean	--	Filter by active status

Status Codes:

Code	Description
200	Company list returned
401	Not authenticated

GET /companies/{company_id}¶

Retrieve a single company by its ID. Only returns companies within the current tenant.

Authentication: Required

curl

curl -X GET https://api.carbonconnect.io/api/v1/companies/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>"

Path Parameters:

Parameter	Type	Description
`company_id`	UUID	Company ID

Status Codes:

Code	Description
200	Company returned
401	Not authenticated
404	Company not found or wrong tenant

PATCH /companies/{company_id}¶

Update a company by ID. Only provided fields are updated (PATCH semantics).

Authentication: Required

RequestResponse (200)curl

{
  "employee_count": 52,
  "scope1_emissions": 110.2,
  "scope2_emissions": 78.6,
  "carbon_profile_completed": true,
  "has_carbon_baseline": true
}

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "GreenTech Solutions GmbH",
  "employee_count": 52,
  "scope1_emissions": 110.2,
  "scope2_emissions": 78.6,
  "carbon_profile_completed": true,
  "has_carbon_baseline": true,
  "total_emissions": 188.8,
  "carbon_readiness_score": 0.85
}

curl -X PATCH https://api.carbonconnect.io/api/v1/companies/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"employee_count": 52, "scope1_emissions": 110.2}'

Request Body (CompanyUpdate):

All fields from CompanyCreate are accepted, all optional. Additionally:

Field	Type	Description
`is_active`	boolean	Activate/deactivate company

Status Codes:

Code	Description
200	Company updated
401	Not authenticated
404	Company not found or wrong tenant
422	Validation error

DELETE /companies/{company_id}¶

Delete a company and all its associated matches and applications.

Authentication: Required

curl

curl -X DELETE https://api.carbonconnect.io/api/v1/companies/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>"

Cascading Delete

Deleting a company also removes all associated matches and applications. This action cannot be undone.

Path Parameters:

Parameter	Type	Description
`company_id`	UUID	Company ID

Status Codes:

Code	Description
204	Company deleted (no response body)
401	Not authenticated
404	Company not found or wrong tenant

Supported Certifications¶

The following certification values are recognized by the matching engine for carbon alignment scoring:

Value	Description
`ISO_14001`	ISO 14001 Environmental Management System
`SBTi_COMMITTED`	Science Based Targets initiative -- Committed
`SBTi_VALIDATED`	Science Based Targets initiative -- Validated
`CDP_DISCLOSURE`	CDP (Carbon Disclosure Project) participant
`B_CORP`	Certified B Corporation
`EMAS`	EU Eco-Management and Audit Scheme
`EU_ECOLABEL`	EU Ecolabel certification

Carbon Profile Source Breakdown Examples¶

Scope 1 Sources:

{
  "natural_gas_kwh": 50000,
  "diesel_liters": 2000,
  "petrol_liters": 500,
  "refrigerants_kg": 10
}

Scope 2 Sources:

{
  "electricity_kwh": 150000,
  "district_heating_kwh": 20000
}

Scope 3 Categories (GHG Protocol):

{
  "purchased_goods": 500,
  "business_travel": 100,
  "employee_commuting": 80,
  "upstream_transport": 120
}