CyberTipline Reporting API Technical Documentation

1. Overview

There are two ways for companies to submit reports of apparent child sexual exploitation to NCMEC: they can submit a report using a web form or using this web service API, which allows a more automated reporting experience.

While ESPs have a statutory duty to report apparent child pornography to NCMEC’s CyberTipline (see 18 U.S.C. § 2258A), the reporting of data via the web service, other than the incident type and date/time of incident, is voluntary and undertaken at the ESPs' initiative.

2. Access

For production reporting, the API base URI is https://report.cybertip.org/ispws.
For testing, NCMEC provides a testing environment with base URI https://exttest.cybertip.org/ispws.

This documentation uses https://{applicationRoot} as a representative base URI, which should be replaced with the appropriate production or testing environment URI from above.

All CyberTipline Reporting API endpoints use either GET or POST requests. Endpoints are only accessible via HTTPS and authentication is required. A username and password must be requested from and supplied by NCMEC.

Credentials appearing in this document are for the purpose of example only. You will not be able to use them to authenticate in either the testing or production environments.

3. Endpoints

NCMEC’s Cybertip Reporting API is RESTful and provides the endpoints listed below, relative to one of the base URIs indicated above. For example, to submit a report, a reporter would construct a POST request to the URI https://{applicationRoot}/submit. A detailed report submission example is provided in a later section.

GET/status: Verify that the client can connect to and authenticate with the server.
GET/xsd: Download the latest XML schema definition.
POST/submit: Open a report submission. This is the first endpoint used to initiate the submission of a report. Requests to this endpoint require a body containing a single XML document conforming to the report schema. A response from the server will indicate whether the report was accepted and, if so, the ID assigned to the report. Only one XML document may be submitted per request.
POST/upload: Upload a file to a report. A successful request to begin a report submission must have been made prior to a request to this endpoint. Requests to this endpoint require the report ID to which the uploaded file is to be associated. A response from the server will indicate whether the file upload was successful and, if so, the ID assigned to the file. File uploads are optional and may be made as many times as necessary for the report. There is no limit to the size of uploaded files.
POST/fileinfo: Supply additional details for an uploaded file. A successful file upload must have been made prior to a request to this endpoint. Requests to this endpoint require a single XML document containing the report ID and file ID to which the file details are to be associated. A response from the server will indicate whether the file details submission was successful. File details submissions are optional and may be made once per uploaded file.
POST/finish: Finish a report submission. A report must be finished after all report contents have been uploaded for successful submission. A response from the server will indicate whether the request to finish the report was successful and, if so, the report ID and a list of file IDs associated with the report. Once a report is finished, additional files or file details cannot be added and the report cannot be cancelled. If a report is not finished by the reporter, the report is automatically deleted by NCMEC 24 hours after the date the report was opened or 1 hour after the last modification (file upload or file details submission), whichever is later.
POST/retract: Cancel a report submission. A report may be cancelled by a reporter before the report has been finished or it has been automatically cancelled by NCMEC after timing out. A response from the server will indicate whether the request to cancel the report was successful.

4. XML Root Elements

Below are the root elements defined by the CyberTipline Reporting API schema.

<report>: The root element used to submit a report.
<fileDetails>: The root element used to upload additional details about an uploaded file.
<reportResponse>: The root element of responses to /submit, /upload, /fileinfo, and /retract requests.
<reportDoneResponse>: The root element of the response to a /finish request.

5. Example Report Transactions

Below are example sequence diagrams for various report transactions. Client requests are indicated with a solid line from the left and server responses are indicated with a dotted line from the right. All requests below use POST.

In the simplest transaction, the report contains no files:

In this transaction, the report contains only a single file:

In this transaction, the report contains one file with details and another file without details:

In this transaction, the reporter retracts the report after uploading a file:

6. Example (using curl)

To illustrate how a report is submitted, included is an example using curl. Executables and documentation for curl are available at https://curl.se. This example shows how to open a report, upload a file, submit file details about that file, and finish or cancel the report. For this illustration, the following base URI and example credentials will be used. Note that the username and password below are not valid credentials; you can use your NCMEC-provided credentials to follow along with this example.

The example base URI is the test environment: https://exttest.cybertip.org/ispws
The example username and password supplied by NCMEC is usr123 and pswd123

The credentials used in this section are for illustration only.
You must use your credentials provided by NCMEC.

6.1. Open the Report

The report is submitted as an XML document with <report> as the root element. This is the first request made for a new report submission, which "opens" the report.

Below is an example of a simple report document. Assume this XML file is located on the file system at /home/me/report.xml.

/home/me/report.xml

<?xml version="1.0" encoding="UTF-8"?>
<report xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://report.cybertip.org/ispws/xsd">
    <incidentSummary>
        <incidentType>Child Pornography (possession, manufacture, and distribution)</incidentType>
        <reportAnnotations>
            <sextortion />
            <csamSolicitation />
            <minorToMinorInteraction />
            <spam />
        </reportAnnotations>
        <incidentDateTime>2012-10-15T08:00:00-07:00</incidentDateTime>
    </incidentSummary>
    <internetDetails>
        <webPageIncident>
            <url>http://badsite.com/baduri.html</url>
        </webPageIncident>
    </internetDetails>
    <reporter>
        <reportingPerson>
            <firstName>John</firstName>
            <lastName>Smith</lastName>
            <email>jsmith@example.com</email>
        </reportingPerson>
    </reporter>
