NAV Navbar
shell python
Documentation header

Introduction

Welcome to Inscribe! Use the Inscribe API to evaluate your customers' documents so you can approve your customers faster and reduce fraud. Inscribe automatically extracts key information from your documents and looks for evidence of fraud in an instant.

Here you can find all the documentation and sample code you need to get started. If you have any questions about the API, pricing or new features please contact us at team@inscribe.ai or join our Slack support group.

Version: 1.0.0

Quick Start Guide

This quickstart guide allows you to evaluate your first customer document set within minutes. Follow the steps below to get started.

Sign Up and generate API Key

Sign up to Inscribe for free on our website at https://app.inscribe.ai/auth/register/ to create your account and visit https://app.inscribe.ai/#/profile/api to generate your API key.

import inscribe

# API Authentication
api = inscribe.Client(api_key="YOUR_API_KEY")

# Create customer folder
customer = api.create_customer(customer_name="new")
customer_id = customer['data']['id']

# Upload document 
doc_obj = open("YOUR_FILE.pdf", "rb")
document = api.upload_document(customer_id = customer_id, document=doc_obj)
document_id = document['result_urls'][0]['document_id']

# Check document
result = api.check_document(customer_id=customer_id, document_id = document_id)
curl http://www.inscribe.ai/api/v1/customers \
 -H "Authorization: YOUR_API_KEY" \ 
 -d '{"customer_name": "first_customer"}'

Create Your First Customer

To evaluate a customer document set, the first step is to create a customer folder. Customers folders are used to store documents. You should create a customer folder for each new customer you are looking to evaluate.

curl "https://app.inscribe.ai/api/v1/customers/{customer_id}/documents"
  -H "Authorization: YOUR_API_KEY"
  -F {document_filename}{.pdf, .png, .jpg}@/{document_file_path}

Upload Your First Document

The second step is to upload documents to your customer folder. When the documents are uploaded, they are automatically analyzed by our fraud detection systems.

curl http://www.inscribe.ai/api/v1/customers/{customer_id}/documents/{document_id} \
 -H "Authorization: YOUR_API_KEY"

The above command returns a JSON response which contains a URL that leads to detailed results when we are finished processing the document (more at Check Document).

Check Your First Document

The last step is to retrieve a detailed JSON response that contains the results from each of Inscribe's detection systems.

Authentication

To authorize, use this code:

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
# Each cURL request requires the header to contain the authorization key.
curl "http://www.inscribe.ai/"
  -H "Authorization: YOUR_API_KEY"

Make sure to replace YOUR_API_KEY with your API key.

Summary: Authenticate your requests with your API key.

Description: Inscribe uses API keys to allow access to our API. If you would like access to the Inscribe API please contact us as team@inscribe.ai.

Inscribe expects for the API key to be included in all API requests to the server in a header that looks like the following: Authorization: YOUR_API_KEY

Customers

Create Customer

Summary: Create a new customer folder

Description: This endpoint allows you to create customer folders to easily track and store documents. When checking a document you can simply add the customer name into the customer_id parameter to add a document to a particular customer folder. The results of our analysis will cross-check against the other documents within a customer folder.

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
api.create_customer("NEW CUSTOMER 1")
curl http://www.inscribe.ai/api/v1/customers \
 -H "Authorization: YOUR_API_KEY" \ 
 -d '{"name": 'CUSTOMER_ID'}'

The above command returns JSON structured like this:

{
    "success": true,
    "message": "Customer was successfully created",
    "data": {
        "id": 4,
        "customer_name": "NEW CUSTOMER 1",
        "url": "https://app.inscribe.ai/#/files/4"
    }
}

HTTP Request

POST /api/v1/customers/

Parameters

Name Located in Description Required Type
customer name body customer name no

Responses

Code Description
201 customer created

Get List of Customers

Summary: Returns list of all customers

