Overview
CalPrivacy publishes an OpenAPI 3.1 description of the API, version 1.3.0 of 19 November 2026, alongside a human guide. CalPrivacy is plain about it: “Integration via API is not required.” Brokers can download and upload in the DROP portal instead. The API is worth it when you want downloads to happen on schedule without anyone logging in; DROP API or manual upload weighs the two.
| Environment | Base URL |
|---|---|
| Production | https://api.drop.privacy.ca.gov |
| Sandbox | https://api.drop.privacy.ca.gov/sandbox |
That is the whole surface. There is no pagination, no filter by date or list (your key's list selection decides what you get), no endpoint to ask for a batch's status, and no endpoint for rejected-row details. Completion and validation results arrive by email and, optionally, webhook.
API keys
Every call carries the key in an X-API-KEY header over TLS 1.2 or later. There is no OAuth and no request signing. A call without a key returns 401.
- Keys are issued in the broker's DROP account: select the consumer deletion lists, save, then open the API Key tab and get a new key. Sandbox keys are issued separately in the sandbox area.
- A key is scoped to the lists selected when it was issued. Only those lists appear in the batch.
- Keys do not expire. Issuing a new key deactivates all previous ones, so a rotation in the portal silently breaks any integration using the old key.
- Changing list selection means issuing a new key.
The DROP account and its key belong to the broker. Keep the key encrypted at rest and treat a 401 as “someone rotated the key”, with an alert to a person rather than a retry.
GET /data/download
curl -sS https://api.drop.privacy.ca.gov/data/download \
-H "X-API-KEY: $DROP_KEY" \
-H "Accept: application/zip, application/json" \
-o batch.zip -D headers.txtThe first call asks DROP to build the package. Poll until it is ready.
| Response | Meaning | What to do |
|---|---|---|
200 ZIP | The batch. The file name is in Content-Disposition. | Store it durably before anything else. The clock has started. |
200 JSON | No new requests or removals since your last completed download. | Record the check; nothing to process. |
202 | Package being built. | Wait for Retry-After seconds and call again. |
401 | Key missing or invalid. | Do not retry; get a valid key. |
403 | Account not eligible (registration, payment, access) or no lists selected. | Do not retry; fix the account. |
409 | The current batch still has outstanding work items. | Finish the open batch first. |
429 | Too many requests. | Wait for Retry-After (the example is 30 seconds). |
500 | DROP temporarily unavailable. | Retry later. |
The 409 matters more than it looks. A batch you have downloaded is not served again on request while it is open, so if you lose the ZIP you need DROP support. What is inside the ZIP is described in how to process DROP requests.
POST /data/upload
curl -sS https://api.drop.privacy.ca.gov/data/upload \
-H "X-API-KEY: $DROP_KEY" \
-H "Accept: application/json" \
-F "files=@20261120_4821_Email.csv;type=text/csv" \
-F "files=@20261120_4821_NDZ.csv;type=text/csv"multipart/form-datawith one or more parts namedfiles. CSV only, never zipped.- Up to 10 files and 100 MB per request; up to 100 files per batch across all uploads.
- Each file has the header
Id,Statusand reuses the downloaded file name, with a suffix such as_part02for a second file. - Wait for one request's record-level validation to finish before sending the next.
202 means at least one file was accepted and queued; 400 means none was. Both return a body listing each file:
{
"message": "Upload received. Accepted files were queued for validation. ...",
"acceptedCount": 1,
"rejectedCount": 1,
"accepted": [{ "fileName": "20261120_4821_Email.csv", "fileSizeBytes": 2849112 }],
"rejected": [{ "fileName": "notes.txt", "message": "Only CSV files are accepted." }]
}File-level rejections cover a missing file, a non-CSV file, a wrong header, a name already used for this download, and a file that is not readable UTF-8. Row-level checks come later, by email and webhook: each ID must be one DROP delivered to you, appear once, and carry 2, 3, 4 or 5. Rejected rows are listed in the portal; send them again through /data/upload in a new file. A 409 here means no download is waiting for responses.
POST /data/amend
Same request shape as upload. Use it only to change a status DROP already accepted, for example a 5 that becomes a 3 when new data arrives. Amend files may mix work items from several batches of the same list and may carry any date in the file name. Amending does not restart the deadline. Do not use amend for rejected rows; those were never accepted.
Errors and retries
| Case | Retry? |
|---|---|
202 on download | Yes, after Retry-After |
429 | Yes, after Retry-After |
500 | Yes, later, with backoff |
400, 401, 403, 404, 409 | No; fix the cause first |
| Bad header, wrong type, duplicate name, unreadable file | No; fix the file |
No numeric rate limit is published. Version 1.0.0 of the documentation mentioned a daily maintenance window from 1:00 to 3:00 a.m. Pacific; later versions do not, but scheduling jobs outside those hours costs nothing.
Webhooks
Webhooks are optional and set up by the broker in the portal's notification settings, which also show the signing secret. Version 1.3.0 sends these events in the X-Webhook-Event-Type header:
drp.list.download.ready: a download is readydrp.upload.receivedanddrp.upload.processed: check the processed result for rejected rowsdrp.amendment.receivedanddrp.amendment.processeddrp.batch.completed: nothing outstanding in the batch
The body is a short message with no batch details. Verify every delivery: the signature is the hex HMAC-SHA256 of the timestamp header, a dot and the raw body, sent as sha256=<hex>. The timestamp is ISO 8601 with seven fractional digits, for example 2026-07-02T18:30:00.0000000Z.
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(rawBody, headers, secret) {
const ts = headers["x-webhook-timestamp"];
const sent = (headers["x-webhook-signature"] ?? "").replace(/^sha256=/, "");
const want = createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
const fresh = Math.abs(Date.now() - Date.parse(ts)) < 5 * 60_000;
return fresh && sent.length === want.length &&
timingSafeEqual(Buffer.from(sent), Buffer.from(want));
}Reply with a 2xx quickly (204 is fine) and do the work afterwards. Deliveries can repeat, so deduplicate on X-Webhook-Event-Id. Older documentation used event names without the drp. prefix, and one example in the current guide still does; accept both.
The sandbox
The sandbox runs at the /sandbox prefix with synthetic data and its own key, issued from the sandbox area of a DROP account. CalPrivacy recommends testing there first and provides a synthetic dataset and a standardization and hashing tool inside the account. Because the sandbox sits inside a broker's account, a developer without one has no published route to it. You can still build and test almost everything offline: the OpenAPI file and the published test vectors in DROP hashing and standardization cover the hashing, parsing and file building.
When the API fails
If your automated connection fails through no fault of your own, the current regulations ask you to notify CalPrivacy in writing within 45 days of your last access and to download manually in the meantime (11 CCR § 7612(b)(1)). Deadlines keep running. Proposed rules from November 2026 would shorten the notice to three business days. Build the manual path into your runbook before you need it.
CalDrop Compliance handles polling, retries, upload batching, webhook verification and the evidence log for each call. How automatic cycles work.
Questions
Is the DROP API required?
No. CalPrivacy says integration via API is not required. Brokers can download batches and upload status files in the DROP portal, with the same formats and deadlines.
How do I authenticate to the DROP API?
Send your API key in the X-API-KEY header over TLS. Keys are issued in your DROP account, scoped to the lists you selected, and do not expire. Issuing a new key deactivates the old ones.
What does a 409 from GET /data/download mean?
Your current batch still has outstanding work items. DROP will not build a new batch, or serve the old one again, until the open batch is complete.
How many files can I upload to DROP at once?
Up to 10 files and 100 MB per request, and up to 100 files per batch across all upload requests.
How are DROP webhooks signed?
With HMAC-SHA256 over the X-Webhook-Timestamp value, a dot and the raw body, encoded as hex and sent as sha256=<hex> in X-Webhook-Signature. Reject stale timestamps and deduplicate on X-Webhook-Event-Id.
Can I use the DROP sandbox without a DROP account?
No published route exists. Sandbox keys are issued inside a DROP account. You can build against the OpenAPI file and test vectors without one.
Related
- DROP API or manual upload
- DROP hashing and standardization
- How to process DROP requests
- Automatic cycles in CalDrop Compliance
Sources
- CalPrivacy: DROP API operations
- CalPrivacy: DROP operations and API documentation
- CalPrivacy: DROP technical reference (version history)
- CalPrivacy: Processing DROP requests
- DROP regulations, 11 CCR §§ 7600–7622 (PDF)
- CalPrivacy: DROP audits (proposed regulations)
Written by the CalDrop Compliance team at Preptics LLC and last reviewed 22 November 2026. This guide explains the rules; it is not legal advice. CalDrop Compliance is an independent product of Preptics LLC. It is not affiliated with, endorsed by or operated by the State of California or the California Privacy Protection Agency (CalPrivacy).