</report>

The following curl command can be used to submit the report XML to the CyberTipline Reporting API.

curl --user 'usr123:pswd123' \
     --header 'Content-Type: text/xml; charset=utf-8' \
     --data @/home/me/report.xml \
     https://exttest.cybertip.org/ispws/submit

Note that the UTF-8 character set is specified to ensure correct transmission of non-ASCII characters.

The server’s response will indicate whether the report submission was successful and, if so, provide the report ID assigned to the report. The report ID will be used to submit files and file details, as well as to cancel or finish the report.

Submit Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportResponse>
    <responseCode>0</responseCode> (1)
    <responseDescription>Success</responseDescription>
    <reportId>4564654</reportId> (2)
</reportResponse>

1	Response code `0` indicates successful report submission
2	Report ID assigned to the submitted report

6.2. Upload a File

A request to upload a file requires the following parameters.

`id`	The report ID to which the uploaded file should be associated
`file`	The actual file being uploaded

Assume a file to be uploaded to the report opened in the prior example is located on the file system at /home/me/file.jpg. The following curl command can be used to upload the file to the report.

curl --user 'usr123:pswd123' \
     --form id=4564654 \
     --form file=@/home/me/file.jpg \
     https://exttest.cybertip.org/ispws/upload

The server’s response will indicate whether the file upload was successful and, if so, the file ID and MD5 hash of the uploaded file. The file ID is used to submit file details for the uploaded file. The MD5 hash can be used to verify that the complete file was received.

File Upload Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportResponse>
    <responseCode>0</responseCode> (1)
    <responseDescription>Success</responseDescription>
    <reportId>4564654</reportId> (2)
    <fileId>b0754af766b426f2928a02c651ed4b99</fileId> (3)
    <hash>fafa5efeaf3cbe3b23b2748d13e629a1</hash> (4)
</reportResponse>

1	Response code `0` indicates successful file upload
2	Report ID for the report
3	File ID assigned to the uploaded file
4	MD5 hash of the uploaded file

6.3. Submit File Details

Optional file details are submitted for an uploaded file as an XML document with <fileDetails> as the root element.

Below is an example of a file details document for the file uploaded in the prior example. Assume the file is located on the file system at /home/me/file-details.xml.

/home/me/file-details.xml

<?xml version="1.0" encoding="UTF-8"?>
<fileDetails xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:noNamespaceSchemaLocation="https://report.cybertip.org/ispws/xsd">
    <reportId>4564654</reportId> (1)
    <fileId>b0754af766b426f2928a02c651ed4b99</fileId> (2)
    <originalFileName>mypic.jpg</originalFileName>
    <ipCaptureEvent>
        <ipAddress>63.116.246.17</ipAddress>
        <eventName>Upload</eventName>
        <dateTime>2011-10-31T12:00:00Z</dateTime>
    </ipCaptureEvent>
    <additionalInfo>File was originally posted with 6 others</additionalInfo>
</fileDetails>

1	Report ID assigned to the submitted report from report submission response
2	File ID assigned to the uploaded file from file upload response

The following curl command can be used to submit the file details XML to the CyberTipline Reporting API. Note that the UTF-8 character set is specified to ensure correct transmission of non-ASCII characters.

curl --user 'usr123:pswd123' \
     --header 'Content-Type: text/xml; charset=utf-8' \
     --data @/home/me/file-details.xml \
     https://exttest.cybertip.org/ispws/fileinfo

The server’s response will indicate whether the file details submission was successful.

File Details Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportResponse>
    <responseCode>0</responseCode> (1)
    <responseDescription>Success</responseDescription>
    <reportId>4564654</reportId>
</reportResponse>

1	Response code `0` indicates successful file details submission

6.4. Finish the Report

Once all the files and file details are uploaded, the report must be finished to complete submission. A request to finish a report requires the parameter id, the report ID of the report to finish.

The following curl command can be used to finish the report.

curl --user 'usr123:pswd123' \
     --form id=4564654 \
     https://exttest.cybertip.org/ispws/finish

The server’s response will indicate whether the finish was successful, the report ID, and the list of file IDs for the report.

The XML notification of receipt of a report made to NCMEC’s CyberTipline under 18 U.S.C. § 2258A shall serve as the ESP notification pursuant to 18 U.S.C. § 2258A(h)(1)).

Finish Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportDoneResponse>
    <responseCode>0</responseCode> (1)
    <reportId>4564654</reportId> (2)
    <files>
        <fileId>b0754af766b426f2928a02c651ed4b99</fileId> (3)
    </files>
</reportDoneResponse>

1	Response code `0` indicates successful report finish
2	Report ID of the finished report
3	File IDs of the finished report

6.5. Cancel the Report

Before the report is finished, it may be cancelled if the reporter encounters an error during submission. A request to cancel a report requires the parameter id, the report ID of the report to cancel.

The following curl command can be used to cancel the report.

curl --user 'usr123:pswd123' \
     --form id=4564654 \
     https://exttest.cybertip.org/ispws/retract

The server’s response will indicate whether the cancel was successful and the report ID of the cancelled report.

Cancel Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportResponse>
    <responseCode>0</responseCode> (1)
    <responseDescription>Success</responseDescription>
    <reportId>4564654</reportId> (2)
