Rest API (JSON)

This page describes the steps you need to take to integrate with the standard Metamaze API. This page serves as a tutorial.

This page describes the steps you need to take to integrate with the standard Metamaze API. This page serves as a tutorial. Connection through the API of Metamaze is possible via token authentication or mutual TLS certification. For technical details on how to implement it, see the Metamaze API documentation.

For this tutorial, we will use Postman to perform the API request.

API integration using token authentication

Step 1: Configure the input API and get a Bearer token

  1. Create (or refresh) a new Bearer token by clicking the two blue arrows

  2. Copy the Bearer token and store it for later use

  3. Click Save to store the generated Bearer token

Step 2: Find your organisationId and projectId

You can find the organisationId and projectId in the URL of e.g. the project settings:

Step 3: Base64 encode your document

To add documents to your JSON API request, you need to base64 encode them. In Linux and on Mac OS X, you can just run

> base64 <inputfile>

Tip: to immediately copy the base64 encoded file to your clipboard you can use > base64 <inputfile> | pbcopy

Step 4: Create your request to start processing

In Postman, create a new request.

  1. Change the type from GET to POST

  2. Set the request URL to https://app.metamaze.eu/gql/api/organisations/{{organisationId}}/projects/{{projectId}}/process where {{organisationId}} and {{projectId}} are the values from Step 2.

  3. Under the Authorization tab, choose Bearer Token as the type. Fill in the generated Bearer Token from Step 1.

  4. Under Body, change the type to raw and select JSON as the body format.

  5. Add the following request body where you replace {{base64 encoded file}} with the output from Step 3. You can add optional metadata too

{
  "files": [
    {
      "name": "mm-api-example.pdf",
      "id": "mm-api-example",
      "file": "{{base64 encoded file}}"
    }
  ],
  "metadata": {"example-key": "example-value"}
}

In Postman, you can click "Code" (top-right, under the Send and Save buttons) to quickly export your API call to the most popular programming languages immediately.

6. Click Send to send the request. You will receive a response like this with status code 200. Store the uploadId: you will need it to fetch the status and the results

Step 5: Create a new request to fetch the results

In Postman, create a new request.

  1. Set the request type as GET now.

  2. Set the request URL to https://app.metamaze.eu/gql/api/organisations/{{organisationId}}/projects/{{projectId}}/process/{{uploadId}} where {{organisationId}} and {{projectId}} are the values from Step 2, and {{uploadId}} is the ID you received in the response of Step 4.

  3. As above, add the Bearer Token authentication.

  4. Click Send to send the request and fetch the results.

  5. You will find the extracted values under documents[].aggregatedEntities.

Summary

In this tutorial, we showed the easiest way to integrate Metamaze. For other topics like receiving results immediately (push instead of pull), advanced authentication, restricting document types, uploading training data or adding metadata you can find information in the full API documentation.

Generating certificates for requests to Metamaze with mTLS

In the tutorial above, authentication was with a Bearer token. You might want to consider to add certificate-based authentication for an additional layer of security.

This guide provides step-by-step instructions on generating certificates using SSL for secure communication with Metamaze using mutual TLS (mTLS).

Step 1: Generating a key and a Certificate Signing Request (CSR)

To generate a key and a CSR, please follow the command given below:

openssl req -new -newkey rsa:4096 -keyout client.key -out client.csr -nodes -subj '/CN=*.metamaze.eu'

Keep your client.key file private and protected.

Step 2: Send the CSR to Metamaze Support to sign with our CA

After generating a CSR, you can open a support ticket via support@metamaze.eu or the information provided on Getting support. In that support ticket, include the client.csr file as an attachment and ask to sign it.

After verifying your information, Metamaze will sign the CSR and provide you with a signed certificate.

For reference, we will use a command similar to:

openssl x509 -req -sha256 -days 365 -in client.csr -CA mm_ca.crt -CAkey mm_ca.key -set_serial 02 -out client.crt

Step 3: Add the certificate content to Metamaze

After generating the client.crt file, you can paste the content of it in the Metamaze project settings > Input > REST API. The certificate should have the following structure:

---BEGIN CERTIFICATE---
...
---END CERTIFICATE---

Step 4: Test API calls in Postman

To configure Postman correctly with mTLS, follow these steps:

In Postman, navigate to Settings > Certificates and click "Add Certificate"

Enter the following information

  1. Add HOST *.metamaze.eu

  2. Add CRT file client.crt that was provided by Metamaze

  3. Add your KEY file client.key

  4. Leave PFX file empty

  5. (Optional) If you set a passphrase when generating the key, add the passphrase here too.

Postman automatically looks at the hostname of every API call to decide if client authentication is needed. By adding the host *.metamaze.eu, all API calls will be covered.

For testing purposes, we provide an endpoint at app.metamaze.eu/test-sslthat you can use. When sending a POST request to that endpoint with an empty body, you should receive a response similar to 

Fingerprint: [the sha1 fingerprint of certificate]
 Verified: SUCCESS 
 Subject: CN=*.metamaze.eu

Overview of files

At the end of the process, you will have the following files:

  • client.csr (not needed anymore, it was used for step 2 only)

  • client.key (use this to sign the request to Metamaze, keep this private)

  • client.crt (used to validate the request in Metamaze, to be pasted in the project settings.)

Please note that both the client.key and client.crt files are necessary for secure communication with Metamaze and should be kept securely.

Note that self-signed certificates are not supported. Certificates for client authentication using mTLS must be signed by the Metamaze Certificate Authority.

PreviousSFTPNextOCR

Last updated