API Example: Uploading a document

This guide will show you how to use DocIntel’s API to upload a new document to the platform. To upload a document, you will need to create a new document and then upload a file to it. You will also need to obtain a Bearer token to authenticate your requests. This guide will walk you through each step in detail.

Step 1: Obtaining a Bearer Token Before you can upload a document, you will need to obtain a Bearer token to authenticate your requests. To do this, you will need to provide your API key and username. Here’s an example of how to obtain a Bearer token using Python and the Requests library:

# Replace USERNAME with your actual username
USERNAME = "your_username"
# Replace API_KEY with your actual API key
API_KEY = "your_api_key_here"
# Replace API_BASE with the URL of the API endpoint you want to use
API_BASE = "https://[your-instance]/API"

url = f"{API_BASE}/Authentication/Login"

payload = {
    "username": f"{USERNAME}",
    "api_key": f"{API_KEY}"
}
headers = {
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

if response.status_code == 200:
    # Extract the token from the response
    token = response.json()["token"]
else:
    print("Failed to get token from API.")

Step 2: Creating a Document Once you have obtained a Bearer token, you can create a new document using the DocIntel API. To create a document, you will need to provide the document’s metadata, such as its name and description. Here’s an example of how to create a new document using Python and the Requests library:

url = f"{API_BASE}/Document"

payload = {
    "title": "My document",
    "shortDescription": "My description",
    "sourceUrl": "https://docintel.org"
}
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}
response = requests.request("POST", url, json=payload, headers=headers)


# Check if the request was successful
if response.status_code == 200:
    document = response.json()
    print(document)
else:
    print("Failed to create a document from API.")

If you want the document to be automatically registered and skip the pending list, or if you don’t want DocIntel to extract the structured data automatically, you can specify the following metadata information.

payload = {
    ...
    "metadata": {
        "extraction": {
            "structured_data": False
        },
        "registration": {
            "auto": True
        }
    }
}

Step 3: Uploading a File to the Document With the new document created, you can now upload a file to it using the DocIntel API. To upload a file, you will need to provide the file’s metadata, such as its name and MIME type, as well as the file’s binary data. Here’s an example of how to upload a file to a document using Python and the Requests library:

# Replace FILE_PATH with the path to the file you want to upload
FILE_PATH = "path/to/file"

url = f"{API_BASE}/Document/{document['documentId']}/Files"

# Read the binary data from the file
with open(FILE_PATH, "rb") as f:
    file_data = f.read()

headers = {
    "Content-Type": "application/pdf",
    "Authorization": f"Bearer {token}"
}

response = requests.request("POST", url, data=file_data, headers=headers)

# Check if the request was successful
if response.status_code == 200:
    file = response.json()
    print(file)
else:
    print("Failed to upload a file from API.")

Step 4: Updating the File Metadata After uploading the file, you can update its metadata, such as its name, using the DocIntel API. To update a file’s metadata, you will need to make a PATCH request to the /API/File/{file_id} endpoint, providing the updated metadata in the request body. Here’s an example of how to update a file’s metadata using Python and the Requests library:

url = f"{API_BASE}/File/{file['fileId']}"

payload = {"title": "My custom report"}
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}

response = requests.request("PATCH", url, json=payload, headers=headers)

# Check if the request was successful
if response.status_code == 200:
    file = response.json()
    print(file)
else:
    print("Failed to update a file from API.")

In conclusion, using the DocIntel API allows for seamless integration with your application, enabling you to create, manage, and share documents with ease. By following the steps outlined in this documentation page, you can upload a document and its associated files, as well as update the metadata associated with those files, all through the use of API requests. As you continue to use the API, keep in mind the different endpoints and parameters available to customize your integration with DocIntel.