ClerkAI

ClerkAI Compliance API Documentation

This documentation provides details on the ClerkAI Compliance API, which allows users to submit claims for compliance analysis, check processing status, and retrieve results.

Authentication

All API endpoints require the following headers:

  • userid: Your registered user ID
  • x-api-key: Your API key provided by ClerkAI

Authentication failures result in a 401 (missing headers) or 403 (invalid credentials) status code.

Additionally, all endpoints verify that the user has an active subscription before processing requests.

API Endpoints

1. Upload Batch Claims

Endpoint:/ingestion
Method:
POST
Content-Type:multipart/form-data

Query Parameters:

  • autoprocess - Set to yes to automatically process the uploaded claims (optional)

Request Body:

{
  "document_id": "unique_document_id",
  "content": "document content or reference",
  "metadata": "additional information"
}

Response:

{
  "message": "Claims submit successfully to the system",
  "batch_id": "b8f9c6d7-e5a4-4b3c-9d2e-1f0a7b6c5d4e",
  "duplicate_docIDs": ["doc123", "doc456"]
}

2. Submit Single Claim

Endpoint:/compliance
Method:
POST
Content-Type:application/json

Request Body:

{
  "claim_id": "existing_claim_id"
}

Response:

{
  "message": "Message sent to SQS successfully",
  "messageId": "12345678-1234-1234-1234-123456789012"
}

3. Check Claim Status

Endpoint:/status
Method:
GET

Query Parameters:

  • document_id: ID of a specific document
  • batch_id: ID of a batch (takes precedence if both parameters are provided)

Response for Single Document:

{
  "doc123": "in-progress"
}

Response for Batch:

{
  "doc123": "completed",
  "doc456": "in-progress",
  "doc789": "created"
}

4. Retrieve Processing Results

Endpoint:/results
Method:
GET

Query Parameters:

  • document_id: ID of a specific document
  • batch_id: ID of a batch (takes precedence if both parameters are provided)

Response for Single Document:

{
  "doc123": {
    "compliance_score": 0.85,
    "issues": [
      {
        "type": "missing_field",
        "description": "Required field 'X' is missing"
      }
    ]
  }
}

Response for Batch:

{
  "doc123": {
    "compliance_score": 0.85,
    "issues": [...]
  },
  "doc456": {
    "compliance_score": 0.92,
    "issues": [...]
  }
}

Error Responses

400
Bad Request

{
  "error": "Missing document_id or batch_id parameters"
}

401
Unauthorized

{
  "error": "Missing userid"
}

403
Forbidden

{
  "error": "Userid or API key is incorrect. Access Denied."
}
{
  "error": "The user is not permitted for service use. Access Denied."
}
{
  "error": "ClaimID belongs to the different user. Access Denied."
}

404
Not Found

{
  "error": "Claim not found"
}

405
Method Not Allowed

{
  "error": "Method not allowed"
}

500
Internal Server Error

{
  "error": "Error details"
}

Workflow Example

  1. Upload a batch of claims using /ingestion with autoprocess=yes
  2. Track processing status using /status?batch_id=YOUR_BATCH_ID
  3. Once all claims are processed, retrieve results using /results?batch_id=YOUR_BATCH_ID

For individual claims, you can use the document ID for status and result retrieval.

Security Notes

  • All API calls must be made over HTTPS
  • Your API key should be kept confidential and not shared
  • The system verifies that you only access your own claims