</reportResponse>

1	Response code `0` indicates successful report cancellation
2	Report ID of the cancelled report

7. Troubleshooting

If you encounter problems using this web service, the following tips may help you with troubleshooting.

7.1. Status Endpoint

Verify that you can access the server and that your credentials are correct by accessing the status endpoint from a web browser. For production, navigate to https://report.cybertip.org/ispws/status. For testing, navigate to https://exttest.cybertip.org/ispws/status. Your browser will ask you to provide credentials. Verify that you receive the following response, where {username} represents your username and {ip address} represents your IP address.

Status Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportResponse>
    <responseCode>0</responseCode>
    <responseDescription>Remote User : {username}, Remote Ip : {ip address}</responseDescription>
</reportResponse>

If you receive the above response, you know that you can access the server and authenticate successfully. If you cannot, contact NCMEC to verify your credentials. Verify that you do not have any firewall rules that prevent you from connecting to NCMEC’s servers.

7.2. XML Validation

Verify that your XML is syntactically and structurally correct by validating it against the latest schema, available at https://report.cybertip.org/ispws/xsd.

7.3. Timestamp Format

Make sure your date/time values are specified according to the ISO 8601 standard. ISO 8601 timestamps must have a time zone specified in the format +/-hh:mm or Z for UTC.

7.4. curl

Try to submit a report to the testing environment at https://exttest.cybertip.org/ispws using curl as in example above. The example has been tested on both Linux and Windows.

7.5. Request IDs

If you are receiving error responses from the server and need assistance from NCMEC, please also include in your message the value of the Request-ID header provided in the server response. This will help NCMEC locate your API request to provide timelier and more useful troubleshooting assistance.

Appendix A: Common Types

Below is a description of common element types specified by the reporting schema.

Listed with each element or attribute is an indicator of the element’s or attribute’s cardinality.

Cardinality	Description
1	exactly one element is required
1+	one or more elements is required
0\|1	element is optional but at most 1 element may be supplied
0+	element is optional but there is no limit on the number that may be supplied

Cardinality

Description

exactly one element is required

one or more elements is required

0|1

element is optional but at most 1 element may be supplied

element is optional but there is no limit on the number that may be supplied

In the event that a reporter chooses to voluntarily provide information for an element, certain parent, child, or sibling elements may also be required. Please refer to the XSD for the authoritative schema definition.

<ipCaptureEvent>

A capture of an IP address. For example, the IP address of the computer a user used to upload a child pornography picture and the time the upload happened.

<ipAddress>1

The IP address from which the event occurred.

type string

validation must be a valid IPv4, IPv6, or IPv4-mapped IPv6 address

validation must not be blank if <ipCaptureEvent> supplied

<eventName>0|1

The type of event from which the IP address was captured. One of:

Login
Registration
Purchase
Upload
Other
Unknown

type string

<dateTime>0|1

The date and time the IP address was captured.

type ISO 8601 date and time

validation must be in the past

<possibleProxy>0|1

Whether the reporter has reason to believe this IP address is a proxy.

type boolean

<port>0|1

The port number of the IP address.

type int

validation must be between 1 and 65535

<deviceId>

A capture of a device ID. Similar to <ipCaptureEvent>. Used to report information such as ICCID or IMEI numbers associated with an event.

<idType>1

The type of device ID captured (e.g., IMEI, ICCID, SSID).

type string

validation must not be blank if <deviceId> supplied

validation max length is 255 characters

<idValue>1

The device ID from which the event occurred.

type string

validation must not be blank if <deviceId> supplied

validation max length is 2083 characters

<eventName>0|1

The type of event from which the device ID was captured. One of:

Login
Registration
Purchase
Upload
Other
Unknown

type string

<dateTime>0|1

The date and time the device ID was captured.

type ISO 8601 date and time

validation must be in the past

<address>

A physical street address.

<address>0|1

Street address.

type string

validation max length is 255 characters

<city>0|1

City.

type string

validation max length is 100 characters

<zipCode>0|1

Zip or postal code.

type string

validation max length is 20 characters

<state>0|1

US state or territory postal abbreviation.

type string

validation must be a valid US state or territory postal abbreviation

<nonUsaState>0|1

State, province, or region if not in the United States.

type string

validation max length is 100 characters

<country>0|1

ISO 3166-1 alpha-2 two-character country code.

type string

validation must be a valid ISO 3166-1 alpha-2 country code

type0|1attribute

Type of address. One of:

Home
Business
Billing
Shipping
Technical

type string

<phone>

A phone number.

type string

validation max length is 50 characters

validation if countryCallingCode supplied, must not start with country calling code

type0|1attribute

Type of phone number. One of:

Mobile
Home
Business
Work
Fax
Internet

type string

verified0|1attribute

Whether the reporter has verified the phone number.

type boolean

validation must be true when verificationDate is supplied

verificationDate0|1attribute

The date and time that the reporter last verified the phone number.

type string

validation must be in the past

countryCallingCode0|1attribute

The country calling code for the phone number.

type string

validation must conform to the regular expression \+[0-9]{1,3}

extension0|1attribute

The extension for the phone number.

type string

validation must conform to the regular expression [0-9]+

validation max length is 10 characters

<email>

An email address.

type string

