# Kununu Reviews

Get reviews for a specific company on Kununu. Existing per-company callers may set recovery=partial on fenced page 2; the provider-side fanout needs no separate search trigger or caller-side filter orchestration. Ordinary fenced pagination remains HTTP 503 without data. An incomplete recovery returns HTTP 503 with unique reviews in data, meta.partial=true, meta.complete=false, recovered_count and upstream_total; it is not a paginated success. Only a verified complete set with no failed angles returns HTTP 200. Recovery is non-billable and sends at most 96 additional upstream requests, in waves of at most 4 concurrent lookups (or lower configured limits), bounded by the overall request deadline.

- **Documentation:** [https://staging.scrappa.co/docs/kununu-api/kununu_reviews](https://staging.scrappa.co/docs/kununu-api/kununu_reviews)
- **API group:** Kununu API
- **Endpoint:** `GET https://scrappa.co/api/kununu/reviews`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | string | Yes | Country code (de, at, ch) |
| `company_slug` | string | Yes | Company slug (e.g., "bmw-group", "sap-se") |
| `company_id` | string | No | Company UUID. Optional; resolved from company_slug when omitted. |
| `page` | integer | No | Page number for pagination (default: 1) |
| `review_type` | string | No | Type of reviews: "employees" or "candidates" (default: "employees") |
| `sort` | string | No | Sort order. "newest" and "oldest" order the full result set by last review activity, which is the creation date unless the review was edited later. "best" and "worst" order each returned page by score while preserving stable, non-overlapping pagination. Omit to use the default kununu relevance ordering. For incremental syncing, compare the updatedAt field rather than createdAt. |
| `score_filters[]` | array | No | Filter by ratings: "excellent", "good", "satisfactory", "subpar" |
| `recommended_filters[]` | array | No | Filter by recommendation: "yes" or "no" |
| `jobstatus_filters[]` | array | No | Filter by employment status: "current" or "former" |
| `position_filters[]` | array | No | Filter by position: "employee", "manager", "apprentice", "student", "intern", "freelancer", "contractor" |
| `department_filters[]` | array | No | Filter by department: "administration", "sales", "legal", "operations", "recruiting", "communication", "product", "logistic", "it", "management", "research", "controlling", "design", "procurement" |
| `response_filters[]` | array | No | Filter by employer response: "yes" or "no" |
| `result_filters[]` | array | No | Filter candidate reviews by application outcome: "hired", "rejected", "offerDeclined", "deferred" |
| `date_filters[]` | array | No | Filter by review age: "24months", "12months", "6months", "30days" |
| `fetch_factor_scores` | boolean | No | Include detailed factor ratings in response (adds ratings array with items like {"id": "workLifeBalance", "score": 4.5, "roundedScore": 5.0, "text": "Work-life balance"}) |
| `recovery` | string | No | Set to "partial" on fenced page 2 to start server-selected documented filter fanout (up to 96 additional requests, at most 4 simultaneous). A partial HTTP 503 contains unique reviews but never implies full pagination. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/kununu/reviews?country=de&company_slug=bmwgroup"
```

## Example response

```json
{
    "success": true,
    "data": [
        {
            "uuid": "review-uuid",
            "type": "employer",
            "typeVersion": "v1_dach",
            "source": null,
            "title": "Great team",
            "score": 4.2,
            "roundedScore": 4,
            "createdAt": "2026-01-01T00:00:00.000Z",
            "updatedAt": "2026-01-02T00:00:00.000Z",
            "displayStatus": "published",
            "multipleReview": false,
            "apprenticeshipJob": false,
            "position": "employee",
            "department": "research",
            "texts": [
                {
                    "id": "positive",
                    "text": "Great team environment"
                },
                {
                    "id": "suggestion",
                    "text": "Better coffee"
                }
            ],
            "responses": [
                {
                    "id": "response-uuid",
                    "uuid": "response-uuid",
                    "text": "Thank you for your feedback",
                    "response": "Thank you for your feedback",
                    "createdAt": "2026-01-03T00:00:00.000Z",
                    "updatedAt": "2026-01-04T00:00:00.000Z",
                    "reviewEditedAfterResponse": false,
                    "reactions": {
                        "helpful": {
                            "count": 2
                        }
                    },
                    "user": {
                        "name": "HR Team"
                    },
                    "author": null
                }
            ],
            "reactions": {
                "agree": {
                    "count": 5
                },
                "helpful": {
                    "count": 3
                }
            },
            "company": {
                "uuid": "company-uuid",
                "name": "Example Company",
                "slug": "example-company",
                "location": {
                    "city": "Munich",
                    "state": "Bavaria",
                    "countryCode": "de"
                }
            }
        }
    ],
    "meta": {
        "pagination": {
            "currentPage": 1,
            "totalPages": 1,
            "resultsStart": 0,
            "resultsEnd": 1,
            "totalResults": 1
        },
        "filters": {
            "score": {
                "excellent": 123,
                "good": 456,
                "satisfactory": 78,
                "subpar": 12
            },
            "recommended": {
                "yes": 789,
                "no": 101
            },
            "jobstatus": {
                "current": 234,
                "former": 567
            },
            "position": {
                "employee": 890,
                "manager": 123
            },
            "department": {
                "it": 456,
                "sales": 789
            },
            "response": {
                "yes": 321,
                "no": 654
            }
        },
        "totalReviewsApprenticeship": 42,
        "duration_ms": 123.45,
        "cached": false
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 401 | Unauthorized | API key is missing or invalid |
| 422 | Validation Error | One or more parameters failed validation |
| 404 | Not Found | Company not found on Kununu |
| 500 | Internal Server Error | Service temporarily unavailable or failed to fetch reviews from Kununu API |
| 503 | Upstream Review Access Restricted | Kununu review fencing prevented access to the requested page. Authorized upstream access is required before a complete scan can be verified. No review data or zero count is returned. |

## More Scrappa resources

- [API documentation](https://staging.scrappa.co/docs)
- [Full LLM-readable API reference](https://staging.scrappa.co/llms-full.txt)
- [OpenAPI specification](https://staging.scrappa.co/docs/api.json)
- [Pricing](https://staging.scrappa.co/pricing)