Authentication Requirements

Every request must include the following headers:

• X-Api-Key: Your public API key.
• X-Timestamp: The current UNIX timestamp.
• X-Signature: A signature generated using your secret key and the timestamp.

For more details on generating signatures, refer to the Signature Generation section.

Response Structure

The following response structures are used in the API:

• Success: For successful requests:

  
  {
    "message": "ok", //  Or a more detailed success message
    "data": { ... } // Response data specific to the endpoint
  }
                  

• Error: For requests that fail due to logical errors or exceptions:

  
  {
    "generalErrors": [
      "Error message 1",
      "Error message 2"
    ],
    "fieldErrors": []
  }
                  

  General Errors: A list of general error messages.

  Field Errors: A list of field-specific errors with the field name and corresponding error message.

• Validation Errors: For validation failures:

  
  {
    "generalErrors": [],
    "fieldErrors": [
      {
        "field": "email",
        "message": "This value is not a valid email address."
      },
      {
        "field": "token",
        "message": "This value should not be blank."
      }
    ]
  }
                  

  Validation errors use the same structure as general errors, with detailed field-specific error messages.

• HTML Views: For endpoints returning rendered HTML (e.g., wizards or interfaces):

  
  HTTP/1.1 200 OK
  Content-Type: text/html
  
    
  
                  

Endpoint Details

Parameters

Success Response

{
  "message": "ok",
  "data": {
    "token": "UNIQUE_DOCUMENT_TOKEN"
  }
}
            

The response includes a unique token to identify the uploaded document. Keep this token for use in subsequent requests.

Identity in Usage Section

If the identity parameter is provided, it will appear in Account → Usage to help you track the analysis.

Endpoint Details

Parameters

Success Response

{
  "message": "ok",
  "data": {
    "tables": [
      [
        ["Cell 1-1", "Cell 1-2"],
        ["Cell 2-1", "Cell 2-2"]
      ],
      [
        ["Another Cell 1-1", "Another Cell 1-2"]
      ]
    ]
  }
}
            

The response contains a list of tables extracted from the document. Each table is represented as a 2D array of rows and columns.

Pending Response

{
  "message": "The analysis is still in progress. Please try again in a few moments.",
  "data": {}
}
            

If the analysis is not yet complete, the server will return this response with a status code of 202 Accepted.

Result Retention

Analysis results are stored on the server and available for download for 7 days after the analysis completion. After this period, the results are automatically deleted and a new document upload and analysis will be required.

Endpoint Details

Parameters

How to Integrate

The wizard endpoint requires valid signatures and headers, so you cannot simply point an <iframe> directly to it. Instead:

1. Use your backend to generate a valid signature and fetch the wizard's HTML using those credentials.
2. Insert the retrieved HTML into your iframe using srcdoc.
3. Handle communication with the wizard via window.postMessage. This includes responding to signature requests and handling product selections.

Here’s an example flow:

• You fetch the wizard’s HTML from /api/document/analysis-wizard (with proper authentication) and store it in a variable iframeContent.
• You set srcdoc={iframeContent} on your iframe to render the wizard.
• When the wizard needs a new signature, it sends a REQUEST_SIGNATURE event to your window. You then call your backend to get a fresh signature and reply with NEW_SIGNATURE.
• Once the user selects products at Step 3 and clicks "Confirm Selection", the wizard sends a PRODUCTS_SELECTED event. At this point, you have the chosen products and can decide how to proceed. If you close the wizard now, the process ends here. If you let the user continue, they reach Step 4 in the wizard.
• At Step 4, if the user chooses "Add to Cart", the wizard sends a PRODUCTS_SELECTION_CONFIRMED event. This typically indicates the final confirmation of the selected products, allowing you to add them to the cart or finalize the process.

<!-- Example Iframe: Insert the fetched wizard HTML via srcdoc -->
<iframe
        id="analysisWizard"
        srcdoc="{your-injected-html-here}"
></iframe>

// Set up communication handlers
let wizardWindow = null;

// Once the iframe loads, store its window reference
document.getElementById('analysisWizard').onload = function() {
  wizardWindow = this.contentWindow;
};

// Handle events from the wizard
window.addEventListener('message', async (event) => {
  if (!wizardWindow || event.source !== wizardWindow) return;

  switch (event.data.type) {
    case 'REQUEST_SIGNATURE':
      // Wizard needs a new signature (e.g., token expired)
      try {
        const response = await fetch('/your-signature-endpoint', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' }
        });
        const { signature, timestamp } = await response.json();

        // Reply with NEW_SIGNATURE so the wizard can continue
        wizardWindow.postMessage({
          type: 'NEW_SIGNATURE',
          signature,
          timestamp
        }, '*');
      } catch (error) {
        console.error('Failed to generate signature:', error);
      }
      break;

    case 'PRODUCTS_SELECTED':
      // User finished selecting products at Step 3
      const selectedProducts = event.data.products;
      console.log('Products selected:', selectedProducts);
      // Here you can decide:
      // - Close the wizard and use these products immediately
      // - Or let the user proceed to step 4 by leaving the wizard open
      break;

    case 'PRODUCTS_SELECTION_CONFIRMED':
      // User confirmed selection at Step 4 (e.g., clicked "Add to Cart")
      const confirmedProducts = event.data.products;
      console.log('Products selection confirmed:', confirmedProducts);

      // Add products to cart or perform another final action
      try {
        await addProductsToCart(confirmedProducts);
        showSuccessMessage('Products added to cart successfully!');
      } catch (error) {
        showErrorMessage('Failed to add products to cart');
      }
      break;
  }
});

// Helper functions
function showSuccessMessage(message) {
  // Display success notification
}

function showErrorMessage(message) {
  // Display error notification
}

async function addProductsToCart(products) {
  // Implement your cart addition logic
}

Endpoint Details

Success Response

{
  "message": "ok",
  "data": {
    "availablePages": 1000,
    "hasSubscription": true
  }
}
        

The response contains the number of available pages the user can use and whether the user has an active subscription.