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:

sequence diagram 1

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

sequence diagram 2

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

sequence diagram 3

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

sequence diagram 4

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

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
<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 lease one email address is required 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

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

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.

<report>

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

<incidentSummary>1

General incident information.

<internetDetails>0+

Details of an incident being reported.

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

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

<intendedRecipient>0+

An intended recipient involved in the incident.

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

<emailIncident>

Details for an incident that occurred over email.

<newsgroupIncident>

Details for an incident that occurred in a newsgroup.

<chatImIncident>

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

<onlineGamingIncident>

Details for an incident that occurred during an online game.

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

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

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

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.

<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 <person>
<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 <person>
<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>

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

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

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

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

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

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

<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

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.

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

<industryClassification>0|1

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

  • A1

  • A2

  • B1

  • B2

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

<ipCaptureEvent>0|1

An IP address associated with the file.

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

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

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