{
  "info": {
    "_postman_id": "b2c3d4e5-agent-client-fintra",
    "name": "Fintra — Agent ↔ Client (AgentClientController)",
    "description": "## Agent ↔ Client (Many-to-Many) API\n\n**Base URL** is in collection variable `base_url` (default `http://127.0.0.1:8000/api`).\n\n### Auth\n1. Run **Back-office login** first. The test script saves `access_token` → `{{token}}` and `userdata.users_id` → `{{users_id}}`.\n2. Other requests use **Bearer** `{{token}}` from collection auth.\n\n### Routes (from `routes/api.php` lines 236–242)\n- `GET  {{base_url}}/agent/get-client-agent-details` → `AgentClientController@getClientsAgent`\n- `POST {{base_url}}/agent/deactivate-client-assignment` → `AgentClientController@deactivateClientAssignment`\n- `POST {{base_url}}/agent/assign-agent-to-user` → `AgentClientController@assignToAgent`\n- `POST {{base_url}}/agent/search-client` → `AgentClientController@searchClients`\n- `GET  {{base_url}}/agent/get-unassigned-agents` → `AgentClientController@getUnassignedAgents`\n- `GET  {{base_url}}/agent/get-client-agent` → `AgentClientController@showWithAgentCount`\n\nAll routes (except the `get-client-agent-details` one configured with the `api` middleware) require `jwt.auth`, `check.token`, and `dynamic.permission`. The logged-in role must have the corresponding submenu/API mapping or the request will return 403.\n\n### Prerequisites (DB)\n- `{{users_id}}`: back-office user (`fintra_back_users.user_id`) — set automatically after login.\n- `{{bo_initial_id}}`: existing row in `bo_initial_info.bo_in_id` for a BO client with `applicant_status = 1` in `bo_personal_info`.\n- `{{fintra_customer_id}}`: existing `bo_initial_info.fintr_customer_id`.\n- `{{agent_id}}`: existing `agent_user.id` (numeric primary key, not the `agent_id` string code).\n- `{{agent_assign_id}}`: an active row in `agent_assign_user` to deactivate.\n\n### Direction notes\n- `assignToAgent` = many agents → one BO. Skips agent IDs already active for that BO and reports them in `warnings.already_assigned_agent_ids`.\n- `deactivateClientAssignment` is the agent-side counterpart to `deactivateAgentAssignment`; both flip the same row.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    { "key": "base_url", "value": "http://127.0.0.1:8000/api" },
    { "key": "token", "value": "" },
    { "key": "users_id", "value": "" },
    { "key": "bo_initial_id", "value": "1" },
    { "key": "fintra_customer_id", "value": "FIN-000123" },
    { "key": "agent_id", "value": "1" },
    { "key": "agent_assign_id", "value": "1" },
    { "key": "page", "value": "1" },
    { "key": "per_page", "value": "10" }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [{ "key": "token", "value": "{{token}}", "type": "string" }]
  },
  "item": [
    {
      "name": "Auth — Back-office login",
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "try {",
              "  var json = pm.response.json();",
              "  if (json.access_token) { pm.collectionVariables.set('token', json.access_token); }",
              "  if (json.userdata && json.userdata.users_id != null) { pm.collectionVariables.set('users_id', String(json.userdata.users_id)); }",
              "} catch (e) { console.warn(e); }"
            ]
          }
        }
      ],
      "request": {
        "auth": { "type": "noauth" },
        "method": "POST",
        "header": [{ "key": "Accept", "value": "application/json" }],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"email\": \"your-backoffice@email.com\",\n  \"password\": \"your-password\"\n}",
          "options": { "raw": { "language": "json" } }
        },
        "url": "{{base_url}}/auth/login",
        "description": "Update email/password. On success, `token` and `users_id` collection variables are set for the next requests."
      },
      "response": []
    },
    {
      "name": "Agent ↔ Client — Assign multiple agents to one BO",
      "request": {
        "method": "POST",
        "header": [
          { "key": "Accept", "value": "application/json" },
          { "key": "Content-Type", "value": "application/json" }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"bo_initial_id\": {{bo_initial_id}},\n  \"agent_ids\": [1, 2, 3],\n  \"activity_flag\": \"A\"\n}",
          "options": { "raw": { "language": "json" } }
        },
        "url": {
          "raw": "{{base_url}}/agent/assign-agent-to-user",
          "host": ["{{base_url}}"],
          "path": ["agent", "assign-agent-to-user"]
        },
        "description": "Many-to-many assignment: assigns each `agent_id` in `agent_ids` to the given `bo_initial_id`.\n\n**Body**\n- `bo_initial_id` (int, required) — `bo_initial_info.bo_in_id`\n- `agent_ids` (int[], required, min 1) — each must exist in `agent_user.id`\n- `activity_flag` (string, required) — `A` or `I`\n\n**Behavior**\n- Skips a pair if `(agent_id, bo_initial_id)` is already active.\n- Returns 201 with `data.assignments`. If some agents were duplicates, `warnings.already_assigned_agent_ids` lists them. If all were duplicates, `status` is `false` and message says nothing was assigned."
      },
      "response": []
    },
    {
      "name": "Agent ↔ Client — Search client by fintra customer id",
      "request": {
        "method": "POST",
        "header": [
          { "key": "Accept", "value": "application/json" },
          { "key": "Content-Type", "value": "application/json" }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"fintra_customer_id\": \"{{fintra_customer_id}}\"\n}",
          "options": { "raw": { "language": "json" } }
        },
        "url": {
          "raw": "{{base_url}}/agent/search-client",
          "host": ["{{base_url}}"],
          "path": ["agent", "search-client"]
        },
        "description": "Looks up a BO client by `fintr_customer_id` and returns the client record plus all agents currently assigned to it (active only).\n\n**Body**\n- `fintra_customer_id` (string, required) — must exist in `bo_initial_info.fintr_customer_id`.\n\n**Response data**\n- `client_info`: `bo_initial_id`, `fintra_id`, `bo_id`, `client_name`, `client_phone`, `client_email`, `client_branch`, `account_type` (`Individual` / `Joint` / `Company`).\n- `agent_info[]`: `agent__pmid`, `agent_name`, `agent_id`, `agent_email`, `agent_phone`, `branch_name`.\n\nReturns 404 with `BO client not found` when there is no active applicant row for the given customer id."
      },
      "response": []
    },
    {
      "name": "Agent ↔ Client — Get agents assigned to a BO",
      "request": {
        "method": "GET",
        "header": [{ "key": "Accept", "value": "application/json" }],
        "url": {
          "raw": "{{base_url}}/agent/get-client-agent-details?bo_initial_id={{bo_initial_id}}",
          "host": ["{{base_url}}"],
          "path": ["agent", "get-client-agent-details"],
          "query": [
            { "key": "bo_initial_id", "value": "{{bo_initial_id}}" }
          ]
        },
        "description": "Returns all active agents for a given BO.\n\n**Query / body**\n- `bo_initial_id` (int, required) — `bo_initial_info.bo_in_id`.\n\n**Response data**\n- `agent_info[]`: `agent_assign_id`, `agent__pmid`, `agent_id`, `agent_name`, `agent_email`, `agent_phone`, `agent_commission`, `brokerhouse_commission`, `agent_branch`.\n\nNote: this route is registered with the bare `api` middleware (no JWT). If you tighten it later, switch the request auth from inherited to bearer."
      },
      "response": []
    },
    {
      "name": "Agent ↔ Client — Deactivate client assignment",
      "request": {
        "method": "POST",
        "header": [
          { "key": "Accept", "value": "application/json" },
          { "key": "Content-Type", "value": "application/json" }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"agent_id\": {{agent_id}},\n  \"agent_assign_id\": {{agent_assign_id}},\n  \"users_id\": {{users_id}}\n}",
          "options": { "raw": { "language": "json" } }
        },
        "url": {
          "raw": "{{base_url}}/agent/deactivate-client-assignment",
          "host": ["{{base_url}}"],
          "path": ["agent", "deactivate-client-assignment"]
        },
        "description": "Agent-side counterpart of `deactivate-assignment`. Flips `agent_assign_user.activity_flag` from `A` to `I` for the matching row.\n\n**Body**\n- `agent_id` (int, required) — `agent_user.id`.\n- `agent_assign_id` (int, required) — `agent_assign_user.id`.\n- `users_id` (int) — `fintra_back_users.user_id` of the actor; written into `updated_by`.\n\nReturns 404 with `Active assignment not found for the provided IDs` if the row does not belong to that agent or is already inactive."
      },
      "response": []
    },
    {
      "name": "Agent ↔ Client — Get unassigned agents (paginated)",
      "request": {
        "method": "GET",
        "header": [{ "key": "Accept", "value": "application/json" }],
        "url": {
          "raw": "{{base_url}}/agent/get-unassigned-agents?per_page={{per_page}}&page={{page}}",
          "host": ["{{base_url}}"],
          "path": ["agent", "get-unassigned-agents"],
          "query": [
            { "key": "per_page", "value": "{{per_page}}" },
            { "key": "page", "value": "{{page}}" }
          ]
        },
        "description": "Lists agents that have **no row at all** in `agent_assign_user` (even an inactive one excludes them).\n\n**Query**\n- `per_page` (int, default 10).\n- `page` (int, default 1).\n\n**Response data**\n- `data[]`: `agent__pmid`, `agent_id`, `agent_name`, `agent_email`, `agent_phone`, `agent_commission`, `brokerhouse_commission`, `agent_branch`.\n- `pagination`: standard Laravel paginator fields."
      },
      "response": []
    },
    {
      "name": "Agent ↔ Client — List clients with agent count (paginated)",
      "request": {
        "method": "GET",
        "header": [{ "key": "Accept", "value": "application/json" }],
        "url": {
          "raw": "{{base_url}}/agent/get-client-agent?per_page={{per_page}}&page={{page}}",
          "host": ["{{base_url}}"],
          "path": ["agent", "get-client-agent"],
          "query": [
            { "key": "per_page", "value": "{{per_page}}" },
            { "key": "page", "value": "{{page}}" }
          ]
        },
        "description": "Mirror of `showWithClientCount` (in `AgentController`). Paginates active BO clients (`applicant_status = 1`) ordered by `bo_initial_info.created_at` desc, and attaches `agent_assigned_num` per row.\n\n**Query**\n- `per_page` (int, default 10, max 100).\n- `page` (int, default 1).\n\n**Response data**\n- `data[]`: `bo_initial_id`, `fintra_id`, `bo_id`, `client_name`, `client_phone`, `client_email`, `client_branch`, `created_at`, `agent_assigned_num`, `account_type`.\n- `pagination`: includes `current_page`, `per_page`, `total`, `last_page`, `from`, `to`, `has_more_pages`, `has_previous_page`, `has_next_page`."
      },
      "response": []
    }
  ]
}
