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

# Submit One-Time Scan

> Submit a batch of phone numbers for one-time carrier spam score scanning

Submit a batch of phone numbers for one-time carrier spam score scanning. Results are delivered asynchronously via webhook notification.

<Note>
  Unlike TrustCall monitoring, one-time scans do not add numbers to ongoing
  monitoring. Results are delivered to your webhook URL when the scan completes.
</Note>

## Request

### Headers

<ParamField header="loginId" type="string" required>
  Your API Key (LoginId from your DNCScrub account)
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Request Body

<ParamField body="PhoneNumbers" type="string[]" required>
  Array of 10-digit phone number strings to scan
</ParamField>

<ParamField body="NotificationURL" type="string" required>
  Webhook URL where scan results will be POSTed when complete. Maximum 1500 characters.
</ParamField>

<Tip>
  Consider using [webhook.site](https://webhook.site) to generate a temporary
  URL for testing. It lets you inspect the exact payload and headers sent by the
  callback, making it easy to understand the webhook structure before
  implementing your production endpoint.
</Tip>

<ParamField body="NotificationAPIKey" type="string">
  Optional API key to include in the webhook notification header. Maximum 1500 characters.
</ParamField>

<ParamField body="ScanType" type="string" required>
  Type of scan to perform: - `carrier` - Carrier scores only (Verizon, AT\&T,
  T-Mobile) - `carrierandapps` - Carrier scores plus app scores (RoboKiller,
  Nomorobo, FTC complaints)
</ParamField>

<ParamField body="TestNotificationURL" type="boolean">
  Set to `true` to test your webhook URL without performing an actual scan. The system will send a test payload to verify your endpoint is reachable.
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request POST \
    'https://dataapi.dncscrub.com/v1.5/TrustCall/OneTimeScan' \
    --header 'loginId: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "PhoneNumbers": ["5039367187", "8084565302", "7867056421"],
      "NotificationURL": "https://your-server.com/webhook/trustcall",
      "NotificationAPIKey": "your-webhook-api-key",
      "ScanType": "carrierandapps"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://dataapi.dncscrub.com/v1.5/TrustCall/OneTimeScan",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        loginId: "YOUR_API_KEY",
      },
      body: JSON.stringify({
        PhoneNumbers: ["5039367187", "8084565302", "7867056421"],
        NotificationURL: "https://your-server.com/webhook/trustcall",
        NotificationAPIKey: "your-webhook-api-key",
        ScanType: "carrierandapps",
      }),
    }
  );
  const data = await response.json();
  console.log(data);
  ```

  ```csharp C# theme={null}
  using (var client = new HttpClient())
  {
      client.DefaultRequestHeaders.Add("loginId", "YOUR_API_KEY");

      var requestData = new
      {
          PhoneNumbers = new[] { "5039367187", "8084565302", "7867056421" },
          NotificationURL = "https://your-server.com/webhook/trustcall",
          NotificationAPIKey = "your-webhook-api-key",
          ScanType = "carrierandapps"
      };

      var content = new StringContent(
          JsonSerializer.Serialize(requestData),
          Encoding.UTF8,
          "application/json"
      );

      var response = await client.PostAsync(
          "https://dataapi.dncscrub.com/v1.5/TrustCall/OneTimeScan",
          content
      );

      var result = await response.Content.ReadAsStringAsync();
      Console.WriteLine(result);
  }
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "JobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "Status": "Submitted",
    "PhoneCount": 3
  }
  ```
</ResponseExample>

## Response Fields

<ResponseField name="JobId" type="string (UUID)">
  Unique identifier for the scan job. Use this to check scan status.
</ResponseField>

<ResponseField name="Status" type="string">
  Initial status of the scan: `Submitted`
</ResponseField>

<ResponseField name="PhoneCount" type="integer">
  Number of phone numbers submitted for scanning
</ResponseField>

## Webhook Notification

When the scan completes, results are POSTed to your `NotificationURL`:

```json theme={null}
{
  "JobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "Status": "Complete",
  "Results": [
    {
      "Phone": "5039367187",
      "CurrScore": "Clean",
      "VerizonScore": "Clean",
      "ATTScore": "Clean",
      "TMobileScore": "Clean",
      "RoboKillerStatus": "Clean",
      "NomoroboStatus": "Clean",
      "FTCComplaints": null
    }
  ]
}
```

## Error Responses

| Status           | Description                                                      |
| ---------------- | ---------------------------------------------------------------- |
| 400 Bad Request  | Invalid request body or phone number format                      |
| 401 Unauthorized | Invalid or missing API key                                       |
| 403 Forbidden    | Account not authorized for one-time scan or insufficient credits |
| 500 Server Error | Internal server error                                            |

## Scan Types

| Scan Type        | Included Data                                         |
| ---------------- | ----------------------------------------------------- |
| `carrier`        | Verizon, AT\&T, T-Mobile scores                       |
| `carrierandapps` | Carrier scores + RoboKiller, Nomorobo, FTC complaints |