---
title: "Async batch variant of kyc_screener. Accepts 1-100 names and returns immediately (<300ms) with a job_id. The screening r"
method: POST
path: "/api/v1/call/kyc_screener_batch"
tags: ["compliance", "expertise"]
---

# Async batch variant of kyc_screener. Accepts 1-100 names and returns immediately (<300ms) with a job_id. The screening r

`POST /api/v1/call/kyc_screener_batch`

## Request

- Base URL: `https://mcp.gapup.io`
- URL: `https://mcp.gapup.io/api/v1/call/kyc_screener_batch`
- Auth: HTTP bearer

Async batch variant of kyc_screener. Accepts 1-100 names and returns immediately (<300ms) with a job_id. The screening runs in the background (up to 10 parallel KYC calls). Poll the result with kyc_screener_batch_result(job_id) after the eta_seconds hint. Each entry can specify name, type (person/company/any), and an optional birthdate hint. Use for bulk client onboarding, UBO list screening, or periodic AML refresh batches. Async tool — register a webhook via `webhooks_manage(register, url, [job.completed])` to receive callbacks instead of polling. Faster + lighter.

## Request body

- object
  - `names` object[], required: List of entities to screen (1-100). Each entry requires at minimum a name.
    - `name` string, required: Full name of person or legal entity
    - `type` 'person' | 'company' | 'any': Entity type hint. Defaults to 'any'.
    - `birthdate` string: Optional birthdate (YYYY-MM-DD) for disambiguation
  - `async` boolean: If true, returns a job_id immediately (<200ms) instead of waiting for the result. Poll the result with job_result(job_id). Use for slow tools to avoid client timeouts.

## Response `200`

Tool result

- object
  - `tool` string
  - `result` object
    - `job_id` string, required: Unique job identifier — pass to kyc_screener_batch_result
    - `status` 'queued', required
    - `eta_seconds` number, required: Estimated seconds until result is ready
    - `submitted_at` string, required: ISO-8601 submission timestamp
    - `batch_size` number, required: Number of names queued for screening
  - `request_id` string
  - `source` 'rest-api'
  - `ms` number

## Other responses

- `400`: Invalid arguments
- `401`: Unauthorized
- `402`: Payment Required — pay via x402 (USDC on Base) then retry with X-Payment header
- `404`: Tool not found
- `429`: Rate limited
- `500`: Internal error

---

[API](https://skmtc.dev/gapup/apis/gapup-mcp-rest-api.md) · [All operations](https://skmtc.dev/gapup/apis/gapup-mcp-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gapup/apis/gapup-mcp-rest-api/revisions/afb9da3b98f4?raw)