Matchlight REST API

Overview

The Matchlight API is a set of endpoints for programatically accessing the Matchlight system and is used by both the web interface and the software development kit (SDK).

Requests

All API endpoints use HTTPS and expect either GET or POST methods, even for requests that delete, edit, or partially edit a resource. All endpoints require authentication via an API Key in the request header with the exception of the API version endpoint.

Responses

All responses will be sent over HTTPS and will be application/json content type unless otherwise noted. Regardless of HTTP method, all successful requests will return a 200 status code. Invalid requests will return a 400. Unauthenticated responses will return a 401. Nonexistent or inaccessible resources will return a 404. Expected endpoint response codes are documented in each endpoint’s documentation.

Authentication

With the exception of the API version resource, each request requires authentication via an API Key using the X-Matchlight-Auth header keyword. This key can be generated from the Matchlight web interface. The format for the header value is {access_key}:{secret_key}. For example:

X-Matchlight-Auth: ba6c1c0ec7bc4e3d93b17ebe654dfbf8:c38c40d6c7014a94b3aa74bcad6569ed

API Version

You can get the API version with an unauthenticated POST request.:

CURL https://api.terbiumlabs.com/api/v2/version
    {
  "status": "success",
  "version": "v0.1.0+112.g5d2d69f.dirty"
}

Resources

The following are resources exposed by the Matchlight API. The API endpoints in each section are documented in detail in the api-reference-label section. The resources themselves are explained in detail in the Matchlight system documentation.

Feeds

Users can only list data feeds and pull their contents. Contact Terbium Labs to create, edit, or delete a data feed.

Please see the Matchlight system documentation for details.

Resource Operation Description
Feed GET /api/v2/feeds List of feeds in an account
  POST /api/v2/feed/(feed_name)/prepare Prepare a feed.
  POST /api/v2/feed/(feed_name)/link Get the state of a feed in preperation.
  POST /api/v2/feeds/(feed_name) List feed hit counts over a date range.

Incidents

Incidents are created by our analysts to notify you of relevant activity.

Please see the Matchlight system documentation for details.

Resource Operation Description
Event GET /api/v2/incident/(incident_id)/screenshot/(screenshot_id) Get screenshot associated with incident.
Incident GET /api/v2/incidents Get a list of all the account incidents.
  GET /api/v2/incident/(incident_id)/details Get incident details.

Projects

Projects are collections of Records. Both Projects and Records are shared among all users in an account.

Please see the Matchlight system documentation for details.

Resource Operation Description
Project POST /api/v2/project/add Create a project
  GET /api/v2/projects List all the projects in the account.
  POST /api/v2/project/(upload_token)/delete Delete the project.
  POST /api/v2/project/(upload_token)/edit Edit the project name.
  GET /api/v2/project/(upload_token) Get a project’s details.

Records

Matchlight monitors text which may be PII, Bulk PII, Documents, or Source Code. Generically, these are all referred to as “records”.

Please see the Matchlight system documentation for details.

Resource Operation Description
Record GET /api/v2/records Get a list records in an account.
  POST /api/v2/records/upload/source_code/(upload_token) Create new records in a document type project.
  POST /api/v2/records/upload/document/(upload_token)  
  POST /api/v2/records/upload/bulk_pii/(upload_token) Create a new PII record.
  POST /api/v2/records/upload/pii/(upload_token)  
  POST /api/v2/record/(record_id)/delete Delete the record.
  POST /api/v2/record/(record_id)/edit Edit the record metadata.

Report

Reports are documents created by our analysts that summarize activity relevant to your account.

Please see the Matchlight system documentation for details.

Resource Operation Description
Report GET /api/v2/reports List of reports for an account
  GET /api/v2/report/(report_key)/details Get report details.

Alerts

An Alert is a notification that is triggered anytime Terbium finds a match for a Record on the dark web. What constitutes an alert varies among record types and account-specific alerting thresholds.

Please see the Matchlight system documentation for details.

