{
  "openapi": "3.1.0",
  "info": {
    "title": "Rättkoll API",
    "version": "1.0.0",
    "description": "Screen which Swedish benefits, grants, deductions and business support may apply to a profile. Results are guidance with official sources, never decisions. Profiles are validated against an allowlist of fields and never stored. Rättkoll is an independent service, not a government agency.",
    "contact": {
      "name": "Rättkoll (Accruvia AB)",
      "email": "rattkoll@accruvia.se",
      "url": "https://rattkoll.se/utvecklare/"
    }
  },
  "servers": [
    {
      "url": "https://rattkoll.se/api/v1"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/screening/match": {
      "post": {
        "summary": "Run the check for a profile (one check)",
        "operationId": "match",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MatchRequest"
              },
              "example": {
                "audience": "business",
                "locale": "sv",
                "profile": {
                  "company_sweden": true,
                  "hiring": true
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Screening result",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Rattkoll-Checks-Used": {
                "schema": {
                  "type": "integer"
                },
                "description": "Live keys: checks this calendar month (Europe/Stockholm)"
              },
              "X-Rattkoll-Checks-Included": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MatchResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid profile (unknown field, wrong type, wrong audience, identifiers)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message",
                        "request_id"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "request_id": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidKey"
          },
          "402": {
            "$ref": "#/components/responses/Inactive"
          },
          "429": {
            "$ref": "#/components/responses/Limited"
          }
        }
      }
    },
    "/screening/fields": {
      "get": {
        "summary": "Profile fields (free)",
        "operationId": "fields",
        "parameters": [
          {
            "name": "audience",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "individual",
                "business"
              ]
            }
          },
          {
            "name": "locale",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "sv",
                "en"
              ],
              "default": "sv"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Fields",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "catalog_version": {
                      "type": "string"
                    },
                    "locale": {
                      "type": "string"
                    },
                    "fields": {
                      "type": "object",
                      "additionalProperties": {
                        "$ref": "#/components/schemas/Field"
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidKey"
          },
          "402": {
            "$ref": "#/components/responses/Inactive"
          },
          "429": {
            "$ref": "#/components/responses/Limited"
          }
        }
      }
    },
    "/screening/supports": {
      "get": {
        "summary": "The support catalogue (free)",
        "operationId": "supports",
        "parameters": [
          {
            "name": "audience",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "individual",
                "business"
              ]
            }
          },
          {
            "name": "locale",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "sv",
                "en"
              ],
              "default": "sv"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Catalogue",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "catalog_version": {
                      "type": "string"
                    },
                    "locale": {
                      "type": "string"
                    },
                    "supports": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Support"
                      }
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidKey"
          },
          "402": {
            "$ref": "#/components/responses/Inactive"
          },
          "429": {
            "$ref": "#/components/responses/Limited"
          }
        }
      }
    },
    "/screening/usage": {
      "get": {
        "summary": "Your company's usage (free)",
        "operationId": "usage",
        "responses": {
          "200": {
            "description": "Usage",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Usage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidKey"
          },
          "402": {
            "$ref": "#/components/responses/Inactive"
          },
          "429": {
            "$ref": "#/components/responses/Limited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "rk_test_… (free, 100 checks per company and day, results marked test: true) or rk_live_… (needs an active Rättkoll API plan). Create keys under API in the business portal. Server to server only."
      }
    },
    "responses": {
      "InvalidKey": {
        "description": "invalid_key: missing, unknown or revoked key",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error"
              ],
              "properties": {
                "error": {
                  "type": "object",
                  "required": [
                    "code",
                    "message",
                    "request_id"
                  ],
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "Inactive": {
        "description": "subscription_inactive: live key without an active plan",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error"
              ],
              "properties": {
                "error": {
                  "type": "object",
                  "required": [
                    "code",
                    "message",
                    "request_id"
                  ],
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "Limited": {
        "description": "rate_limited (20/s, 600/min per key, see Retry-After) or test_limit (100 test checks per company and day)",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error"
              ],
              "properties": {
                "error": {
                  "type": "object",
                  "required": [
                    "code",
                    "message",
                    "request_id"
                  ],
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "MatchRequest": {
        "type": "object",
        "required": [
          "audience",
          "profile"
        ],
        "additionalProperties": false,
        "properties": {
          "audience": {
            "type": "string",
            "enum": [
              "individual",
              "business"
            ]
          },
          "locale": {
            "type": "string",
            "enum": [
              "sv",
              "en"
            ],
            "default": "sv"
          },
          "profile": {
            "type": "object",
            "description": "Only fields from /screening/fields for the same audience. Leave out what is unknown."
          },
          "include_excluded": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "MatchResult": {
        "type": "object",
        "properties": {
          "engine": {
            "type": "string"
          },
          "catalog_version": {
            "type": "string"
          },
          "catalog_sha256": {
            "type": "string"
          },
          "evaluated_at": {
            "type": "string",
            "format": "date"
          },
          "audience": {
            "type": "string"
          },
          "locale": {
            "type": "string"
          },
          "matches": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Match"
            }
          },
          "excluded": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Match"
            }
          },
          "excluded_count": {
            "type": "integer"
          },
          "followups": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Questions that would settle more support"
          },
          "profile": {
            "type": "object"
          },
          "disclaimer": {
            "type": "string"
          },
          "test": {
            "type": "boolean"
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "Match": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "possible",
              "explore",
              "needs_information",
              "not_matched",
              "inactive",
              "review_required"
            ]
          },
          "explanation": {
            "type": "string"
          },
          "next_steps": {},
          "limitations": {},
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Source"
            }
          },
          "missing_fields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "reviewed_at": {
            "type": "string",
            "format": "date"
          },
          "review_due": {
            "type": "string",
            "format": "date"
          },
          "rule_version": {
            "type": "string"
          },
          "estimated_amount": {
            "type": [
              "null"
            ]
          }
        }
      },
      "Source": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Field": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "boolean",
              "integer",
              "number",
              "enum"
            ]
          },
          "question": {
            "type": "string"
          },
          "audience": {
            "type": "string"
          },
          "options": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "min": {
            "type": "number"
          },
          "max": {
            "type": "number"
          }
        }
      },
      "Support": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "audience": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Source"
            }
          },
          "reviewed_at": {
            "type": "string",
            "format": "date"
          },
          "review_due": {
            "type": "string",
            "format": "date"
          },
          "version": {
            "type": "string"
          },
          "effective_from": {
            "type": "string",
            "format": "date"
          },
          "effective_to": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "availability": {
            "type": "string"
          },
          "funding_kind": {
            "type": "string"
          },
          "screening_level": {
            "type": "string"
          }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "company": {
            "type": "string"
          },
          "key": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "test",
                  "live"
                ]
              }
            }
          },
          "plan": {
            "type": "object",
            "properties": {
              "product": {
                "type": "string"
              },
              "status": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "included_checks": {
                "type": "integer"
              }
            }
          },
          "month": {
            "type": "object",
            "properties": {
              "month": {
                "type": "string"
              },
              "checks": {
                "type": "integer"
              },
              "included": {
                "type": "integer"
              },
              "over": {
                "type": "boolean"
              },
              "pct": {
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          },
          "test_today": {
            "type": "object",
            "properties": {
              "calls": {
                "type": "integer"
              },
              "limit": {
                "type": "integer"
              }
            }
          },
          "request_id": {
            "type": "string"
          }
        }
      }
    }
  }
}