What specific metadata fields are required by the CyberTipline API for ESP submissions?
Executive summary
The CyberTipline Reporting API expects ESPs to submit a structured XML report containing an incident (the initial report) and associated file metadata; key metadata elements called out in NCMEC’s documentation include file hashes, IP addresses, device identifiers and other file-associated metadata [1] [2]. The API is XML-schema driven and the exact root elements and required fields are defined in that schema, which implementers must consult to know which fields are mandatory versus optional [3] [1].
1. The schema-first reality: reports are XML documents and the schema defines required fields
The CyberTipline and related Hash Sharing services require submissions to conform to an XML web‑service schema — entries and the overall submission are a single XML document that must match the web service schema provided by NCMEC, and that schema is the authoritative source for which elements are required versus optional [3] [1]; third‑party wrappers and client libraries likewise rely on that schema to build the “initial report” XML payload and the separate file metadata XML payload [2].
2. Core metadata items explicitly referenced in NCMEC documentation
NCMEC’s reporting documentation explicitly references certain metadata items that ESPs are expected to include when describing reported media: a categorization value from an ESP-designated scale, the original binary hash value of the file at upload, an IP address associated with the file, an identifier for a device associated with the file, and generally “metadata associated with the file” — these elements are repeatedly cited in the API documentation as parts of the file metadata structure [1].
3. Two-part submission model: incident report + file metadata
Implementations submit two primary XML data types to NCMEC: the initial incident report (incident summary, reporter contact, victim/subject descriptors) and attached file metadata records that describe media items; client libraries and guides note that the initial report and file metadata are separate XML pieces attached to the submission and that attached files can carry optional metadata XML [2] [1].
4. Fields that often show up in practice and integrations
Engineering integrations and product writeups show practical fields that platforms populate automatically: company contact information and reporter identity are often pre‑filled, and enrichment endpoints commonly return personOrUserReported, ipCaptureEvent and associatedAccount sections to populate the CyberTipline XML; this reflects common, practical metadata objects that integrators map into the schema but does not replace the schema’s definitive required/optional rules [4] [5].
5. Quality, variability and legal context that affect what is sent
Although U.S. ESPs are legally required to report apparent child sexual abuse material to NCMEC, there is no statutory checklist that prescribes every metadata field platforms must always include, and NCMEC materials and industry reports emphasize variability in the volume and content of reports — meaning some metadata fields are routinely supplied (hashes, IPs, device IDs), while other contextual fields may be omitted depending on platform retention and workflows [6] [7] [8].
6. Practical takeaway and limits of public reporting
The practical takeaway is that the CyberTipline API demands an XML payload conforming to NCMEC’s schema and calls out specific file metadata elements — file binary hash, IP address, device ID, categorization and other file metadata — but the published snippets in these sources do not provide a complete, field‑by‑field “required” checklist in prose; implementers must consult the full CyberTipline Reporting API schema and Hash Sharing schema to determine which elements are technically mandatory for their submission type [1] [3] [2].