Description: This endpoint allows you to get a list of all the customers you have created.

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
all_customers = api.get_all_customers()
curl http://www.inscribe.ai/api/v1/customers \
 -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "NEW CUSTOMER 1",
      "url": "https://app.inscribe.ai/#/files/20"
    },
    {
      "id": 2,
      "name": "NEW CUSTOMER 2",
      "url": "https://app.inscribe.ai/#/files/21"
    }
  ]
}

HTTP Request

GET /api/v1/customers/

Responses

Code Description
200 search results matching criteria

Get Specific Customer

Summary: Returns link to web application.

Description: This endpoint returns the URL link to the web application. This is useful to quickly access the relevant dashboard page to perform further visual analysis.

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
get_customer = api.get_customer(customer_id='CUSTOMER_ID')
curl http://www.inscribe.ai/api/v1/customers/{customer_id} \
 -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "NEW CUSTOMER 1",
    "url": "https://app.inscribe.ai/#/files/21"
  }
}

HTTP Request

GET /api/v1/customer/{customer_id}

Parameters

Name Located in Description Required Type
customer_id path customer id yes string

Responses

Code Description
200 successful operation

Delete Customer

Summary: Delete customer folder

Description: This endpoint allows you to delete a customer folder.

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
api.delete_customer(customer_id='CUSTOMER_ID')

curl -X DELETE http://www.inscribe.ai/api/v1/customers/{customer_id} \
 -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "success": true,
  "message": "Customer was successfully deleted"
}

HTTP Request

DELETE /api/v1/customers/{customer_id}

Parameters

Name Located in Description Required Type
customer_id path customer id yes string

Responses

Code Description
200 successfully deleted

Documents

Upload Document

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
api.upload_document(customer_id='CUSTOMER_ID',document='FILE')
curl "https://app.inscribe.ai/api/v1/customers/{customer_id}/documents"
  -H "Authorization: YOUR_API_KEY"
  -F {document_filename}{.pdf, .png, .jpg}@/{document_file_path}

The above command returns JSON structured like this:

{
    "success": true,
    "message": "Successfully uploaded. Please poll returned URLs for results which will be available when processing is completed.",
    "result_urls": [{
        "filename": "example.pdf",
        "url": "https://app.inscribe.ai/api/v1/customers/2/documents/10"
    }],
    "customer": {
        "name": "test customer 1",
        "customer_id": 2,
        "url": "https://app.inscribe.ai/#/files/2"
    }
}

Summary: Upload document for evaluation

Description: This endpoint allows you to upload one or more documents that you would like to be evaluated for fraud. Once the document(s) has been uploaded, it will be queued for processing by Inscribe's fraud detection algorithms. A JSON response containing a unique document_id is returned which can be used in the Check Document endpoint to retrieve the fraud detection results. You can upload documents in PDF, PNG or JPG format.

HTTP Request

POST /api/v1/customers/{customer_id}/documents

Parameters

Name Located in Description Required Type
customer_id path customer id yes string
document body document file yes object

Responses

Code Description
202 Accepted

Check Document

Summary: Get results of Inscribe's fraud evaluation

