---
updatedAt: 2026-06-09T17:02:41.000Z
---

Fetch the complete documentation index at: https://hq.docs.netevia.com/llms.txt. Use this file to discover all available pages before exploring further.

# Get agent details

## Get Agent Details

Returns an array of agent profile records matching the supplied query criteria. Each profile includes the agent's name, payout number, office affiliation, and contact details. This endpoint is typically the first call made in the V2 boarding workflow — the returned `id` field (agent profile ID) is required when creating or submitting a merchant application.

### Endpoint

`GET /api/v2/agent/profile`

### Authentication

Basic HTTP Authentication required.
Encode `username:password` in Base64 and pass in the Authorization header:

```
Authorization: Basic {base64(username:password)}
```

### When to use

Call this endpoint at the start of the boarding flow to look up the agent profile ID that will be associated with a new merchant. You can search by either `agentId` (the internal user ID of the agent) or `payoutNumber` (the agent's payout/commission identifier). If both are omitted, the API returns all profiles accessible to the authenticated user.

### Query Parameters

| Parameter    | Type            | Required | Description                              |
| ------------ | --------------- | -------- | ---------------------------------------- |
| agentId      | integer (int32) | No       | Internal agent user ID to filter results |
| payoutNumber | string          | No       | Agent's payout number to filter results  |

### Response

**200 OK**

| Field                   | Type                  | Description                                                         |
| ----------------------- | --------------------- | ------------------------------------------------------------------- |
| data                    | array of AgentProfile | List of matching agent profiles                                     |
| data\[].id              | integer               | Agent profile ID — use as `agentProfileId` when creating a merchant |
| data\[].name            | string                | Display name of the agent profile                                   |
| data\[].payoutNumber    | string                | Payout/commission number for the agent                              |
| data\[].agentId         | integer               | Internal agent user ID                                              |
| data\[].agentName       | string                | Full name of the agent                                              |
| data\[].agentOfficeId   | integer               | ID of the agent's office/branch                                     |
| data\[].agentOfficeName | string                | Name of the agent's office/branch                                   |
| data\[].agentUserName   | string                | Login username of the agent                                         |
| data\[].email           | string                | Agent's email address                                               |
| data\[].phone           | string                | Agent's contact phone number                                        |
| requestId               | integer               | Echo of the internal request ID                                     |
| success                 | boolean               | `true` if the call succeeded                                        |
| error                   | string                | Error message if `success` is `false`                               |
| validationErrors        | array                 | Field-level validation errors if any                                |

```json
{
  "data": [
    {
      "id": 204,
      "name": "Southwest Sales Profile",
      "payoutNumber": "PAY-00441",
      "agentId": 88,
      "agentName": "David Chen",
      "agentOfficeId": 12,
      "agentOfficeName": "Phoenix Regional Office",
      "agentUserName": "dchen",
      "email": "d.chen@isopartner.com",
      "phone": "6025550311"
    }
  ],
  "requestId": 10042,
  "success": true,
  "error": null,
  "validationErrors": []
}
```

### Error Codes

| Code | When it happens                                                    |
| ---- | ------------------------------------------------------------------ |
| 400  | Query parameter values are malformed (e.g., non-integer `agentId`) |
| 401  | Invalid or missing Basic Auth credentials                          |
| 403  | User does not have permission to view the requested agent profile  |
| 404  | No agent profiles found matching the supplied criteria             |
| 500  | Internal server error                                              |

### Common Mistakes

* Confusing `data[].id` (the agent *profile* ID used in `agentProfileId`) with `data[].agentId` (the agent *user* ID) — only `data[].id` is the correct value to pass as `agentProfileId` when creating a merchant.
* Not filtering by `agentId` or `payoutNumber` when the authenticated user has access to many profiles — an unfiltered call may return a large list and cause confusion.
* Calling this endpoint with a V1 path (`/api/v1/agent/profile`) — ensure you are using the V2 endpoint when working in the V2 boarding workflow.

### Related Endpoints

* `POST /api/v2/merchant/create` — Create a new merchant using the `agentProfileId` returned here
* `POST /api/v2/merchant/submit` — Submit the full merchant application
* `GET /api/v2/merchant/info` — Retrieve current merchant profile information

### Example

```bash
curl -X GET "https://hq.staging.netevia.dev/api/v2/agent/profile?agentId=88" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Accept: application/json"
```

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "version": "v2",
    "title": "Netevia HQ | API Documentation",
    "description": "Netevia HQ | API Documentation"
  },
  "paths": {
    "/api/v2/agent/profile": {
      "get": {
        "tags": [
          "Data Collections and Variables"
        ],
        "summary": "Get agent details",
        "operationId": "BoardingV2_GetAgentProfileById",
        "parameters": [
          {
            "name": "agentId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "payoutNumber",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResultArray1_AgentProfile"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResultArray1_AgentProfile"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResultArray1_AgentProfile"
                }
              },
              "text/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResultArray1_AgentProfile"
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "Basic": []
    }
  ],
  "servers": [
    {
      "url": "https://hq.staging.netevia.dev"
    }
  ],
  "components": {
    "securitySchemes": {
      "Basic": {
        "type": "http",
        "description": "Basic HTTP Authentication",
        "scheme": "basic"
      }
    },
    "schemas": {
      "ApiResultArray1_AgentProfile": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentProfile"
            }
          },
          "requestId": {
            "format": "int32",
            "type": "integer"
          },
          "success": {
            "type": "boolean"
          },
          "error": {
            "type": "string"
          },
          "validationErrors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            }
          }
        }
      },
      "AgentProfile": {
        "type": "object",
        "properties": {
          "id": {
            "format": "int32",
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "payoutNumber": {
            "type": "string"
          },
          "agentId": {
            "format": "int32",
            "type": "integer"
          },
          "agentName": {
            "type": "string"
          },
          "agentOfficeId": {
            "format": "int32",
            "type": "integer"
          },
          "agentOfficeName": {
            "type": "string"
          },
          "agentUserName": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          }
        }
      },
      "ValidationError": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```