validation must be a well-formed email address

validation max length is 255 characters

type0|1attribute

Type of email address. One of:

Home
Work
Business

type string

verified0|1attribute

Whether the reporter has verified the email address.

type boolean

validation must be true when verificationDate is supplied

verificationDate0|1attribute

The date and time that the reporter last verified the email address.

type string

validation must be in the past

<estimatedLocation>

An estimated location.

<city>0|1: The city of the estimated location.

type string

validation max length is 255 characters
<region>0|1: The region of the estimated location.

type string

validation max length is 255 characters

validation must be a valid US state or territory postal abbreviation if supplied and <countryCode> is "US"

validation must be not be blank if <city> is supplied and <countryCode> is "US"
<countryCode>0|1: ISO 3166-1 alpha-2 two-character country code of the estimated location.

type string

validation must be not be blank if <estimatedLocation> is supplied

validation must be a valid ISO 3166-1 alpha-2 country code
verified0|1attribute: Whether the reporter has verified the estimated location.

type boolean
timestamp0|1attribute: The date and time the reporter made the location estimation.

type ISO 8601 date and time

validation must be in the past

<person>

A real world person.

<firstName>0|1: The person’s first name.

type string

validation max length is 100 characters
<lastName>0|1: The person’s last name.

type string

validation max length is 100 characters
<phone>0+: A phone number.

type <phone>
<email>0+: An email address. At least one email address is required when used as part of the <reportingPerson> element.

type <email>
<address>0+: A physical address.

type <address>
<age>0|1: The person’s approximate age.

type int

validation must be between 0 and 150
<dateOfBirth>0|1: The person’s date of birth.

type ISO 8601 date

validation must be in the past

<contactPerson>

A real world person with information pertinent for professional contact.

<firstName>0|1: The person’s first name.

type string

validation max length is 100 characters
<lastName>0|1: The person’s last name.

type string

validation max length is 100 characters
<phone>0+: A phone number.

type <phone>
<email>0+: An email address.

type <email>
<address>0+: A physical address.

type <address>

Appendix B: Report Details Types

Below is a description of report details element types specified by the reporting schema.

Listed with each element or attribute is an indicator of the element’s or attribute’s cardinality.

Cardinality	Description
1	exactly one element is required
1+	one or more elements is required
0\|1	element is optional but at most 1 element may be supplied
0+	element is optional but there is no limit on the number that may be supplied

Cardinality

Description

exactly one element is required

one or more elements is required

0|1

element is optional but at most 1 element may be supplied

element is optional but there is no limit on the number that may be supplied

<report>

The main top-level tag to define an incident report.

<batchedReport>0|1

Indicator that the report concerns multiple reported persons or users related to the reported incident.

reason1attribute

The reason for grouping multiple reported persons or users into a single batched report. Values include:

VIRAL_POTENTIAL_MEME - The batched report concerns a file that is being shared/posted out of mimicry or other seemingly non-malicious intent or the file is circulating rapidly from one user to another. See Viral/Potential Meme Batched Reports for implications on report validation constraints.

type string

<incidentSummary>1

General incident information.

type <incidentSummary>

<internetDetails>0+

Details of an incident being reported.

type <internetDetails>

<lawEnforcement>0|1

Law enforcement contact information if the incident information has already been reported to law enforcement or if the request originated from law enforcement.

type <lawEnforcement>

<reporter>1

Information related to the person or company reporting the incident.

type <reporter>

<personOrUserReported>0|1

The reported user or person involved in the incident. This person will be displayed as the suspect.

type <personOrUserReported>

<intendedRecipient>0+

An intended recipient involved in the incident.

type <intendedRecipient>

<victim>0+

A child victim involved in the incident.

type <victim>

<additionalInfo>0|1

Additional notes on this incident not covered by any other section.

type string

B.1. Incident Summary

<incidentSummary>

General incident information.

<incidentType>1

The type of incident being reported. Values include:

Child Pornography (possession, manufacture, and distribution)
Child Sex Trafficking
Child Sex Tourism
Child Sexual Molestation
Misleading Domain Name
Misleading Words or Digital Images on the Internet
Online Enticement of Children for Sexual Acts
Unsolicited Obscene Material Sent to a Child

type string

<escalateToHighPriority>0|1

A reason for a higher level of urgency, e.g. immediate risk to child. Supplying a value will escalate the report.

type string

validation must not be blank if <escalateToHighPriority> supplied

validation max length is 3000 characters

<reportAnnotations>0|1

Tags to describe the report.

type <reportAnnotations>

<incidentDateTime>1

The date, time, and time zone of the reported incident.

type ISO 8601 date and time

validation must be in the past

<incidentDateTimeDescription>0|1

Additional information related to the <incidentDateTime>.

type string

validation max length is 3000 characters

B.1.1. Report Annotations

<reportAnnotations>

Tags to describe the report.

<sextortion>0|1: The report is associated with sextortion.
<csamSolicitation>0|1: The report is associated with solicitation of child sexual assault material (CSAM).
<minorToMinorInteraction>0|1: The report is associated with an interaction between minors.
<spam>0|1: The report is associated with spam.

B.2. Internet Details

<internetDetails>

Details of an incident being reported. Each supplied <internetDetails> element must have exactly one of the following:

<webPageIncident>: Details for an incident that occurred on a web page.

