# Beneficiaries Beneficiary management ## Get all beneficiaries > Retrieve a list of all beneficiaries for the authenticated tenant. Returns only active beneficiaries (not soft-deleted). Each beneficiary represents a recipient who can receive money transfers. ```json {"openapi":"3.1.0","info":{"title":"Minit Money Enterprise API","version":"1.12.8"},"tags":[{"name":"Beneficiaries","description":"Beneficiary management"}],"servers":[{"url":"/api/v1","description":"API v1"},{"url":"/","description":"API v0 (Legacy)"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for tenant authentication"}},"schemas":{"BeneficiaryListResponse":{"type":"array","items":{"$ref":"#/components/schemas/BeneficiaryDetails"}},"BeneficiaryDetails":{"type":"object","properties":{"beneficiary_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"deleted_at":{"type":["string","null"],"format":"date-time"},"first_name":{"type":"string"},"middle_name":{"type":["string","null"]},"last_name":{"type":"string"},"country":{"type":"string"},"phone_number":{"type":"string"},"daily_limit":{"type":"number"},"monthly_limit":{"type":"number"}}}}},"paths":{"/beneficiaries":{"get":{"tags":["Beneficiaries"],"summary":"Get all beneficiaries","description":"Retrieve a list of all beneficiaries for the authenticated tenant. Returns only active beneficiaries (not soft-deleted). Each beneficiary represents a recipient who can receive money transfers.","operationId":"getBeneficiaries","responses":{"200":{"description":"Successfully retrieved list of beneficiaries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeneficiaryListResponse"}}}}}}}}} ``` ## Create beneficiary > Create a new beneficiary (money recipient) for the authenticated tenant. The beneficiary's country must match supported destination countries in available corridors. Phone number must be in international E.164 format. Daily and monthly limits must be at least 1. ```json {"openapi":"3.1.0","info":{"title":"Minit Money Enterprise API","version":"1.12.8"},"tags":[{"name":"Beneficiaries","description":"Beneficiary management"}],"servers":[{"url":"/api/v1","description":"API v1"},{"url":"/","description":"API v0 (Legacy)"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for tenant authentication"}},"schemas":{"CreateBeneficiaryDto":{"type":"object","required":["first_name","last_name","country","phone_number","daily_limit","monthly_limit"],"properties":{"first_name":{"type":"string","minLength":1,"description":"Beneficiary's first name"},"middle_name":{"type":["string","null"],"description":"Beneficiary's middle name (optional)"},"last_name":{"type":"string","minLength":1,"description":"Beneficiary's last name"},"country":{"type":"string","minLength":1,"description":"Beneficiary's country. Must match a supported destination country in available corridors"},"phone_number":{"type":"string","description":"International phone number in E.164 format (e.g., +27821234567)"},"daily_limit":{"type":"number","minimum":1,"description":"Maximum amount this beneficiary can receive per day"},"monthly_limit":{"type":"number","minimum":1,"description":"Maximum amount this beneficiary can receive per month"}}},"BeneficiaryDetails":{"type":"object","properties":{"beneficiary_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"deleted_at":{"type":["string","null"],"format":"date-time"},"first_name":{"type":"string"},"middle_name":{"type":["string","null"]},"last_name":{"type":"string"},"country":{"type":"string"},"phone_number":{"type":"string"},"daily_limit":{"type":"number"},"monthly_limit":{"type":"number"}}}}},"paths":{"/beneficiaries":{"post":{"tags":["Beneficiaries"],"summary":"Create beneficiary","description":"Create a new beneficiary (money recipient) for the authenticated tenant. The beneficiary's country must match supported destination countries in available corridors. Phone number must be in international E.164 format. Daily and monthly limits must be at least 1.","operationId":"createBeneficiary","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBeneficiaryDto"}}}},"responses":{"201":{"description":"Beneficiary created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeneficiaryDetails"}}}},"400":{"description":"Bad request - Invalid input data"},"401":{"description":"Unauthorized - Invalid or missing API key"},"409":{"description":"Conflict - Beneficiary already exists"},"500":{"description":"Internal server error"}}}}}} ``` ## Get beneficiary details > Retrieve detailed information for a specific beneficiary by ID. Returns 404 if the beneficiary doesn't exist or has been deleted. Only returns beneficiaries belonging to the authenticated tenant. ```json {"openapi":"3.1.0","info":{"title":"Minit Money Enterprise API","version":"1.12.8"},"tags":[{"name":"Beneficiaries","description":"Beneficiary management"}],"servers":[{"url":"/api/v1","description":"API v1"},{"url":"/","description":"API v0 (Legacy)"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for tenant authentication"}},"schemas":{"BeneficiaryDetails":{"type":"object","properties":{"beneficiary_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"deleted_at":{"type":["string","null"],"format":"date-time"},"first_name":{"type":"string"},"middle_name":{"type":["string","null"]},"last_name":{"type":"string"},"country":{"type":"string"},"phone_number":{"type":"string"},"daily_limit":{"type":"number"},"monthly_limit":{"type":"number"}}}}},"paths":{"/beneficiaries/{beneficiaryId}":{"get":{"tags":["Beneficiaries"],"summary":"Get beneficiary details","description":"Retrieve detailed information for a specific beneficiary by ID. Returns 404 if the beneficiary doesn't exist or has been deleted. Only returns beneficiaries belonging to the authenticated tenant.","operationId":"getBeneficiaryDetails","parameters":[{"name":"beneficiaryId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved beneficiary details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeneficiaryDetails"}}}},"404":{"description":"Not found - Beneficiary does not exist or has been deleted","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"},"errorCode":{"type":"string"},"info":{"type":"object"}}}}}}}}}}}}} ``` ## Update beneficiary > Update an existing beneficiary's information. All fields from the create operation can be updated. The beneficiary must exist and belong to the authenticated tenant. Returns 404 if not found. ```json {"openapi":"3.1.0","info":{"title":"Minit Money Enterprise API","version":"1.12.8"},"tags":[{"name":"Beneficiaries","description":"Beneficiary management"}],"servers":[{"url":"/api/v1","description":"API v1"},{"url":"/","description":"API v0 (Legacy)"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for tenant authentication"}},"schemas":{"UpdateBeneficiaryDto":{"type":"object","required":["first_name","last_name","country","phone_number","daily_limit","monthly_limit"],"properties":{"first_name":{"type":"string","minLength":1},"middle_name":{"type":["string","null"]},"last_name":{"type":"string","minLength":1},"country":{"type":"string","minLength":1},"phone_number":{"type":"string","description":"International phone number in E.164 format"},"daily_limit":{"type":"number","minimum":1},"monthly_limit":{"type":"number","minimum":1}}},"BeneficiaryDetails":{"type":"object","properties":{"beneficiary_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"deleted_at":{"type":["string","null"],"format":"date-time"},"first_name":{"type":"string"},"middle_name":{"type":["string","null"]},"last_name":{"type":"string"},"country":{"type":"string"},"phone_number":{"type":"string"},"daily_limit":{"type":"number"},"monthly_limit":{"type":"number"}}}}},"paths":{"/beneficiaries/{beneficiaryId}":{"put":{"tags":["Beneficiaries"],"summary":"Update beneficiary","description":"Update an existing beneficiary's information. All fields from the create operation can be updated. The beneficiary must exist and belong to the authenticated tenant. Returns 404 if not found.","operationId":"updateBeneficiary","parameters":[{"name":"beneficiaryId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBeneficiaryDto"}}}},"responses":{"200":{"description":"Beneficiary updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeneficiaryDetails"}}}},"400":{"description":"Bad request - Invalid input data"},"401":{"description":"Unauthorized - Invalid or missing API key"},"404":{"description":"Not found - Beneficiary does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"},"errorCode":{"type":"string"},"info":{"type":"object"}}}}}}}},"500":{"description":"Internal server error"}}}}}} ``` ## Delete beneficiary > Soft delete a beneficiary by ID. This marks the beneficiary as deleted but preserves the record in the database. The beneficiary will no longer appear in list operations or be available for new transactions. ```json {"openapi":"3.1.0","info":{"title":"Minit Money Enterprise API","version":"1.12.8"},"tags":[{"name":"Beneficiaries","description":"Beneficiary management"}],"servers":[{"url":"/api/v1","description":"API v1"},{"url":"/","description":"API v0 (Legacy)"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for tenant authentication"}}},"paths":{"/beneficiaries/{beneficiaryId}":{"delete":{"tags":["Beneficiaries"],"summary":"Delete beneficiary","description":"Soft delete a beneficiary by ID. This marks the beneficiary as deleted but preserves the record in the database. The beneficiary will no longer appear in list operations or be available for new transactions.","operationId":"deleteBeneficiary","parameters":[{"name":"beneficiaryId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Beneficiary deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}}}}}},"401":{"description":"Unauthorized - Invalid or missing API key"},"404":{"description":"Not found - Beneficiary does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"},"errorCode":{"type":"string"},"info":{"type":"object"}}}}}}}},"500":{"description":"Internal server error"}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.minitmoney.enterprises/raas-api/beneficiaries.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.