CyberTipline Reporting API

https://report.cybertip.org/ispws/documentation/
Admin
CyberTipline Reporting API is a RESTful web service API that enables electronic service providers to...
Tokens:19,545
Snippets:170
Trust Score:8.9
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Example report XML document (report.xml)

Source: https://report.cybertip.org/ispws/documentation/index.html

Example XML report document with <report> as root element, used to open a new report submission. Includes incident summary, internet details, and reporter information. Assumed to be located at /home/me/report.xml.

```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 />
            <sadisticOnlineExploitation />
            <informational />
            <potentialAggravatingFactors />
            <instrumentalUse />
        </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>
```

--------------------------------

### GET /status

Source: https://report.cybertip.org/ispws/documentation/index.html

Verifies that the client can connect to and authenticate with the server.

```APIDOC
## GET /status

### Description
Verify that the client can connect to and authenticate with the server.

### Method
GET

### Endpoint
https://{applicationRoot}/status

### Parameters
None

### Response
#### Success Response (200)
- **status** (string) - Indicates the connection and authentication status.

#### Response Example
{
  "status": "OK"
}
```

--------------------------------

### File details response XML

Source: https://report.cybertip.org/ispws/documentation/index.html

Example response from the file details submission. Response code 0 indicates successful file details submission.

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

--------------------------------

### GET /xsd

Source: https://report.cybertip.org/ispws/documentation/index.html

Downloads the latest XML schema definition for the report submission format.

```APIDOC
## GET /xsd

### Description
Download the latest XML schema definition.

### Method
GET

### Endpoint
https://{applicationRoot}/xsd

### Parameters
None

### Response
#### Success Response (200)
- **body** (XML) - The latest XML schema definition.

#### Response Example
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">...</xs:schema>
```

--------------------------------

### Submit file details XML document

Source: https://report.cybertip.org/ispws/documentation/index.html

Example XML document for submitting optional file details. The root element is <fileDetails>. It includes the report ID, file ID, original file name, and IP capture event. The file is submitted via curl with the file path /home/me/file-details.xml.

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

--------------------------------

### File upload response XML

Source: https://report.cybertip.org/ispws/documentation/index.html

Example response from the file upload endpoint. Response code 0 indicates success. The file ID is used for submitting file details, and the MD5 hash verifies complete file receipt.

```xml
<?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>
```

--------------------------------

### Finish response XML

Source: https://report.cybertip.org/ispws/documentation/index.html

Example response from the finish report operation. Response code 0 indicates successful report finish. The response includes the report ID and file IDs of the finished report.

```xml
<?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>
```

--------------------------------

### GET /ispws/status

Source: https://report.cybertip.org/ispws/documentation/index.html

Verifies server access and credentials. Returns a response indicating the authenticated username and IP address.

```APIDOC
## [GET] /ispws/status

### Description
Verifies that you can access the server and that your credentials are correct. Returns a response indicating the authenticated username and IP address.

### Method
GET

### Endpoint
https://exttest.cybertip.org/ispws/status (testing) or https://report.cybertip.org/ispws/status (production)

### Response
#### Success Response (200)
- **responseCode** (integer) - Response code `0` indicates successful authentication.
- **responseDescription** (string) - Description containing the username and IP address.

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

--------------------------------

### curl command to submit report XML

Source: https://report.cybertip.org/ispws/documentation/index.html

Curl command to submit the report XML to the CyberTipline Reporting API. Uses the test environment base URI and example credentials (usr123/pswd123). Specifies Content-Type text/xml; charset=utf-8 to ensure correct transmission of non-ASCII characters.

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

--------------------------------

### POST /submit

Source: https://report.cybertip.org/ispws/documentation/index.html

Opens a report submission by sending a single XML document conforming to the report schema. The server responds with the report ID if accepted.

```APIDOC
## POST /submit

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

### Method
POST

### Endpoint
https://{applicationRoot}/submit

### Parameters
#### Request Body
- **XML document** (XML) - Required - A single XML document conforming to the report schema.

### Request Example
<report>...</report>

### Response
#### Success Response (200)
- **reportID** (string) - The ID assigned to the report if accepted.

#### Response Example
{
  "reportID": "12345"
}
```

--------------------------------

### POST /fileinfo

Source: https://report.cybertip.org/ispws/documentation/index.html

Supplies additional details for an uploaded file. Requires a successful file upload and the report ID and file ID in an XML document. Returns success status.

```APIDOC
## POST /fileinfo

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

### Method
POST

### Endpoint
https://{applicationRoot}/fileinfo

### Parameters
#### Request Body
- **XML document** (XML) - Required - A single XML document containing the report ID and file ID.

### Request Example
<fileinfo>
  <reportID>12345</reportID>
  <fileID>67890</fileID>
</fileinfo>

### Response
#### Success Response (200)
- **status** (string) - Indicates whether the file details submission was successful.

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### Upload a file with curl to /ispws/upload

Source: https://report.cybertip.org/ispws/documentation/index.html

Uploads a file to an existing report using the CyberTipline ISP Web Service. Requires the report ID and the file path. The server responds with a reportResponse XML containing a response code, report ID, file ID, and MD5 hash of the uploaded file.

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

--------------------------------

### Submit file details with curl to /ispws/fileinfo

Source: https://report.cybertip.org/ispws/documentation/index.html

Submits the file details XML document to the CyberTipline Reporting API. The UTF-8 character set is specified in the Content-Type header to ensure correct transmission of non-ASCII characters. The server responds with a reportResponse indicating success.

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