type <webPageIncident>
<emailIncident>: Details for an incident that occurred over email.

type <emailIncident>
<newsgroupIncident>: Details for an incident that occurred in a newsgroup.

type <newsgroupIncident>
<chatImIncident>: Details for an incident that occurred over IM or during a chat session.

type <chatImIncident>
<onlineGamingIncident>: Details for an incident that occurred during an online game.

type <onlineGamingIncident>
<cellPhoneIncident>: Details for an incident that occurred when the primary method of communication between the child and/or reported person or user was through a cell phone. This can include phone conversations, text messages, or images sent via a cell phone.

type <cellPhoneIncident>
<nonInternetIncident>: Details for an incident that does not involve an online or computer component or a cell phone (e.g., face-to-face contact, potentially illegal hard copy or printed materials).

type <nonInternetIncident>
<peer2peerIncident>: Details for an incident that occurred via a peer-to-peer (also known as P2P) decentralized network that allows users to share files through a direct connection.

type <peer2peerIncident>

B.2.1. Web Page Incident

<webPageIncident>

Details for an incident that occurred on a web page.

<url>0+: An actual URL where the reported incident occurred.

type string

validation must be a valid URL

validation max length is 2083 characters
<additionalInfo>0|1: Additional information related to the web page event.

type string
thirdPartyHostedContent0|1attribute: Whether the reported URL is hosted on another company’s server and the reporter has no further information on this incident and is providing it to NCMEC for informational purposes.

type boolean

B.2.2. Email Incident

<emailIncident>

Details for an incident that occurred over email.

<emailAddress>0+: An email address associated with the incident.

type <email>

validation must also be supplied as a <personOrUserReported> email address, <intendedRecipient> email address, or a <victim> email address
<content>0|1: The headers, subject, and content of the communication.

type string
<additionalInfo>0|1: Additional information about the email incident not covered by any other section.

type string

B.2.3. Newsgroup Incident

<newsgroupIncident>

Details for an incident that occurred in a newsgroup.

<name>0|1: The newsgroup name.

type string

validation max length is 255 characters
<emailAddress>0+: An email address associated with the incident.

type <email>

validation must also be supplied as a <personOrUserReported> email address, <intendedRecipient email address, or a <victim> email address
<content>0|1: The headers, subject, and content of the communication.

type string
<additionalInfo>0|1: Additional information about the newsgroup incident not covered by any other section.

type string

B.2.4. Chat/IM Incident

<chatImIncident>

Details for an incident that occurred over IM or during a chat session.

<chatClient>0|1: The chat or instant messenger program used.

type string

validation max length is 255 characters
<chatRoomName>0|1: The name of the chat room.

type string

validation max length is 255 characters
<content>0|1: The content of the chat.

type string
<additionalInfo>0|1: Additional information about the chat or instant messaging incident not covered by any other section.

type string

B.2.5. Online Gaming Incident

<onlineGamingIncident>

Details for an incident that occurred during an online game.

<gameName>0|1: The name of the game in which the incident occurred.

type string

validation max length is 255 characters
<console>0|1: The name of the gaming console used in the incident.

type string

validation max length is 255 characters
<content>0|1: The content of the message/chat that occurred during the game.

type string
<additionalInfo>0|1: Additional information about the online gaming incident not covered by any other section.

type string

B.2.6. Cellphone Incident

<cellPhoneIncident>

Details for an incident that occurred when the primary method of communication between the child and/or reported person or user was through a cell phone. This can include phone conversations, text messages, or images sent via a cell phone.

<phoneNumber>0|1: The cell phone number associated with the incident.

type <phone>
<latitude>0|1: The latitude associated with the incident.

type double
<longitude>0|1: The longitude associated with the incident.

type double
<additionalInfo>0|1: Additional information about the cell phone incident not covered by any other section.

type string

B.2.7. Non-Internet Incident

<nonInternetIncident>

Details for an incident that does not involve an online or computer component or a cell phone (e.g., face-to-face contact, potentially illegal hard copy or printed materials).

<locationName>0|1: The location associated with the incident.

type string

validation max length is 255 characters
<incidentAddress>0+: The address of the incident.

type <address>
<additionalInfo>0|1: Additional information about the incident not covered by any other section.

type string

B.2.8. Peer-to-Peer Incident

<peer2peerIncident>

Details for an incident that occurred via a peer-to-peer (also known as P2P) decentralized network that allows users to share files through a direct connection.

<client>0|1: The peer-to-peer client associated with the incident.

type string

validation max length is 255 characters
<ipCaptureEvent>0+: An IP address used by the person or user reported.

type <ipCaptureEvent>
<fileNames>0|1: The name of the file(s) associated with the incident.

type string
<additionalInfo>0|1: Additional information about the peer-to-peer incident not covered by any other section.

type string

B.3. Law Enforcement

<lawEnforcement>

Law enforcement contact information if the incident information has already been reported to law enforcement or if the request originated from law enforcement.

<agencyName>1

The law enforcement agency name.

type string

validation max length is 255 characters

<caseNumber>0|1

The law enforcement agency case number.

type string

validation max length is 100 characters

<officerContact>0|1

Information about the investigator or officer assigned to the case.

type <contactPerson>

<reportedToLe>0|1

Whether the incident was reported to law enforcement by the reporter.