Description: This endpoint allows you to get the fraud evaluation results of an uploaded document. A JSON response is returned with the results from each detection system in addition to an overall determination (under the fraudulent key). The overall determination returns a true/false anwser to signal if any of our detectors found a suspicious document. Each of the detection results are briefly explained below.

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
new_customer = api.check_document(customer_id='CUSTOMER_ID', document_id = 'DOCUMENT_ID')
curl http://www.inscribe.ai/api/v1/customers/{customer_id}/documents/{document_id} \
 -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "status": 200,
  "success": true,
  "document": {
    "id": 19,
    "url": "https://app.inscribe.ai/api/v1/customers/16/documents/19",
    "customer": {
      "id": 16,
      "customer-dashboard-url": "https://app.inscribe.ai/#/files/16"
    },
    "created_at": "2018-12-01T05:51:34.709Z",
    "name": "16",
    "pages": [
      {
        "summary": {
          "metadata": {
            "unknown": [
              "Created by PScript5.dll Version 5.2",
              "Produced by Acrobat Distiller 5.0.5 (Windows)"
            ],
            "bad": [
              "Creation and modification dates do not match"
            ],
            "good": []
          },
          "fonts": {
            "summary": {
              "unknown": [],
              "bad": [
                "5 inconsistent words found"
              ],
              "good": []
            },
            "details": {}
          },
          "rectangles": {
            "summary": {
              "unknown": [],
              "bad": [],
              "good": [
                "No rectangles found"
              ]
            },
            "details": {}
          },
          "blacklist": {
            "phones": [],
            "names": [],
            "addresses": []
          },
          "text": "1000 Walnut Kansas City MO 64106-3686  Jane Customer 1234 Anywhere Dr. Small Town, MO 3.14159 ... ",
          "template_similarity": {
            "bank_statement_forgery.pdf": 0.89
          }
        },
        "fraudulent": true,
        "document-dashboard-url": "https://app.inscribe.ai/#/files/16/28/pdf"
      }
    ]
  }
}

HTTP Request

GET /api/v1/customers/{customer_id}/documents/{document_id}

Parameters

Name Located in Description Required Type
customer_id path customer id yes string
document_id path document id yes string

Responses

Code Description
200 ok

Metadata

The metadata response shows the metadata of a file, such as when it was created and which program it was created by. Not all files will have the same amount of information in the metadata, so some headings may not be present for some files.

What to look out for:
- Differing date of creation and date of modification
- A photo editing tool, such as Adobe Photoshop, as the document creator or producer

Fonts

The fonts analysis highlights the words in the document that contain inconsistent characters—those that are a different size or font to the rest of the word.

The font size measurement used in this analysis is accurate to three decimal places, so even if a forger has matched inserted text to its surroundings so well that it is indistinguishable to the human eye, this method can still detect the discrepancy.

Rectangles

The rectangles analysis shows any rectangle objects found in the PDF document which can be a telltale sign of fraud.

A common forgery technique is to obscure an element in a PDF with a rectangle matching the background color, and then to place new text on top of that rectangle. A legitimate document may also contain rectangles but these should match up to structural elements in the PDF and will not appear out of place.

Blacklists

The blacklists response displays any occurrence of blacklisted names, addresses or phone numbers. Names, addresses or phone numbers that are known to be used in fraudulent applications are a very effective way of detecting fraud. To add new blacklist entries, please see Blacklists.

OCR Text

The text response returns the text content from a document—for both images and PDF documents—which you can use for further analysis or processing.

Template Matching

The template_similarity response shows the result of a comparison of a document against a database of previously known fraudulent document templates. For example, fraudulent pay stubs are often created by using a template with modified information. We check a database of templates to ensure your document does not match a template that is often used in fraud. To add new template documents, please see Templates.

New Detectors

We have more detectors currently in development which we will announce in the coming months. For more information, please feel free to contact us at team@inscribe.ai.

Delete Document

Summary: Delete documents

Description: This endpoint allows you to delete a specific document.

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
new_customer = api.delete_document(customer_id='CUSTOMER_ID', document_id = 'DOCUMENT_ID')
curl -X DELETE http://www.inscribe.ai/api/v1/customers/{customer_name}/documents/{document_id} \
 -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "success": true,
  "message": "Document was successfully deleted"
}

HTTP Request

DELETE /api/v1/customers/{customer_name}/documents/{document_id}

Parameters

Name Located in Description Required Type
customer_id path name of customer yes string
document_id path id of document yes string

Responses

Code Description
200 successful operation

Blacklists

Fraudulent customers often use the same names, addresses and phone numbers across applications. To avoid missing a reapplication of a fraudulent customer you can add their details to the blacklist. The results of this method are returned in the Check Document response.

Add New Blacklist Entry

Summary: Create blacklist entry