Resource Operation Description
Alert GET /api/v2/alerts/count Get user alerts count.
  GET /api/v2/alerts List alerts.
  GET /api/v2/alert/(alert_id)/details Get alert details.
  POST /api/v2/alert/(alert_id)/edit Update alert metadata.

Matchlight API Reference

The following is a complete listing of documented endpoints in the Matchlight API.

GET /api/v2/alert/(alert_id)/details

Detail view for alerts.

Status Codes:

Example Request URL:

https://api.terbiumlabs.com/api/v2/alert/5b160346cfb7404ba2aca6458d95c22e/details

Example Response:

{
  "details": {
    "pii": [
      {
        "email": "o****@gmail.com",
        "first": "a****",
        "last": "b****",
        "record_id": "d3c59d38c4054f62876a2a7a3dca41ca"
      }
    ]
  },
  "notes": "",
  "type": "pii"
}
POST /api/v2/alert/(alert_id)/edit

Endpoint to edit alert metadata (acknowledgment status, archived status) on a per-user basis.

JSON Parameters:
 
  • archived (integer) – True (1) or false (0) if the alert should be archived.
  • seen (integer) – True (1) or false (0) if the alert should be marked as seen.
Status Codes:

Example Request URL:

https://api.terbiumlabs.com/api/v2/alert/5b160346cfb7404ba2aca6458d95c22e/edit

Example Request Payload:

{
  "seen": true,
  "archived": true
}

Example Response:

{
  "archived": true,
  "seen": true
}
GET /api/v2/alerts

Returns a list of all alerts belonging to a particular account. If there are no alerts an empty array is returned. Response content will depend on record type.

Query Parameters:
 
  • archived (integer) – True (1) or false (0) if archived alerts should be returned. Returns both archived and unarchived alerts by default.
  • mtime (timestamp) – The UNIX timestamp of the last time the alert was modified. If present, return all alerts with an mtime greater or equal to this.
  • seen (integer) – True (1) or false (0) if seen alerts should be returned. Returns both seen and unseen alerts by default.
  • offset (integer) – Number of alerts to offset. Used for pagination.
  • limit (integer) – A boolean specifying whether or not to return alerts that have been seen. Defaults to 50.
  • record_id_filter (string) – return alerts only related to this record_id.
  • upload_token_filter (string) – Filter by project upload token
Status Codes:
  • 200 OK – Request completed successfully.

Example Request URL:

https://api.matchlig.ht/api/v2/alerts?limit=50

Example PII Response:

{
  "alerts": [
    {
      "alert_number": 4,
      "archived": false,
      "asset_name": "d****@terbiumlabs.com",
      "ctime": 1472681028,
      "date": "Wed, 31 Aug 2016 22:03:48 GMT",
      "details": {
        "pii": {
          "fields": [
            "phone"
          ]
        }
      },
      "id": "a6dee1d2eebe47b2a9b1795c0894321a",
      "mtime": null,
      "project_name": "Ma Fam",
      "seen": false,
      "type": "pii",
      "upload_token": "6cd3edb0-8cfe-480c-948e-70f0780f14ac",
      "url": "http://pastebin.com/raw.php?i=gK9yyMhr",
      "url_metadata": {
        "description": "Site description",
        "tor_only": false
      }
    },
  ],
  "count": 4
}

Example Document Response:

{
  "alerts": [
    {
      "alert_number": 288,
      "archived": false,
      "asset_name": "Sample 1",
      "ctime": 1478395050,
      "date": "Sun, 06 Nov 2016 01:17:30 GMT",
      "details": {
        "document": {
          "score": 800
        }
      },
      "id": "9b71676bac084ee6b7169be00094c385",
      "mtime": null,
      "project_name": "sample project 1",
      "seen": false,
      "type": "document",
      "upload_token": "82ea7b3c-ce59-4fde-a56f-7c584edacff9",
      "url": "https://sample_url.com/sample_1",
      "url_metadata": {
        "description": "",
        "tor_only": false
      }
    },
    {
      "alert_number": 287,
      "archived": false,
      "asset_name": "Sample 2",
      "ctime": 1478387631,
      "date": "Sat, 05 Nov 2016 23:13:51 GMT",
      "details": {
        "document": {
          "score": 800
        }
      },
      "id": "81bbbb2467ba42dbac68d3fb7ed1f8d0",
      "mtime": null,
      "project_name": "sample project 1",
      "seen": false,
      "type": "document",
      "upload_token": "82ea7b3c-ce59-4fde-a56f-7c584edacff9",
      "url": "https://sample_url.com/sample_2",
      "url_metadata": {
        "description": "",
        "tor_only": false
      }
    }
  ],
  "count": 2
}
GET /api/v2/alerts/count

Returns a count of all alerts belonging to a particular account.

Query Parameters:
 
  • archived (integer) – True (1) or false (0) if archived alerts should be returned. Returns both archived and unarchived alerts by default.
  • seen (integer) – True (1) or false (0) if seen alerts should be counted. Returns count of both seen and unseen alerts by default.
Status Codes:
  • 200 OK – Request completed successfully.

Example Request URL:

https://api.matchlig.ht/api/v2/alerts/count?seen=0

Example Response:

{
  "count": 123
}
POST /api/v2/detailed_search

Search API endpoint.

Status Codes:
  • 200 OK – Request completed successfully

Example Request URL:

https://api.terbiumlabs.com/api/v2/detailed_search

Example Request:

{
  "fingerprints": [
    "b8826850e1ef64c02f5289152f89557a",
    "c54447e704dce4c01cfd89b24bb967cf"
  ]
}

Example Response:

{
  "results": [
    {
      "cwid": "ffa23cb812f9979c17a498c0a3ba95ec",
      "score": 800,
      "ts": 1457870369,
      "urls": [
        [
          1457870369,
          "https://www.reddit.com/r/AskReddit/comments/3oqj4a/which_"
        ]
      ]
    },
    {
      "cwid": "f6bf40e2e8c13be9b5317f5a50afa7f2",
      "score": 800,
      "ts": 1461212069,
      "urls": [
        [
          1461212069,
          "http://pastebin.com/raw.php?i=iDHHAd0Y"
        ]
      ]
    }
  ]
POST /api/v2/feed/(feed_name)/link

Return the current state of a feed report generation task.

Expects JSON request data containing the feed_response_id identifying which report this query is targetting.

The status key in the response array takes one of three possible states:

  • failed: The report cannot be generated. The message will key contain more information about the failure.
  • pending: The report is still being compiled. The progress key will contain progress information on the request of or null if progress cannot be estimated.
  • ready: The report has been generated and is available for download. The response will also contain a url key containing a link to the final CSV.
JSON Parameters:
 
  • feed_response_id (UUID) – The UUID of the feed request, generated by the /prepare endpoint.
Status Codes:

Example Request URL:

https://api.terbiumlabs.com/api/v2/feed/CompanyEmailAddress/link

Example Request Payload:

{
  "feed_response_id": "77bad366-fa8b-43e9-b302-5e343a288eba"
}

Example Response:

{
  "progress": "100",
  "status": "pending"
}
POST /api/v2/feed/(feed_name)/prepare

Get a feed_response_id to track the progress of a feed report generation task using the /link endpoint.

JSON Parameters:
 
  • start_date (timestamp) – A UNIX UTC timestamp of the start date for the request.
  • end_date (timestamp) – A UNIX UTC timestamp of the end date for the request.
Status Codes:

Example Request URL:

https://api.terbiumlabs.com/api/v2/feed/CompanyEmailAddress/prepare

Example Request Payload:

{
  "start_date": 1474243200,
  "end_date": 1474329600
}

Example Response:

{
  "feed_response_id": "1da37adb-75a9-40cc-a580-74df76ad8285"
}
GET /api/v2/feeds

List all the feed subscriptions associated with a user’s account.

Status Codes:
  • 200 OK – Request completed successfully. If no results are found an empty array will be returned for the feeds value in the JSON response.

Example Request URL:

https://api.terbiumlabs.com/api/v2/feeds

Example Response:

{
  "feeds": [
    {
      "description": null,
      "name": "CompanyEmailAddress",
      "recent_alerts_count": 6,
      "start_timestamp": "1464912000",
      "stop_timestamp": null
    }
  ]
}
POST /api/v2/feeds/(feed_name)

List feed hit count per day on a given feed over a range of days.

JSON Parameters:
 
  • start_date (timestamp) – A UNIX UTC timestamp of the start date for the request.
  • end_date (timestamp) – A UNIX UTC timestamp of the end date for the request.
Status Codes:

Example Request URL:

https://api.terbiumlabs.com/api/v2/feeds/CompanyEmailAddress

Example Response:

{
  "1464912000": 6,
  "1464998400": 7,
  "1465084800": 3,
  "1465171200": 2,
  "1465257600": 16,
  "1465344000": 8,
  "1465430400": 12,
  "1465516800": 103
}
GET /api/v2/incident/(incident_id)/details

Detail view for incidents.

Status Codes:

Example Request URL:

https://api.terbiumlabs.com/api/v2/incident/5b160346cfb7404ba2aca6458d95c22e/details

Example Response:

{
  "impact": ["5 banks"],
  "industry": ["financial"],
  "ts": "2017-01-22T23:19:00",
  "actor": ["haxxster"],
  "summary": "Matchlight found 5 new listings...",
  "analysis": "This leak was the result of a ...",
  "motive": ["financial"],
  "type": ["listing"],
  "id": "4227284e-4fb4-49f8-94f3-00722df79ce4"
}
GET /api/v2/incident/(incident_id)/screenshot/(screenshot_id)

Screenshot download for an incident.

Status Codes:
  • 200 OK – Request completed successfully
  • 404 Not Found – The incident or screenshot does not exist

Example Request URL:

https://api.terbiumlabs.com/api/v2/incident/00000000-0000-0000-0000-000000000000/screenshot/00000000-0000-0000-0000-000000000000
Example Response::
Some image/png
GET /api/v2/incidents

Returns a list of all incidents on an account.

This endpoint will return list of all incidents related to account of the authenticated user.

Query Parameters:
 
  • start_date (timestamp) – The UNIX timestamp of the oldest
incident to return. If present, return all incidents with a
ts greater than or equal to this.
Query Parameters:
 
  • end_date (timestamp) – The UNIX timestamp of the newest
incident to return. If present, return all incidents with a
ts less than or equal to this.
Resource URL:
https://api.matchlig.ht/v2/incidents
Example Request:
CURL https://api.matchlig.ht/v2/incidents

Example Response:

{
  "incidents": [
    {
      "impact": ["5 banks"],
      "industry": ["financial"],
      "ts": "2017-01-22T23:19:00",
      "actor": ["haxxster"],
      "summary": "Matchlight found 5 new listings...",
      "motive": ["financial"],
      "type": ["listing"],
      "id": "4227284e-4fb4-49f8-94f3-00722df79ce4"
    }
  ],
  "count": 1
}
GET /api/v2/project/(upload_token)

Return the project details for a single project.

JSON Parameters:
 
  • upload_token (UUID) – The upload token for the project.
Status Codes:
  • 200 OK – Request completed successfully

Example Request URL:

https://api.matchlig.ht/api/v2/project/65c4443fa6c543b18707a5e7bd7877b3

Example Response:

{
  "last_date_modified": 1472440027,
  "number_of_unseen_alerts": 2,
  "number_of_records": 1,
  "project_name": "sample project 1",
  "project_type": "pii",
  "project_upload_token": "65c4443f-a6c5-43b1-8707-a5e7bd7877b3"
}
POST /api/v2/project/(upload_token)/delete

An endpoint for the session user to delete a project.

Example Request:
An HTTP POST with empty body. The upload_token for the project that you want to delete is passed in the URL route.
Status Codes:

EXample Request URL:

https://api.matchlig.ht/api/v2/project/65c4443fa6c543b18707a5e7bd7877b3/delete

Example Request Payload:

{}

Example Response:

{
  "success": true
}
POST /api/v2/project/(upload_token)/edit

Update a project name and/or alert notification threshold. The alert notification threshold can only be set for document and source code project types.

JSON Parameters:
 
  • name (string) – The new project name.
  • alert_notification_threshold (string) – The new project alert notification threshold.
Status Codes:
  • 200 OK – Request completed successfully
  • 400 Bad Request – Invaid user input, including trying to set the alert notification threshold on a pii project type.
  • 404 Not Found – Project not found

Example Request URL:

https://api.matchlig.ht/api/v2/project/65c4443fa6c543b18707a5e7bd7877b3/edit

Example Request:

{
  "name": "Patented DNA strands"
}

Example Response:

{
  "data": {
    "id": "1",
    "last_date_modified": 1472440027,
    "number_of_unseen_alerts": 2,
    "number_of_records": 1,
    "project_name": "Patented DNA strands",
    "project_type": "pii",
    "project_upload_token": "562aad9b-e50b-461e-b68c-d1d37286b046"
  }
}
POST /api/v2/project/add

This endpoint allows an authorized user to create a new project. Requires a name and a project type.

JSON Parameters:
 
  • name (string) – The new project name.
  • type (string) – The Matchlight project type. Options are pii, document, and source_code.
  • alert_notification_threshold (integer) – the notification threshold for alerts. If this is not present, it will be set to 1 (all alerts come through) for documents and source code. For PII and bulk PII records, this is always set to 800, regardless of what is sent.
Status Codes:

Example Request URL:

https://api.terbiumlabs.com/api/v2/project/add

Example Request Payload:

{
  "name": "United Staple Company Executive Credit Cards",
  "type": "pii",
  "alert_notification_threshold": null
}

Example Response:

{
  "data": {
    "id": "1",
    "name": "United Staple Company Executive Credit Cards",
    "upload_token": "562aad9b-e50b-461e-b68c-d1d37286b046"
  }
}
GET /api/v2/projects

List all the projects associated with a user’s account.

Query Parameters:
 
  • project_type (string) – Filter parameter for project type. Options are pii, document, and source_code.
Status Codes:
  • 200 OK – Request completed successfully

Example Request URL:

https://api.matchlig.ht/api/v2/projects?project_type=pii

Example Response:

{
  "data": [
    {
      "last_date_modified": 1472440027,
      "number_of_unseen_alerts": 2,
      "number_of_records": 1,
      "project_name": "sample project 1",
      "project_type": "pii",
      "project_upload_token": "65c4443f-a6c5-43b1-8707-a5e7bd7877b3"
    },
    {
      "last_date_modified": 1472440029,
      "number_of_unseen_alerts": 0,
      "number_of_records": 0,
      "project_name": "sample project 2",
      "project_type": "pii",
      "project_upload_token": "dbe6546f-5565-4c4b-8a04-679eb01db214"
    }
  ],
  "count": 2
}
POST /api/v2/record/(record_id)/delete

An endpoint for the session user to delete a record.

Status Codes:

Example Request URL:

https://api.terbiumlabs.com/api/v2/record/ba834666-db4d-436f-91f0-82695a1f10bf/delete

Example Request Payload:

{}

Example Response:

{
  "success": true
}
POST /api/v2/record/(record_id)/edit

An endpoint to edit the name and description for document and source code records. This endpoint does not edit pii or bulk pii records.

Status Codes:
  • 200 OK – Request completed successfully
  • 404 Not Found – Record does not exist or type is invalid

Example Request URL:

https://api.terbiumlabs.com/api/v2/record/ba834666-db4d-436f-91f0-82695a1f10bf/edit

Example Request Payload:

{
  "name": "Record Name Version 2",
  "desc": "The secret formula.",
}

Example Response:

{
    "id": "ae38356fb4ce185c72b648e68d498eea",
    "name": "Record Name Version 2",
    "desc": "The secret formula.",
    "type": 1,
    "ctime": 1472137132,
    "mtime": 1472137132,
    "number_unseen_alerts": 0,
    "metadata": {},
}
GET /api/v2/records

List all the records in an account.

Queryparameters UUID upload_token:
 

The project upload token to filter by.

Status Codes:
  • 200 OK – Request completed successfully. An empty array will be returned if no records are found.

Example Request URL:

https://api.matchlig.ht/api/v2/records?upload_token=562aad9b-e50b-461e-b68c-d1d37286b046

Example Response:

{
  "data": [
    {
        "id": "5c72b648e68d4ae38356fb4ce1898eea",
        "name": "Some Record Name",
        "description": "Some record description...",
        "type": 3,
        "ctime": 1471991529,
        "mtime": 1471991529,
        "number_unseen_alerts": 0,
        "metadata": {
            "email": "f****@email.org",
            "first": "f****",
            "last": "t****",
            "user_record_id": null
        },
    },
    {
        "id": "ae38356fb4ce185c72b648e68d498eea",
        "name": "A Second Record Name",
        "description": "Some other record description...",
        "type": 3,
        "ctime": 1471991546,
        "mtime": 1471991546,
        "number_unseen_alerts": 5,
        "metadata": {
            "email": "r****@email.org",
            "first": "r****",
            "last": "g****",
            "user_record_id": null
        },
    }
  "count": 2
}
POST /api/v2/records/upload/bulk_pii/(upload_token)

Create a new PII record.

JSON Parameters:
 
  • name (string) – (Required) A full name
  • desc (string) – (Required) A description of the record
  • name_fingerprints (array) – (Optional) The fingerprints of the name field.
  • email_fingerprints (array) – (Optional) The fingerpints of the email field
  • ssn_fingerprints (array) – (Optional) The fingerprints of the SSN field
  • street_address_fingerprints (array) – (Optional) The fingerprints of the street address field
  • city_state_zip_fingerprints (array) – (Optional) The fingerprints of the city, state, and zip field.
  • phone_fingerprints (array) – (Optional) The fingerprints of the phone number field
  • blinded_first (string) – (Optional) The censored first name field for displaying the first name of the PII record. E.g “John” could become j*** or j**n, however you want the name to be displayed.
  • blinded_last (string) – (Optional) The censored last name for displaying.
  • blinded_email (string) – (Optional) The censored email for displaying.
  • user_record_id (string) – : (Optional) A user-provided unique identifier.
Status Codes:
  • 200 OK – Request completed successfully
  • 400 Bad Request – Variation limit exceeded, fingerprint limit exceeded
  • 404 Not Found – Project not found or record type mismatch

Example Request URL:

https://api.terbiumlabs.com/api/v2/records/upload/pii/ba834666-db4d-436f-91f0-82695a1f10bf

Example Request Payload:

{
  "name":"r****@email.org",
  "desc":"fingerprinted in-browser",
  "email_fingerprints":[
    ["c6b633114b86d9f9"]
  ],
  "blinded_email":"r****@email.org",
  "name_fingerprints":[
    [
      "1ea55ada9db8db77",
      "72a89e15d316785c"
    ],
    [
      "39a0b7a092885922",
      "3b8bfd39b50b3f79"
    ],
    [
      "68241752690fe696",
      "6b78cdf887c79bca"
    ],
    [
      "08991ae9e81f8530",
      "e90bc9d2319143a9"
    ],
    ...,
  ],
  "blinded_first":"r****",
  "blinded_last":"g****",
  "ssn_fingerprints":[
    ["1789b5f761c5e407"]
  ],
  "street_address_fingerprints":[
    [
      "21817cb5def3f452",
      "b96d7de28b149f6e"
    ],
    [
      "7ecd2b9755c70208",
      "81eee437859f18d0"
    ],
    [
      "4c6dd9e22e7bd03b",
      "a45a008f41dd9f46"
    ],
    [
      "58d1bf7017aaa908"]],
  "city_state_zip_fingerprints":[
    [
      "c7b568ddc6c3c6f4",
      "d4e4c19d1da1ee11"
    ],
    [
      "8a1e456e723c9b58",
      "fd25e167abde03f2
    "]
  ],
  "phone_fingerprints":[
    ["7428b2f77cfc1743"]
  ]
}

Example Response:

{
    "id": "3a98bce12b1f46de8721372f8451ea68",
    "name": "r****@email.org",
    "description": "fingerprinted in-browser",
    "type": 4,
    "ctime": 1474300477,
    "mtime": 1474300477,
    "metadata": {
        "email": "r****@email.org",
        "first": "r****",
        "last": "g****",
        "user_record_id": null
    },
    "number_unseen_alerts": 0
}
POST /api/v2/records/upload/document/(upload_token)

Create new a document record. Only paying customers are allowed to upload this record type.

JSON Parameters:
 
  • name (string) – The record name
  • desc (string) – The record description
  • fingerprints (array) – The array of fingerprints that make up the record.
  • metadata (map) – And metadata associated with the record
Status Codes:
  • 200 OK – Request completed successfully
  • 400 Bad Request – A paid account is required to access this endpoint, or too many fingerprints were included in the record.
  • 404 Not Found – Project not found

Example Request URL:

https://api.terbiumlabs.com/api/v2/records/upload/document/ba834666-db4d-436f-91f0-82695a1f10bf

Example Request Payload:

{
  "name": "Secret Formula 01-2345",
  "desc": "The secret formula for Rooster Sauce",
  "fingerprints": [
    "89bc8d266ab3ffab",
    "5c345dd30f4b89ca"
  ],
  "metadata": {}
}

Example Response:

{
    "id": "ae38356fb4ce185c72b648e68d498eea",
    "name": "Secret Formula 01-2345",
    "description": "The secret formula for Rooster Sauce",
    "type": 1,
    "ctime": 1472137132,
    "mtime": 1472137132,
    "number_unseen_alerts": 0,
    "metadata": {},
}
POST /api/v2/records/upload/pii/(upload_token)

Create a new PII record.

JSON Parameters:
 
  • name (string) – (Required) A full name
  • desc (string) – (Required) A description of the record
  • name_fingerprints (array) – (Optional) The fingerprints of the name field.
  • email_fingerprints (array) – (Optional) The fingerpints of the email field
  • ssn_fingerprints (array) – (Optional) The fingerprints of the SSN field
  • street_address_fingerprints (array) – (Optional) The fingerprints of the street address field
  • city_state_zip_fingerprints (array) – (Optional) The fingerprints of the city, state, and zip field.
  • phone_fingerprints (array) – (Optional) The fingerprints of the phone number field
  • blinded_first (string) – (Optional) The censored first name field for displaying the first name of the PII record. E.g “John” could become j*** or j**n, however you want the name to be displayed.
  • blinded_last (string) – (Optional) The censored last name for displaying.
  • blinded_email (string) – (Optional) The censored email for displaying.
  • user_record_id (string) – : (Optional) A user-provided unique identifier.
Status Codes:
  • 200 OK – Request completed successfully
  • 400 Bad Request – Variation limit exceeded, fingerprint limit exceeded
  • 404 Not Found – Project not found or record type mismatch

Example Request URL:

https://api.terbiumlabs.com/api/v2/records/upload/pii/ba834666-db4d-436f-91f0-82695a1f10bf

Example Request Payload:

{
  "name":"r****@email.org",
  "desc":"fingerprinted in-browser",
  "email_fingerprints":[
    ["c6b633114b86d9f9"]
  ],
  "blinded_email":"r****@email.org",
  "name_fingerprints":[
    [
      "1ea55ada9db8db77",
      "72a89e15d316785c"
    ],
    [
      "39a0b7a092885922",
      "3b8bfd39b50b3f79"
    ],
    [
      "68241752690fe696",
      "6b78cdf887c79bca"
    ],
    [
      "08991ae9e81f8530",
      "e90bc9d2319143a9"
    ],
    ...,
  ],
  "blinded_first":"r****",
  "blinded_last":"g****",
  "ssn_fingerprints":[
    ["1789b5f761c5e407"]
  ],
  "street_address_fingerprints":[
    [
      "21817cb5def3f452",
      "b96d7de28b149f6e"
    ],
    [
      "7ecd2b9755c70208",
      "81eee437859f18d0"
    ],
    [
      "4c6dd9e22e7bd03b",
      "a45a008f41dd9f46"
    ],
    [
      "58d1bf7017aaa908"]],
  "city_state_zip_fingerprints":[
    [
      "c7b568ddc6c3c6f4",
      "d4e4c19d1da1ee11"
    ],
    [
      "8a1e456e723c9b58",
      "fd25e167abde03f2
    "]
  ],
  "phone_fingerprints":[
    ["7428b2f77cfc1743"]
  ]
}

Example Response:

{
    "id": "3a98bce12b1f46de8721372f8451ea68",
    "name": "r****@email.org",
    "description": "fingerprinted in-browser",
    "type": 3,
    "ctime": 1472137132,
    "mtime": 1472137132,
    "number_unseen_alerts": 0,
    "metadata": {
        "email": "r****@email.org",
        "first": "r****",
        "last": "g****",
        "user_record_id": null
    },
}
POST /api/v2/records/upload/source_code/(upload_token)

Create a new source code record. Only paying customers are allowed to upload this record type.

JSON Parameters:
 
  • name (string) – The record name
  • desc (string) – The record description
  • fingerprints (array) – The array of fingerprints that make up the record.
  • metadata (map) – And metadata associated with the record
Status Codes:
  • 200 OK – Request completed successfully
  • 400 Bad Request – A paid account is required to access this endpoint, or too many fingerprints were included in the record.
  • 404 Not Found – Project not found

Example Request URL:

https://api.terbiumlabs.com/api/v2/records/upload/source_code/ba834666-db4d-436f-91f0-82695a1f10bf

Example Request Payload:

{
  "name": "Secret Formula 01-2345",
  "desc": "The secret formula for Rooster Sauce",
  "fingerprints": [
    "89bc8d266ab3ffab",
    "5c345dd30f4b89ca"
  ],
  "metadata": {}
}

Example Response:

{
    "id": "bb45f229eca043c79f0484770812757b",
    "name": "Secret Formula 01-2345",
    "description": "The secret formula for Rooster Sauce",
    "type": 2,
    "ctime": 1472137132,
    "mtime": 1472137132,
    "number_unseen_alerts": 0,
    "metadata": {},
}
GET /api/v2/report/(report_key)/details

Detail view for reports.

Status Codes:

Example Request URL:

https://api.terbiumlabs.com/api/v2/report/5b160346cfb7404ba2aca6458d95c22e/details

Example Response:

{
  id: "0000-0000-0000-0000",
  title: "January Report",
  ts: 1486577703,
  url: ""
}
GET /api/v2/reports

List all the reports associated with a user’s account.

Status Codes:
  • 200 OK – Request completed successfully. If no results are found an empty array will be returned for the reports value in the JSON response.

Example Request URL:

https://api.terbiumlabs.com/api/v2/reports

Example Response:

{
  reports: {
    "0000-0000-0000-0000_2017-01-05.pdf": {
      id: "0000-0000-0000-0000_2017-01-05.pdf",
      ts: 1486577703,
    },
  }
  count: 1
}
GET /api/v2/version

Returns version information from versioneer. Note that this endpoint allows unauthenticated requests.

Status Codes:
  • 200 OK – Request completed successfully

Example Request URL:

https://api.terbiumlabs.com/api/v2/version

Example Response:

{
  "status": "success",
  "version": "v0.1.0+112.g5d2d69f.dirty"
}