Skip to main content
PUT
Create or Update Project (v1.5)
Use this endpoint when you operate a platform with many clients of your own and each client must scrub under their own FTC Org Id and Subscription Account Number (SAN). One DNCScrub Project per client keeps every client’s National DNC subscription, Internal DNC list and settings separate. Federal law does not allow one SAN to be shared across organizations.
During rollout, FTC Org Id / SAN validation is completed by our team rather than automatically: allow up to one business day for FtcValidation.Status to leave pending. Webhooks are not sent yet, so poll Get Project (no more than once a minute). Automatic validation and webhook delivery follow in a later release; requests and responses do not change.
PUT is idempotent: the same request creates the Project on first call and updates it afterwards. The Project code is the path segment; you choose it.

Update semantics

On update, the body is merged into the existing Project:
  • A field you omit (or send as null) is left unchanged.
  • Send an empty string to clear Notes or WebhookUrl. Clearing WebhookUrl also discards the stored secret. WebhookSecret cannot be cleared on its own (400); sending a new value rotates it.
  • ProjectName is required only when the Project is created.
  • FtcOrgId and FtcSan are always sent together; sending a new pair replaces the old one and starts a new validation. Resending the current pair is a no-op unless its last validation failed, in which case it is queued again. A pair with a different Org Id suspends the Project’s National DNC scrubbing until the new pair is validated; a new SAN under the same Org Id does not. They cannot be cleared through the API.
  • StateRegistrations is merged per state key: { "OK": {...} } adds or replaces OK and leaves LA untouched; { "OK": null } withdraws OK. New or changed proof is emailed to Support for review. Neither a change nor a withdrawal changes your account’s LA/OK scrubbing by itself.
  • UseMaster* flags change only when present.

What happens after you call it

  1. The Project (and its default Campaign) exists immediately and can accept uploads and API scrubs against Internal DNC, state lists you are authorized for, litigator lists, etc.
  2. The FTC Org Id and SAN you supplied are queued for validation against the FTC’s telemarketer portal. FtcValidation.Status starts as pending.
  3. When validation completes (usually within a couple of minutes; up to a few hours if the FTC portal is unavailable), the Project is enabled for National DNC scrubbing, FtcValidation.Status becomes validated (or failed with a reason), and if you supplied a WebhookUrl we POST the result to it. You can also poll Get Project.
  4. Any StateRegistrations you supplied are routed to our Support team for review. See Louisiana and Oklahoma Registration.

Request

Headers

string
required
Your API Key. An OAuth Authorization: Bearer token is accepted instead.
string
required
application/json

Path

string
required
Your identifier for the Project. 2 to 23 characters, letters and digits only; lowercase is uppercased. If your account has auto-prefixing enabled, <acctId>_ is prepended when missing, so BRIGHTDENTAL becomes VOXAI_BRIGHTDENTAL; the response and all later calls use the prefixed code, and either form is accepted on later calls. The prefixed code must fit in 30 characters. Reserved: codes starting with TMPL or equal to DNC or ROOT.

Body

string
Display name, usually your client’s company name. Up to 50 characters. Required when creating; optional on update.
string
Your client’s FTC Organization Id, for example 10000598-10598. Required if FtcSan is supplied.
string
Your client’s Subscription Account Number, for example 10000830-100830-07. Required if FtcOrgId is supplied. The SAN must belong to the Org Id; we verify that on the FTC portal.
object
Proof that your client is registered as a telemarketer in a state that requires it before its state Do Not Call list may be scrubbed. Keys are state abbreviations, currently LA and OK. Each value: { "Confirmation": string, "Notes": string }. Confirmation is the registration or confirmation number the state issued (up to 100 characters; Notes up to 1000). Supporting documents go to support@dnc.com, not through the API. See Louisiana and Oklahoma Registration.
string
HTTPS URL (up to 500 characters) we POST to when FTC validation completes. See Webhook. Must resolve to a public host: URLs with embedded credentials, non-443 ports, or hosts that resolve to loopback, private, link-local or reserved addresses are rejected with 400, both when saved and again at delivery time. Redirects are not followed. Requires WebhookSecret.
string
Shared secret, 16 to 128 characters, used to sign every delivery with HMAC-SHA256. Required when WebhookUrl is set (400 otherwise). Stored encrypted and never returned by the API; rotate it by sending a new value.
string
Free-form notes shown in the DNCScrub portal. Up to 512 characters.
boolean
default:"false"
Share the Master Project’s Internal DNC list with this Project. Leave false when each client must keep its own Internal DNC.
boolean
default:"false"
Share the Master Project’s EBR / exemption database.
boolean
default:"false"
Inherit the Master Project’s DNC policy.
boolean
default:"false"
Inherit the Master Project’s National DNC subscription instead of FtcOrgId/FtcSan. Only valid when the client is the same legal organization as the master account.
boolean
default:"false"
Inherit the Master Project’s training settings.

Example Request

Response

201 Created
Status is active or inactive.

ftcValidation.status

Webhook

Webhook delivery starts with automatic validation (see the rollout note at the top of this page); until then, poll Get Project. When WebhookUrl is set, we send POST requests with a JSON body:
Headers: Respond with any 2xx within 10 seconds. Anything else, or a timeout, is retried up to five times with exponential backoff (1 min, 5 min, 30 min, 2 h, 12 h), so six deliveries at most over about 15 hours. The most recent delivery outcome is visible on Get Project as Webhook.LastDelivery. Verify the signature and reject stale timestamps (older than 5 minutes) before trusting the body:
Verify signature (Node)

Best Practices

Org Id and SAN are optional on create. Create the Project as soon as your client signs up, then call the endpoint again with FtcOrgId and FtcSan once they have them. Only National DNC scrubbing waits on validation.
Validation completes asynchronously, usually within a couple of minutes. Subscribe with WebhookUrl and poll Get Project no more than once a minute if you need a fallback.
Pass the returned DefaultCampaignId as campaignId on Scrub API calls so each client’s numbers are scrubbed under that client’s own subscription and Internal DNC list.
POST https://www.dncscrub.com/app/main/rpc/project (docs) remains available for existing integrations. New integrations should use this endpoint.