{"schemaVersion":"1.0","sourceCommit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca","sourceVisibility":"private","article":{"id":"api-mansoq-kutumba-beneficiaryviewset-534b36a8","title":"Beneficiary API reference · mansoq-kutumba","summary":"Static source contract for Beneficiary: 1 declared or inherited operation mappings, schema/field evidence and authorization/refusal references. Deployment and behavioral review remain explicit.","module":"IT & integrations","roles":["IT administrator","Developer","Integration engineer"],"facilities":["All configured facility types"],"kind":"reference","minutes":3,"prerequisites":["Use the API contract from the installed deployment and an authorized synthetic test environment.","Confirm facility/organization scope, action permissions and optional app enablement.","This reference is static source evidence; complete payload, authorization, failure and end-to-end review remains recorded as pending."],"steps":[],"sections":[{"title":"Declared route and availability","body":"This resource is declared in **mansoq-kutumba** at `/api/{installed_plugin_prefix}/beneficiary/`. plugin/local mount; actual prefix and enablement require deployment verification A registered path and an indexed handler do not prove deployment availability, user permission or production readiness."},{"title":"Operation map","body":"| Method | Path | Action | Evidence |\n| --- | --- | --- | --- |\n| POST | `/api/{installed_plugin_prefix}/beneficiary/lookup/` | lookup | @action declaration |"},{"title":"lookup · POST","body":"Lookup beneficiary data by Ration Card number.\n\nRequest body:\n{\n    \"rc_number\": \"110399147990\"\n}\n\nReturns family member data from Karnataka Kutumba system.\n\n**POST /api/{installed_plugin_prefix}/beneficiary/lookup/** — action `lookup`. static contract extracted; runtime/permission/payload behavior review pending.\n\nPath and deployment-context parameters:\n\n| Location | Parameter | Type | Required |\n| --- | --- | --- | --- |\n| deployment mount | installed_plugin_prefix | deployment-selected mount prefix | true |\n\n**Observed authorization checks:** `can_create_patient`. Helper/queryset evidence is included; this is not proof of complete security review.\n\n**Class policy declarations:** permission_classes: IsAuthenticated.\n\n**Explicit response statuses in observed code:** status.HTTP_200_OK, status.HTTP_503_SERVICE_UNAVAILABLE, status.HTTP_400_BAD_REQUEST. Other branches/framework exception handling may differ.\n\n**Declared refusal/error evidence:** PermissionDenied: You do not have permission to look up Kutumba beneficiaries."},{"title":"Integration review checklist","body":"Confirm the installed route and full schema; review authentication, organization/facility scoping, all accepted fields, value-state and date/time semantics, idempotency, pagination, response/exception branches and the allowed correction/reversal workflow. Test positive and negative cases with synthetic data. This source reference does not establish external certification or replace an illustrated user procedure."}],"troubleshooting":[{"problem":"A declared route is unavailable or a request is rejected","solution":"Compare the installed revision, actual API schema, optional plugin mount, HTTP-method restrictions and recorded validation/permission evidence. Do not bypass a refusal or send a production transaction to test documentation."}],"sources":[{"path":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/urls.py","line":14,"commit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca"},{"path":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/api/viewsets.py","line":19,"commit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca"},{"path":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/api/viewsets.py","line":24,"commit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca"}],"related":["it-api-contract","it-api-auth","security-rcm-roles"],"verification":"Static API contract — behavior review pending","version":"f6e9f05f76d4","apiReferenceIds":["backend-resource-d5438fd9534b36a8","backend-resource-d5438fd9534b36a8:POST:lookup"]},"backend":{"resources":[{"id":"backend-resource-d5438fd9534b36a8","localPrefix":"beneficiary","viewset":"BeneficiaryViewSet","classId":"repositories/teleicu/mansoq-kutumba:mansoq_kutumba.api.viewsets.BeneficiaryViewSet","basename":"kutumba-beneficiary","source":{"path":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/urls.py","line":14,"commit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca"},"conditions":[],"repository":"repositories/teleicu/mansoq-kutumba","classSource":{"path":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/api/viewsets.py","line":19,"commit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca"},"description":"","path":"/api/{installed_plugin_prefix}/beneficiary/","mountStatus":"plugin/local mount; actual prefix and enablement require deployment verification","operationIds":["backend-resource-d5438fd9534b36a8:POST:lookup"],"unresolvedViewset":false,"reviewStatus":"registered resource enumerated; behavioral review pending"}],"operations":[{"id":"backend-resource-d5438fd9534b36a8:POST:lookup","resourceId":"backend-resource-d5438fd9534b36a8","repository":"repositories/teleicu/mansoq-kutumba","boundary":"optional-plugin/local-service","method":"POST","path":"/api/{installed_plugin_prefix}/beneficiary/lookup/","declaredPattern":"/api/{installed_plugin_prefix}/beneficiary/lookup/","action":"lookup","viewset":"BeneficiaryViewSet","classId":"repositories/teleicu/mansoq-kutumba:mansoq_kutumba.api.viewsets.BeneficiaryViewSet","detail":false,"allowedByDeclaredHttpMethods":true,"mountStatus":"plugin/local mount; actual prefix and enablement require deployment verification","routeEvidence":{"path":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/urls.py","line":14,"commit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca"},"handlerSource":{"path":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/api/viewsets.py","line":24,"commit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca"},"registrationConditions":[],"evidenceKind":"@action declaration","methodEvidenceIds":["repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/api/viewsets.py:24:lookup"],"schemaIds":{},"classPermissionEvidence":[{"kind":"permission_classes","declaration":["IsAuthenticated"],"source":{"path":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/api/viewsets.py","line":20,"commit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca"}}],"filterEvidence":[],"reviewStatus":"static contract extracted; runtime/permission/payload behavior review pending","pathParameters":[{"name":"installed_plugin_prefix","in":"deployment mount","type":"deployment-selected mount prefix","required":true,"source":{"path":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/urls.py","line":14,"commit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca"}}]}],"methodEvidence":[{"id":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/api/viewsets.py:24:lookup","name":"lookup","owner":"repositories/teleicu/mansoq-kutumba:mansoq_kutumba.api.viewsets.BeneficiaryViewSet","summary":"Lookup beneficiary data by Ration Card number.\n\nRequest body:\n{\n    \"rc_number\": \"110399147990\"\n}\n\nReturns family member data from Karnataka Kutumba system.","source":{"path":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/api/viewsets.py","line":24,"commit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca"},"signatureParameters":[],"parametersRead":[],"permissionChecks":[{"permission":"can_create_patient","source":{"path":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/api/viewsets.py","line":35,"commit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca"}}],"declaredErrors":[{"exception":"PermissionDenied","message":"You do not have permission to look up Kutumba beneficiaries","dynamicMessage":false,"source":{"path":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/api/viewsets.py","line":36,"commit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca"}}],"explicitResponseStatuses":[{"value":null,"symbol":"status.HTTP_200_OK","source":{"path":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/api/viewsets.py","line":80,"commit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca"}},{"value":null,"symbol":"status.HTTP_503_SERVICE_UNAVAILABLE","source":{"path":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/api/viewsets.py","line":79,"commit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca"}},{"value":null,"symbol":"status.HTTP_400_BAD_REQUEST","source":{"path":"repositories/teleicu/mansoq-kutumba/src/mansoq_kutumba/api/viewsets.py","line":41,"commit":"f6e9f05f76d443b26ebd2369f67d3c3bd52257ca"}}],"conditions":[],"schemaIds":[],"schemaUsages":[],"unconditionalRaise":false,"reviewStatus":"static declaration extracted; behavioral/security review pending"}],"schemas":[],"frameworkSettings":[]},"frontend":{"operations":[],"schemas":[]},"services":{"operations":[]},"boundaries":[]}