type boolean

<servedLegalProcessDomestic>0|1

Whether domestic law enforcement has served legal process about this person/user or reported incident.

type boolean

<servedLegalProcessInternational>0|1

Whether international law enforcement has served legal process about this person/user or reported incident.

type boolean

fleaCountry0|1attribute: The country associated with this report from which legal process was received.

type string

validation must be a valid ISO 3166-1 alpha-2 country code

B.4. Reporter

<reporter>

Information related to the person or company reporting the incident.

<reportingPerson>1: Information about the person reporting the incident. The email element of this element is required, however the XML notification of receipt of a report made to NCMEC’s CyberTipline under 18 U.S.C. § 2258A shall serve as the ESP notification pursuant to 18 U.S.C. § 2258A(h)(1).

type <person>

validation <email> is required
<contactPerson>0|1: Information about a person who should be contacted by law enforcement regarding the report other than the person submitting the report.

type <contactPerson>
<companyTemplate>0|1: Language (not specific to the reported incident) that the reporting company wants included in the CyberTipline report, e.g., basic company information, how legal process should be served, length of data retention, 24-hour emergency phone numbers.

type string
<termsOfService>0|1: Terms of Service (TOS) relevant to the incident being reported.

type string
<legalUrl>0|1: A URL for a web page with further information.

type string

validation must be a valid URL

validation max length is 2083 characters

B.5. Reported Person

<personOrUserReported>

A reported user or person involved in the incident. This person will be displayed as the suspect.

<personOrUserReportedPerson>0|1: Information about the reported person or user involved in the incident.

type <person>
<vehicleDescription>0|1: Description of the vehicle of the reported person.

type string

validation max length is 300 characters
<espIdentifier>0|1: The unique ID of the reported person or user in the reporter’s system.

type string

validation max length is 255 characters
<espService>0|1: The name of the reporter’s product or service that was used by the reported person or user during the incident.

type string

validation max length is 100 characters
<screenName>0|1: The screen/user name of the reported person or user.

type string

validation max length is 255 characters
<displayName>0+: A display name, other than a screen name or a username, for the reported person or user.

type string

validation max length is 255 characters
<profileUrl>0+: An identifying URL for the reported person or user.

type string

validation must be a valid URL

validation max length is 2083 characters
<ipCaptureEvent>0+: An IP address used by the reported person or user.

type <ipCaptureEvent>
<deviceId>0+: An ID for a device used by the reported person or user.

type <deviceId>
<thirdPartyUserReported>0|1: Whether the reported person or user is using another company’s service and the reporting company has no further information about this person or user.

type boolean
<priorCTReports>0+: A report ID for a prior CyberTipline report on this reported person or user.

type long

validation must be a valid CyberTipline report ID
<groupIdentifier>0|1: Unique group identifiers (e.g., group name, group ID) if the reporter believes the reported person or user is engaged in an online group related to child sexual exploitation.

type string

validation max length is 255 characters
<estimatedLocation>0|1: The reporter’s estimated location for the reported person or user.

type <estimatedLocation>
<additionalInfo>0|1: Additional information about this reported person or user not covered by any other section.

type string

B.6. Intended Recipient

<intendedRecipient>

The intended recipient involved in the incident.

<intendedRecipientPerson>0|1

Information about the intended recipient in the incident.

type <person>

<espIdentifier>0|1

The unique ID of the intended recipient in the reporter’s system.

type string

validation max length is 255 characters

<espService>0|1

The name of the reporter’s product or service that was used by the intended recipient during the incident.

type string

validation max length is 100 characters

<screenName>0|1

The screen name of the intended recipient.

type string

validation max length is 255 characters

<displayName>0+

A display name, other than a screen name or a username, for the intended recipient.

type string

validation max length is 255 characters

<profileUrl>0+

An identifying URL for the intended recipient.

type string

validation must be a valid URL

validation max length is 2083 characters

<ipCaptureEvent>0+

An IP address used by the intended recipient.

type <ipCaptureEvent>

<deviceId>0+

An ID for a device used by the intended recipient.

type <deviceId>

<priorCTReports>0+

A report ID for a prior CyberTipline report on this intended recipient.

type long

validation must be a valid CyberTipline report ID

<groupIdentifier>0|1

Unique group identifiers (e.g., group name, group ID) if the reporter believes the intended recipient is engaged in an online group related to child sexual exploitation.

type string

validation max length is 255 characters

<accountTemporarilyDisabled>0|1

Whether the account was temporarily disabled at any point.

type boolean

disabledDate0|1attribute: The date the account was temporarily disabled.

type ISO 8601 date and time

validation must be in the past
reenabledDate0|1attribute: The date the temporarily disabled account was re-enabled.

type ISO 8601 date and time

validation must be after the disabledDate if both are supplied

<accountPermanentlyDisabled>0|1

Whether the account was permanently disabled.

type boolean

disabledDate0|1attribute: The date the account was permanently disabled.

type ISO 8601 date and time

validation must be in the past

<estimatedLocation>0|1

The reporter’s estimated location for the intended recipient.

type <estimatedLocation>

<additionalInfo>0|1

Additional information about this intended recipient not covered by any other section.

type string

B.7. Child Victim

<victim>

A child victim involved in the incident.

<victimPerson>1: Information about the child victim involved in the incident.

