MIMS SDK
Get Started

SDK Endpoints

These endpoints are designed specifically for SDK integration and support client-side API keys.

Authentication

All SDK endpoints accept both public (pk_*) and secret (sk_*) API keys via the X-API-Key header.

Validate API Key

POST/sdk/validate-key

Validates the API key and returns organization information and granted scopes.

Request

No request body required. The API key is read from the X-API-Key header.

cURLbash
curl -X POST https://api.mims-tech.com/sdk/validate-key \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Response

Success Responsejson
{
  "valid": true,
  "organizationId": "org_abc123",
  "organizationName": "Acme Corporation",
  "scopes": [
    "documents:read",
    "documents:submit"
  ],
  "expiresAt": "2025-01-15T00:00:00Z"
}
Error Responsejson
{
  "valid": false,
  "error": "API key has expired"
}

Response Fields

PropTypeDefaultDescription
validrequiredboolean—Whether the API key is valid.
organizationIdstring—The organization ID associated with the key.
organizationNamestring—The organization name.
scopesstring[]—Array of permission scopes granted to the key.
expiresAtstring—ISO 8601 expiration date, if applicable.
errorstring—Error message if validation failed.

Get Document

GET/sdk/documents/:documentId

Retrieves document metadata, PDF URL, and predefined fields for display in the viewer.

Path Parameters

PropTypeDefaultDescription
documentIdrequiredstring—The unique document identifier.

Request

cURLbash
curl -X GET https://api.mims-tech.com/sdk/documents/doc_abc123 \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx"

Response

Success Responsejson
{
  "metadata": {
    "id": "doc_abc123",
    "filename": "contract.pdf",
    "mimeType": "application/pdf",
    "pageCount": 5,
    "fileSize": 245678,
    "createdAt": "2024-01-10T09:00:00Z",
    "updatedAt": "2024-01-10T09:00:00Z",
    "version": 1
  },
  "documentUrl": "https://cdn.mims-tech.com/documents/doc_abc123.pdf?token=xxx",
  "fields": [
    {
      "id": "field_name",
      "type": "text",
      "page": 1,
      "x": 0.15,
      "y": 0.25,
      "width": 0.4,
      "height": 0.04,
      "required": true,
      "editable": true,
      "label": "Full Name",
      "placeholder": "Enter your full name"
    },
    {
      "id": "field_signature",
      "type": "signature",
      "page": 5,
      "x": 0.1,
      "y": 0.8,
      "width": 0.35,
      "height": 0.1,
      "required": true,
      "editable": true,
      "label": "Signature"
    }
  ]
}

Required Scope

documents:read

Submit Document

POST/sdk/documents/submit

Submits a completed document with all field values for processing.

Request Body

Request Bodyjson
{
  "documentId": "doc_abc123",
  "submittedAt": "2024-01-15T10:30:00Z",
  "renderContext": {
    "scale": 1,
    "viewportWidth": 800,
    "viewportHeight": 1000,
    "devicePixelRatio": 2
  },
  "pages": [
    {
      "pageNumber": 1,
      "width": 612,
      "height": 792,
      "rotation": 0
    }
  ],
  "fields": [
    {
      "id": "field_name",
      "type": "text",
      "page": 1,
      "position": {
        "x": 0.15,
        "y": 0.25,
        "width": 0.4,
        "height": 0.04
      },
      "value": {
        "type": "text",
        "content": "John Doe"
      },
      "style": {
        "fontSize": 12,
        "fontFamily": "Helvetica",
        "textAlign": "left"
      }
    },
    {
      "id": "field_signature",
      "type": "signature",
      "page": 5,
      "position": {
        "x": 0.1,
        "y": 0.8,
        "width": 0.35,
        "height": 0.1
      },
      "value": {
        "type": "signature",
        "imageData": "data:image/png;base64,iVBORw0KGgo..."
      }
    }
  ],
  "checksum": "a1b2c3d4"
}

Response

Success Responsejson
{
  "success": true,
  "submissionId": "sub_xyz789",
  "documentId": "doc_abc123",
  "timestamp": "2024-01-15T10:30:01Z",
  "message": "Document submitted successfully"
}

Request Fields

PropTypeDefaultDescription
documentIdrequiredstring—The document being submitted.
submittedAtrequiredstring—ISO 8601 timestamp of submission.
renderContextrequiredRenderContext—Viewport information at submission time.
pagesrequiredPageInfo[]—Array of page information.
fieldsrequiredSubmittedField[]—Array of completed fields with values.
checksumrequiredstring—Client-generated integrity hash.

Required Scope

documents:submit

Validation

The API validates that all required fields have values. Missing required fields will result in a 422 error with details about which fields are incomplete.

SDK Usage Examples

Using the SDK's apiRequest method:

SDK Examplestsx
import { useSDK } from '@mims/sdk-react';

function DocumentOperations() {
  const { apiRequest } = useSDK();

  // Validate key (called automatically by MIMSProvider)
  const validateKey = async () => {
    const result = await apiRequest<ApiKeyValidationResponse>(
      '/sdk/validate-key',
      { method: 'POST' }
    );
    console.log('Valid:', result.valid);
  };

  // Get document
  const getDocument = async (documentId: string) => {
    const doc = await apiRequest<DocumentWithFields>(
      `/sdk/documents/${documentId}`
    );
    return doc;
  };

  // Submit document
  const submitDocument = async (payload: DocumentSubmissionPayload) => {
    const result = await apiRequest<SubmissionResponse>(
      '/sdk/documents/submit',
      {
        method: 'POST',
        body: JSON.stringify(payload),
      }
    );
    return result;
  };

  return null;
}

Error Responses

Invalid API Key (401)

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}

Document Not Found (404)

{
  "success": false,
  "error": {
    "code": "DOCUMENT_NOT_FOUND",
    "message": "Document with ID 'doc_xxx' not found"
  }
}

Validation Error (422)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Required fields are missing values",
    "details": {
      "missingFields": ["field_signature", "field_date"]
    }
  }
}

Related