> ## 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.

# Scrub with Unique Identifiers

> Pass a unique identifier with each phone number

Pass a unique identifier (such as Account ID, Record ID, or Member ID) with each phone number and have it returned in the response. This allows you to easily match scrub results back to your records.

## How It Works

Append a pipe character (`|`) followed by your unique identifier to each phone number:

```
phoneList=5039367181|UniqueID
```

The unique identifier will be returned in the `Reserved` field of the response.

An optional third field carries the contact's postal code, which switches the
time zone and calling-window calculation from the number's area code to the
postal code (see [Postal Code Time
Zones](/api-reference/scrub/scrub-single#postal-code-time-zones)):

```
phoneList=5039367181|UniqueID|10001
phoneList=5039367181||10001      (no identifier)
```

## Request

### Headers

<ParamField header="loginId" type="string" required>
  Your API Key
</ParamField>

### Query Parameters

<ParamField query="phoneList" type="string" required>
  Phone number with identifier in format: `PHONE|ID` (e.g.,
  `5039367181|ACCT-12345`), optionally followed by a postal code:
  `PHONE|ID|POSTALCODE` (e.g., `5039367181|ACCT-12345|10001`). For multiple
  numbers, comma-separate them: `5039367181|ACCT-001,7075276405|ACCT-002`
</ParamField>

<ParamField query="version" type="string" required default="8">
  API version. Use `8` (latest). Version `6` adds `EBRExpiresOn`; version `7`
  adds `WirelessPortDate` and `VoIPDate`; version `8` adds `PostalCode`, `TZSource`,
  `IsCallAllowedNonATDS`, `IsCallAllowedATDS` and `IsCallAllowedAI`.
</ParamField>

<ParamField query="output" type="string" default="csv">
  Response format: `json` or `csv`
</ParamField>

<ParamField query="projId" type="string">
  Project ID
</ParamField>

<ParamField query="campaignId" type="string">
  Campaign ID
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET \
    'https://www.dncscrub.com/app/main/rpc/scrub?phoneList=5039367181|ACCT-12345&version=8&output=json' \
    --header 'loginId: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const phoneNumber = "5039367181";
  const accountId = "ACCT-12345";

  const response = await fetch(
    `https://www.dncscrub.com/app/main/rpc/scrub?phoneList=${phoneNumber}|${accountId}&version=8&output=json`,
    {
      method: "GET",
      headers: { loginId: "YOUR_API_KEY" },
    }
  );

  const data = await response.json();
  console.log("Account ID:", data.results[0].Reserved); // "ACCT-12345"
  ```

  ```csharp C# theme={null}
  System.Net.ServicePointManager.SecurityProtocol = System.Net.SecurityProtocolType.Tls12;

  using (var client = new HttpClient())
  {
      client.DefaultRequestHeaders.Add("loginId", "YOUR_API_KEY");

      var phoneNumber = "5039367181";
      var accountId = "ACCT-12345";
      var url = $"https://www.dncscrub.com/app/main/rpc/scrub?phoneList={phoneNumber}|{accountId}&version=8&output=json";

      var response = await client.GetStringAsync(url);
      Console.WriteLine(response);
  }
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "version": 8,
    "results": [
      {
        "Phone": "5039367181",
        "ResultCode": "W",
        "Reserved": "ACCT-12345",
        "Reason": ";;;W",
        "RegionAbbrev": "OR",
        "Country": "US",
        "Locale": "Portland",
        "CarrierInfo": "5820;WIRELESS;\"Verizon Wireless:Verizon Wireless\"",
        "NewReassignedAreaCode": null,
        "TZCode": 4,
        "CallingWindow": "8:00-21:00;8:00-21:00;8:00-21:00",
        "UTCOffset": -420,
        "DoNotCallToday": false,
        "CallingTimeRestrictions": 4,
        "EBRType": null,
        "IsWirelessOrVoIP": true,
        "LineType": "Wireless",
        "EBRExpiresOn": null,
        "WirelessPortDate": null,
        "VoIPDate": null,
        "PostalCode": null,
        "TZSource": "areaCode",
        "IsCallAllowedNonATDS": true,
        "IsCallAllowedATDS": false,
        "IsCallAllowedAI": false
      }
    ]
  }
  ```
</ResponseExample>

<Note>
  The `Reserved` field contains your unique identifier `"ACCT-12345"`.
</Note>

## Response Fields

<ResponseField name="Phone" type="string">
  The phone number that was scrubbed
</ResponseField>

<ResponseField name="ResultCode" type="string">
  The scrub result code (see [Result
  Codes](/api-reference/scrub/overview#result-codes))
</ResponseField>

<ResponseField name="Reserved" type="string | null">
  Your unique identifier passed with the phone number, otherwise `null`
</ResponseField>

<ResponseField name="Reason" type="string">
  Explanation of why the number is flagged
</ResponseField>

<ResponseField name="RegionAbbrev" type="string">
  State/region abbreviation (e.g., "CA")
</ResponseField>

<ResponseField name="Country" type="string">
  Country code (e.g., "US")
</ResponseField>

<ResponseField name="Locale" type="string">
  City or locality
</ResponseField>

<ResponseField name="CarrierInfo" type="string">
  Carrier information in format: `ID;TYPE;"Name"`
</ResponseField>

<ResponseField name="TZCode" type="integer">
  Timezone code
</ResponseField>

<ResponseField name="UTCOffset" type="integer">
  UTC offset in minutes for the destination, adjusted for DST (e.g. `-240`)
</ResponseField>

<ResponseField name="IsWirelessOrVoIP" type="boolean">
  `true` if wireless or VoIP
</ResponseField>

<ResponseField name="LineType" type="string">
  Line type: `Wireless`, `VoIP`, or `AllOther`
</ResponseField>

<ResponseField name="PostalCode" type="string | null">
  Normalized postal code used for the time zone calculation (`10001`, `M5V`).
  `null` if none was supplied. Requires `version=8` or higher
</ResponseField>

<ResponseField name="TZSource" type="string">
  `postalCode` when the time zone and calling window were derived from the
  supplied postal code, otherwise `areaCode`. See [Postal Code Time
  Zones](/api-reference/scrub/scrub-single#postal-code-time-zones). Requires
  `version=8` or higher
</ResponseField>

<ResponseField name="IsCallAllowedNonATDS" type="boolean">
  `true` if a **manually dialed, live-agent** marketing call may be placed to this number right now. Combines `ResultCode`, `DoNotCallToday` and
  the calling window. See [Is the call
  allowed?](/api-reference/scrub/output-guide#is-the-call-allowed) for the rules
  and for when this flag applies to you. Requires `version=8` or higher
</ResponseField>

<ResponseField name="IsCallAllowedATDS" type="boolean">
  Same checks, for calls placed by an **autodialer** (federal or state
  definition). Wireless and VoIP numbers return `false` unless a Permission (`P`)
  EBR — express written consent — is on file. Requires `version=8` or higher
</ResponseField>

<ResponseField name="IsCallAllowedAI" type="boolean">
  Same checks, for calls using an **artificial, prerecorded or AI-generated
  voice**. `true` only when a Permission (`P`) EBR is on file and still valid
  (`EBRType` is `P` and `ResultCode` is `E`, `O`, `G` or `H`) — any line type.
  Clean numbers without consent return `false`. See [Compliance for AI Voice
  Agents](/api-reference/scrub/ai-voice-agents). Requires `version=8` or higher
</ResponseField>

For the full field list see the [Output Guide](/api-reference/scrub/output-guide).

## Multiple Numbers with Identifiers

Comma-separate multiple phone numbers with their identifiers:

```
phoneList=5039367181|ACCT-001,7075276405|ACCT-002,7072842774|ACCT-003
```

### Example

```javascript theme={null}
const records = [
  { phone: "5039367181", accountId: "ACCT-001" },
  { phone: "7075276405", accountId: "ACCT-002" },
  { phone: "7072842774", accountId: "ACCT-003" },
];

const phoneList = records.map((r) => `${r.phone}|${r.accountId}`).join(",");

// phoneList = "5039367181|ACCT-001,7075276405|ACCT-002,7072842774|ACCT-003"

const response = await fetch(
  `https://www.dncscrub.com/app/main/rpc/scrub?phoneList=${encodeURIComponent(
    phoneList
  )}&version=8&output=json`,
  {
    method: "GET",
    headers: { loginId: "YOUR_API_KEY" },
  }
);

const { results } = await response.json();

// Match results back to original records
results.forEach((result) => {
  console.log(`Account ${result.Reserved}: ${result.ResultCode}`);
});
```

## Use Cases

<CardGroup cols={2}>
  <Card title="CRM Integration" icon="address-book">
    Pass your CRM Record ID to update records directly after scrubbing
  </Card>

  <Card title="Batch Processing" icon="layer-group">
    Track which phone number belongs to which customer in large batches
  </Card>

  <Card title="Audit Trail" icon="clipboard-list">
    Include transaction IDs for compliance logging
  </Card>

  <Card title="Database Updates" icon="database">
    Pass primary keys to enable efficient database updates
  </Card>
</CardGroup>

## Best Practices

<Warning>
  The unique identifier should not contain commas (`,`) or pipe characters (`|`)
  as these are used as delimiters. The pipe fields are positional: the second
  is always the identifier and the third is always the postal code, so use
  `PHONE||POSTALCODE` to pass a postal code without an identifier.
</Warning>

* Keep identifiers reasonably short
* Use URL-safe characters
* Consider encoding special characters if needed


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.