--------------------------------

### POST /submit

Source: https://report.cybertip.org/ispws/documentation/index.html

Submits a new report to the CyberTipline Reporting API. This is the first request made for a new report submission, which "opens" the report.

```APIDOC
## POST /submit

### Description
Submits a new report to the CyberTipline Reporting API. This is the first request made for a new report submission, which "opens" the report.

### Method
POST

### Endpoint
https://exttest.cybertip.org/ispws/submit

### Parameters
#### Request Body
- **report** (XML) - Required - The report document with `<report>` as the root element.

### Request Example
```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 />
            <sadisticOnlineExploitation />
            <informational />
            <potentialAggravatingFactors />
            <instrumentalUse />
        </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>
```

### Response
#### Success Response (200)
- **responseCode** (integer) - Response code `0` indicates successful report submission.
- **responseDescription** (string) - Description of the response.
- **reportId** (string) - Report ID assigned to the submitted report.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportResponse>
    <responseCode>0</responseCode>
    <responseDescription>Success</responseDescription>
    <reportId>4564654</reportId>
</reportResponse>
```
```

--------------------------------

### POST /ispws/fileinfo

Source: https://report.cybertip.org/ispws/documentation/index.html

Submits optional file details for an uploaded file as an XML document with `<fileDetails>` as the root element.

```APIDOC
## [POST] /ispws/fileinfo

### Description
Submits optional file details for an uploaded file as an XML document with `<fileDetails>` as the root element.

### Method
POST

### Endpoint
https://exttest.cybertip.org/ispws/fileinfo

### Parameters
#### Request Body
- **fileDetails** (XML) - Required - The XML document containing file details. Must include `reportId` and `fileId`.

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

### Response
#### Success Response (200)
- **responseCode** (integer) - Response code `0` indicates successful file details submission.
- **responseDescription** (string) - Description of the response.
- **reportId** (string) - Report ID for the report.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportResponse>
    <responseCode>0</responseCode>
    <responseDescription>Success</responseDescription>
    <reportId>4564654</reportId>
</reportResponse>
```
```

--------------------------------

### POST /upload

Source: https://report.cybertip.org/ispws/documentation/index.html

Uploads a file to an existing report. Requires a successful report submission initiation and the report ID. Returns the file ID if successful.

```APIDOC
## POST /upload

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

### Method
POST

### Endpoint
https://{applicationRoot}/upload

### Parameters
#### Query Parameters
- **reportID** (string) - Required - The ID of the report to which the file is to be associated.

#### Request Body
- **file** (binary) - Required - The file to upload.

### Request Example
POST /upload?reportID=12345
Content-Type: multipart/form-data

[file content]

### Response
#### Success Response (200)
- **fileID** (string) - The ID assigned to the uploaded file.

#### Response Example
{
  "fileID": "67890"
}
```

--------------------------------

### Finish a report with curl to /ispws/finish

Source: https://report.cybertip.org/ispws/documentation/index.html

Finishes a report after all files and file details are uploaded. Requires the report ID. The server responds with a reportDoneResponse indicating success, the report ID, and the list of file IDs.

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

--------------------------------

### Status endpoint response XML

Source: https://report.cybertip.org/ispws/documentation/index.html

Response from the status endpoint when credentials are valid. The `responseDescription` contains the authenticated username and IP address, which can be used to verify server access and authentication.

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

--------------------------------

### POST /ispws/finish

Source: https://report.cybertip.org/ispws/documentation/index.html

Finishes a report after all files and file details are uploaded. This completes the submission.

```APIDOC
## [POST] /ispws/finish

### Description
Finishes a report after all files and file details are uploaded. This completes the submission.

### Method
POST

### Endpoint
https://exttest.cybertip.org/ispws/finish

### Parameters
#### Form Parameters
- **id** (string) - Required - The report ID of the report to finish.

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

### Response
#### Success Response (200)
- **responseCode** (integer) - Response code `0` indicates successful report finish.
- **reportId** (string) - Report ID of the finished report.
- **files** (array) - List of file IDs for the report.
  - **fileId** (string) - File ID of a file in the report.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportDoneResponse>
    <responseCode>0</responseCode>
    <reportId>4564654</reportId>
    <files>
        <fileId>b0754af766b426f2928a02c651ed4b99</fileId>
    </files>
</reportDoneResponse>
```
```

--------------------------------

### POST /ispws/upload

Source: https://report.cybertip.org/ispws/documentation/index.html

Uploads a file to a report. The file is associated with the report ID provided.

```APIDOC
## [POST] /ispws/upload

### Description
Uploads a file to a report. The file is associated with the report ID provided.

### Method
POST

### Endpoint
https://exttest.cybertip.org/ispws/upload

### Parameters
#### Form Parameters
- **id** (string) - Required - The report ID to which the uploaded file should be associated.
- **file** (file) - Required - The actual file being uploaded.

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

### Response
#### Success Response (200)
- **responseCode** (integer) - Response code `0` indicates successful file upload.
- **responseDescription** (string) - Description of the response.
- **reportId** (string) - Report ID for the report.
- **fileId** (string) - File ID assigned to the uploaded file.
- **hash** (string) - MD5 hash of the uploaded file.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportResponse>
    <responseCode>0</responseCode>
    <responseDescription>Success</responseDescription>
    <reportId>4564654</reportId>
    <fileId>b0754af766b426f2928a02c651ed4b99</fileId>
    <hash>fafa5efeaf3cbe3b23b2748d13e629a1</hash>
</reportResponse>
```
```
Tokens:
Raw