> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vouchmark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Physical address verification

> Submit a business address for physical verification, then poll for the result.

Submit a company's business address for physical verification through the underlying KYC provider, then poll for the result. Submission returns a `reference_id` and an initial `status`; the status endpoint reports progress and, once complete, the captured address data. Both calls require an authenticated owner. The submit body is JSON.

## Submit — `POST /v1/physicalAddress`

<ParamField body="companyId" type="string" required>
  The company being verified.
</ParamField>

<ParamField body="business_name" type="string" required />

<ParamField body="business_mobile" type="string" required />

<ParamField body="first_name" type="string" required />

<ParamField body="last_name" type="string" required />

<ParamField body="mobile" type="string" required />

<ParamField body="street" type="string" required />

<ParamField body="landmark" type="string" required />

<ParamField body="lga" type="string" required />

<ParamField body="city" type="string" required />

<ParamField body="state" type="string" required />

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.vouchmark.com/v1/physicalAddress \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "companyId": "cmp_aBcD...",
      "business_name": "Tekcify Technologies Ltd",
      "business_mobile": "08030000000",
      "first_name": "Jane",
      "last_name": "Doe",
      "mobile": "08031111111",
      "street": "14 Marina Road",
      "landmark": "Opposite the City Mall",
      "lga": "Lagos Island",
      "city": "Lagos",
      "state": "Lagos"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Submitted theme={null}
  {
    "entity": {
      "status": "pending",
      "reference_id": "addr_aBcD..."
    }
  }
  ```
</ResponseExample>

## Check status — `GET /v1/physicalAddress`

Poll with either the `reference_id` from submission or the `companyId`. At least one is required.

<ParamField query="reference_id" type="string">
  The reference returned at submission.
</ParamField>

<ParamField query="companyId" type="string">
  The company whose latest address verification you want. Resolves to the stored reference.
</ParamField>

```bash cURL theme={null}
curl "https://api.vouchmark.com/v1/physicalAddress?companyId=cmp_aBcD..." \
  -H "Authorization: Bearer $TOKEN"
```

Until the visit completes, `data` is absent. Once complete, `data` carries the captured applicant, location, and photos.

```json Status — completed theme={null}
{
  "entity": {
    "status": "completed",
    "reference_id": "addr_aBcD...",
    "data": {
      "applicant": {
        "first_name": "Jane",
        "last_name": "Doe",
        "phone": "08031111111"
      },
      "location": "14 Marina Road, Lagos",
      "photos": ["https://..."],
      "city": "Lagos",
      "street": "14 Marina Road",
      "lga": "Lagos Island",
      "state": "Lagos",
      "country": "Nigeria"
    }
  }
}
```

## Errors

| Status | Body                                                                                            | When                                                  |
| ------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `401`  | `{ "message": "Unauthorized" }`                                                                 | No authenticated user.                                |
| `400`  | `{ "message": "companyId is required" }`                                                        | Submit without `companyId`.                           |
| `400`  | `{ "message": "Missing required fields: ..." }`                                                 | One or more required submit fields are empty.         |
| `400`  | `{ "message": "Either reference_id or companyId is required" }`                                 | Status check with neither parameter.                  |
| `404`  | `{ "message": "Company not found or you don't have access to it" }`                             | The company is missing or not yours.                  |
| `404`  | `{ "message": "No address verification found for this company" }`                               | Status check by `companyId` with no prior submission. |
| `402`  | `{ "message": "Monthly investigation budget limit exceeded", "code": "...", "details": {...} }` | The monthly budget cap was reached.                   |

Submission is rate limited to 5 attempts per 24 hours per caller.