type <person>
<espIdentifier>0|1: The unique ID of the child victim in the reporter’s system.

type string

validation max length is 255 characters
<espService>0|1: The name of the reporter’s product or service that was used by the child victim during the incident.

type string

validation max length is 100 characters
<screenName>0|1: The screen name of the child victim.

type string

validation max length is 255 characters
<displayName>0+: A display name, other than a screen name or a username, for the child victim.

type string

validation max length is 255 characters
<profileUrl>0+: An identifying URL for the child victim.

type string

validation must be a valid URL

validation max length is 2083 characters
<ipCaptureEvent>0+: An IP address used by the child victim.

type <ipCaptureEvent>
<deviceId>0+: An ID for a device used by the child victim.

type <deviceId>
<schoolName>0|1: The school name of the child victim.

type string

validation max length is 255 characters
<priorCTReports>0+: A report ID for a prior CyberTipline report on this child victim.

type long

validation must be a valid CyberTipline report ID
<estimatedLocation>0|1: The reporter’s estimated location for the child victim.

type <estimatedLocation>
<additionalInfo>0|1: Additional information about this child victim not covered by any other section.

type string

Appendix C: File Details Types

Below is a description of file details element types specified by the reporting schema.

Listed with each element or attribute is an indicator of the element’s or attribute’s cardinality.

Cardinality	Description
1	exactly one element is required
1+	one or more elements is required
0\|1	element is optional but at most 1 element may be supplied
0+	element is optional but there is no limit on the number that may be supplied

Cardinality

Description

exactly one element is required

one or more elements is required

0|1

element is optional but at most 1 element may be supplied

element is optional but there is no limit on the number that may be supplied

<fileDetails>

Details about a file.

<reportId>1

The report ID to which the details are related.

type long

validation must be a valid CyberTipline report ID

validation reporter must have permission to update the supplied CyberTipline Report

<fileId>1

The file ID to which the details are related.

type string

validation must not be blank

validation must be a valid file ID for the supplied report ID

<originalFileName>0|1

The original filename associated with the file when it was uploaded to the company’s servers by the reported user or person.

type string

validation max length is 2056 characters

<locationOfFile>0|1

The URL where file was originally located.

type string

validation must be a valid URL

validation max length is 2083 characters

<fileViewedByEsp>0|1

Whether the reporting company viewed the entire contents of the file being reported to NCMEC.

type boolean

validation must be "true" when the value of <exifViewedByEsp> is "true"

<exifViewedByEsp>0|1

Whether the reporting company viewed the EXIF for the file being reported to NCMEC.

type boolean

<publiclyAvailable>0|1

Whether the entire contents of the file were publicly accessible to online users.

type boolean

<fileRelevance>0|1

The relevance or relation of the file to the report. Unless specified otherwise, a file is "Reported" by default. One of the following values:

Reported: Content that is the motivation for making the CyberTipline report, according to the chosen incident type. Only "Reported" files may be identified as potential meme or be given an industry classification.
Supplemental Reported: Supplementary content that provides contextual value to the report. A part of the communication containing apparent child pornography, including any data or information regarding the transmission of the communication or any images, data, or other digital files contained in, or attached to, the communication (18 U.S. Code § 2258A (b)(5)).

type string

validation may not be "Supplemental Reported" if a potential meme annotation is supplied

validation may not be "Supplemental Reported" if an <industryClassification> is supplied

<fileAnnotations>0|1

Tags to describe the file.

type <fileAnnotations>

<industryClassification>0|1

A categorization from the ESP-designated categorization scale. One of:

type string

<originalFileHash>0+

The original binary hash value of the file at the time it was uploaded by the reported user or person (prior to any potential modification by the reporter).

type <originalFileHash>

<ipCaptureEvent>0|1

An IP address associated with the file.

type <ipCaptureEvent>

<deviceId>0+

An ID for a device associated with the file.

type <deviceId>

<details>0+

Metadata associated with the file.

type <details>

<additionalInfo>0+

Additional information about this file not covered by any other section.

type string

C.1. File Annotations

<fileAnnotations>

Tags to describe a file.

<animeDrawingVirtualHentai>0|1: The file is depicting anime, drawing, cartoon, virtual or hentai.
<potentialMeme>0|1: The file is being shared/posted out of mimicry or other seemingly non-malicious intent.
<viral>0|1: The file is circulating rapidly from one user to another.
<possibleSelfProduction>0|1: The file contains content that is believed to be self-produced.
<physicalHarm>0|1: The file depicts an intentional act of causing physical injury or trauma to a person.
<violenceGore>0|1: The file depicts graphic violence, including but not limited to acts of brutality or detailed or vivid gruesomeness.
<bestiality>0|1: The file involves an animal.
<liveStreaming>0|1: The file depicts content that was streamed live at the time it was uploaded.
<infant>0|1: The file depicts an infant.
<generativeAi>0|1: The file contains content that is believed to be Generative Artificial Intelligence.

C.2. Original File Hash

<originalFileHash>

An original file hash value.

type string

hashType1attribute: The type of hash (e.g. MD5, SHA1).

type string

validation max length is 64 characters

C.3. Details

<details>

Metadata associated with a file.

<nameValuePair>1+

A metadata entry.

<name>1: The name of the metadata entry.

type string