Description: If you would like to add a new blacklist entry you can use this API endpoint. For each entry, you can provide details (name, address, or phone number) that you would like Inscribe to look out for in the future. Going forward, all documents will be scanned for these details and you will be alerted in the Check Document response if the same details appear.

You can also add new blacklist entries or large CSV/Excel files by passing a file object ("csv", "xlsx", "xls") in the request.

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
api.create_blacklist_entry(name="BLACKLISTED_NAME", phone = "BLACKLISTED_PHONE", address="BLACKLISTED_ADDRESS")
curl http://www.inscribe.ai/api/v1/blacklist \
 -H "Authorization: YOUR_API_KEY" \ 
 -d '{"name": "BLACKLISTED_NAME", "phone": "BLACKLISTED_PHONE", "address": "BLACKLISTED_ADDRESS"}'

The above command returns JSON structured like this:

{
  "message": "Entry was successfully created", 
  "success": true, 
  "entry": {
    "name": "BLACKLISTED_NAME", 
    "phone": "BLACKLISTED_PHONE", 
    "address": "BLACKLISTED_ADDRESS"}
}

HTTP Request

POST /api/v1/blacklist

Parameters

Name Located in Description Required Type
blacklist entry body blacklist entry to add yes

Responses

Code Description
200 successful operation

Get All Blacklist Entries

Summary: Return all blacklist entries

Description: This method returns all blacklist entries which is useful if you would like to examine what is being search for.

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
api.get_blacklist()

curl http://www.inscribe.ai/api/v1/blacklist \
 -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "success": true,
  "blacklist": [
    {
      "id": 1,
      "address": "BLACKLISTED_ADDRESS",
      "name": "BLACKLISTED_NAME",
      "phone": "BLACKLISTED_PHONE"
    },
    {
      "id": 2,
      "address": "BLACKLISTED_ADDRESS",
      "name": "BLACKLISTED_NAME",
      "phone": "BLACKLISTED_PHONE"
    },
    {
      "id": 3,
      "address": "BLACKLISTED_ADDRESS",
      "name": "BLACKLISTED_NAME",
      "phone": "BLACKLISTED_PHONE"
    }
  ]
}

HTTP Request

GET /api/v1/blacklist

Responses

Code Description
200 successful operation

Update Blacklist Entry

Summary: Update blacklist entry

Description: This method allows you to update a blacklist entry that already exists.

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
api.update_blacklist_entry(blacklist_id = "BLACKLIST_ID", name="BLACKLISTED_NAME", phone = "BLACKLISTED_PHONE", address="BLACKLISTED_ADDRESS")
curl http://www.inscribe.ai/api/v1/blacklist/{blacklist_id} \
 -H "Authorization: YOUR_API_KEY" \ 
 -d '{"name": "BLACKLISTED_NAME", "phone": "BLACKLISTED_PHONE", "address": "BLACKLISTED_ADDRESS"}'

The above command returns JSON structured like this:

{
  "message": "Entry was successfully updated", 
  "success": true, 
  "entry": {
    "name": "BLACKLISTED_NAME", 
    "phone": "BLACKLISTED_PHONE", 
    "address": "BLACKLISTED_ADDRESS"}
}

HTTP Request

POST /api/v1/blacklist/{blacklist_id}

Parameters

Name Located in Description Required Type
blacklist_id path blacklist id yes integer
blacklist entry body blacklist entry to update yes

Responses

Code Description
200 successful operation

Delete Blacklist Entry

Summary: Delete blacklist entry

Description: This method allows you to delete a blacklist entry. This is useful if you find you no longer need to search for a particular identity or if you mistakenly added incorrect details.

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
api.delete_blacklist_entry(blacklist_id = "BLACKLIST_ID")

curl -X DELETE http://www.inscribe.ai/api/v1/blacklist/{blacklist_id} \
 -H "Authorization: YOUR_API_KEY" 

The above command returns JSON structured like this:

{
  "message": "Entry was successfully deleted", 
  "success": true
}

HTTP Request

DELETE /api/v1/blacklist/{blacklist_id}

Parameters

Name Located in Description Required Type
blacklist_id path blacklist id yes integer

Responses

Code Description
200 successful operation

Templates

Fraudulent documents are often created by modifying a real or fake document which is used as a template. This templating feature allows you to scan new documents to check if they match a previously used template. The results of this method are returned in the Check Document response.

Add New Template

Summary: Add a new template

Description: Use this API endpoint to add a new template document. The document can be either in PDF, PNG or JPG format.

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
api.upload_template(document="TEMPLATE_FILE")
curl http://www.inscribe.ai/api/v1/templates
  -H "Authorization: YOUR_API_KEY" 
  -F -F {document_filename}{.pdf, .png, .jpg}@/{document_file_path}

The above command returns JSON structured like this:

{
  "message": "Successfully uploaded template.",
    "status": 202,
    "success": true,
    "template": {
        "filename": "bank_statement_forgery.pdf",
        "id": 97,
        "template_text": "1111 Walnut Drive\nSan Francisco, CA\n\nJane Customer\n1234 Anywhere Dr.\nSmall Town, MO 3.14159 ..."
    }
}

HTTP Request

POST /api/v1/templates

Parameters

Name Located in Description Required Type
template body templates document to add yes

Responses

Code Description
200 successful operation

Get Template

Summary: Returns specific templates

Description: This method returns a specific template.

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
api.get_template(template_id="TEMPLATE_ID")
curl http://www.inscribe.ai/api/v1/templates/{template_id}
  -H "Authorization: YOUR_API_KEY" 

The above command returns JSON structured like this:

{
  "success": true,
  "templates": [
    {"filename": "forged_utility_bill_1.png",
       "id": 1,
       "template_text": "1111 Walnut Drive\nSan Francisco, CA\n\nJane Customer\n1234 Anywhere Dr.\nSmall Town, MO ..."}
  ]
}

HTTP Request

GET /api/v1/templates/{template_id}

Parameters

Name Located in Description Required Type
template_id path template id yes integer

Responses

Code Description
200 successful operation

Get All Templates

Summary: Return all templates

Description: This method returns all templates which is useful if you would like to examine what is being search for.

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
api.get_all_templates()
curl http://www.inscribe.ai/api/v1/templates
  -H "Authorization: YOUR_API_KEY" 

The above command returns JSON structured like this:

{
  "success": true,
  "templates": [
    {"filename": "forged_utility_bill_1.png",
       "id": 1,
       "template_text": "1111 Walnut Drive\nSan Francisco, CA\n\nJane Customer\n1234 Anywhere Dr.\nSmall Town, MO ..."},
    {"filename": "forged_bank_statement_1.pdf",
       "id": 2,
       "template_text": "Total Deposits & Other Credits $3,615.08\n\nATM Withdrawals & Debits Account ... "}
  ]
}

HTTP Request

GET /api/v1/templates

Responses

Code Description
200 successful operation

Delete Template

Summary: Delete template document

Description: This method allows you to delete a template. This is useful if you find you no longer need to search for a particular template or if you mistakenly added a template.

import inscribe

api = inscribe.Client(api_key='YOUR_API_KEY')
api.delete_template(template_id="TEMPLATE_ID")
curl -X DELETE http://www.inscribe.ai/api/v1/templates/{template_id} \
  -H "Authorization: YOUR_API_KEY" 

HTTP Request

DELETE /api/v1/templates/{template_id}

Parameters

Name Located in Description Required Type
template_id path template id yes integer

Responses

Code Description
200 successful operation

Errors

The Inscribe API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The item requested is hidden for administrators only.
404 Not Found -- The specified item could not be found.
405 Method Not Allowed -- You tried to access a item with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The item requested has been removed from our servers.
429 Too Many Requests -- You're requesting too many items! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.