validation max length is 64 characters
<value>1: The value of the metadata entry.

type string

type0|1attribute

The type of the metadata entry. One of:

EXIF
HASH

type string

Appendix D: Response Types

Below is a description of response element types specified by the reporting schema.

Listed with each element or attribute is an indicator of the element’s or attribute’s cardinality.

Cardinality	Description
1	exactly one element will be supplied
1+	one or more elements will be supplied
0\|1	element is optional but at most 1 element will be supplied
0+	element is optional but there is no limit on the number that may be supplied

Cardinality

Description

exactly one element will be supplied

one or more elements will be supplied

0|1

element is optional but at most 1 element will be supplied

element is optional but there is no limit on the number that may be supplied

Please refer to the XSD for the authoritative schema definition.

D.1. Report Response

<reportResponse>

The root element of the response to a report, file, or file details submittal.

<responseCode>1

The response code returned from the submittal. 0 is success, any non-zero number is an error code. The following is a non-exhaustive list of possible error codes.

0	Success
1000	Server error
1100	Save failed
1110	Upload failed
1111	File upload failed
1210	Resource not found
1300	Update failed
2000	Authentication required
3000	User is not authorized to perform this action
3100	User does not have authorization to make submissions
3300	User does not have authorization to make updates
4000	Invalid request
4100	Validation failed
4110	Malformed XML submittal
4200	Malformed file submittal
5001	Report does not exist
5002	File does not exist
5101	Report already retracted
5102	Report already finished

type int

<responseDescription>1

The description of the response code.

type string

<reportId>1

The report ID to which this response is related.

type long

<fileId>0|1

If a file was successfully uploaded, the file ID for the file.

type string

<hash>0|1

If a file was successfully uploaded, the MD5 hash of the file.

type string

D.2. Report Done Response

<reportDoneResponse>

The final response from the server once the report has been submitted, all files and file details have been uploaded, and the has been finished.

<responseCode>1

The response code returned from the submittal. 0 is success, any non-zero number is an error code. The following is a non-exhaustive list of possible error codes.

0	Success
1000	Server error
1100	Save failed
1110	Upload failed
1111	File upload failed
1210	Resource not found
1300	Update failed
2000	Authentication required
3000	User is not authorized to perform this action
3100	User does not have authorization to make submissions
3300	User does not have authorization to make updates
4000	Invalid request
4100	Validation failed
4110	Malformed XML submittal
4200	Malformed file submittal
5001	Report does not exist
5002	File does not exist
5101	Report already retracted
5102	Report already finished

type int

<reportId>1

The report ID for the finished report.

type long

<files>1

A list of file IDs for files successfully uploaded to the report.

<fileId>0+: A file ID for a file successfully uploaded to the report.

type long

Appendix E: Batched Report Validation

To activate a batched report, add element <batchedReport> under the <report> element. This element must specify a reason attribute indicating the rationale for submitting a batched report.

Elements and attributes in this section are indicated in XPath notation.

E.1. Viral/Potential Meme Batched Reports

The Viral/Potential Meme batched report mode is activated when the reason attribute of the <batchedReport> element is VIRAL_POTENTIAL_MEME.

When the Viral/Potential Meme batched report mode is activated, the following validation rules apply to the main report submission.

Multiple /report/personOrUserReported elements are allowed.
The only elements allowed within a /report/personOrUserReported element are following:
- /report/personOrUserReported/espIdentifier
None of the following elements or their child elements are allowed:
- /report/incidentSummary/escalateToHighPriority
- /report/internetDetails
- /report/lawEnforcement
- /report/intendedRecipient
- /report/victim
- /report/additionalInfo

When the Viral/Potential Meme batched report mode is activated, only 1 uploaded file is allowed. If more than 1 uploaded file is included in the report, the call to complete the report via the /finish endpoint will fail with a validation error (HTTP status 400 and application status 4100). In this situation, the reporter should execute a retraction of the report via the /retract endpoint and resubmit the report according to the validation rules specified in this section. If the report is not retracted by the reporter, it will be automatically retracted by NCMEC after the default abandonment period has passed.

When the Viral/Potential Meme batched report mode is activated, the following validation rules apply to file details submissions.

The file must be annotated as viral and/or potential meme via the /fileDetails/fileAnnotations/viral and/or /fileDetails/fileAnnotations/potentialMeme elements.
The file may optionally be annotated with an industry classification via the /fileDetails/industryClassification element.
The file may not indicate any other annotation; none of the following elements are allowed:
- /fileDetails/fileAnnotations/animeDrawingVirtualHentai
- /fileDetails/fileAnnotations/possibleSelfProduction
- /fileDetails/fileAnnotations/physicalHarm
- /fileDetails/fileAnnotations/violenceGore
- /fileDetails/fileAnnotations/bestiality
- /fileDetails/fileAnnotations/liveStreaming
- /fileDetails/fileAnnotations/infant
- /fileDetails/fileAnnotations/generativeAi
None of the following elements or their child elements are allowed:
- /fileDetails/originalFileName
- /fileDetails/locationOfFile
- /fileDetails/originalFileHash
- /fileDetails/ipCaptureEvent
- /fileDetails/deviceId
- /fileDetails/details
- /fileDetails/additionalInfo
The relevance of the file specified by the /fileDetails/fileRelevance element must be "Reported".