Certificates API

The Certificates API handles pharmaceutical compliance certificates including Certificates of Analysis (CoA), Certificates of Conformity (CoC), GMP certificates, and supplier qualification documents.

Certificate Model

{
  "id": "cert_abc123def456",
  "type": "coa",
  "name": "CoA - Magnesium Stearate - Batch 2024-001",
  "status": "valid",
  "supplier_id": "ent_supplier_789",
  "component_id": "ent_component_456",
  "batch_number": "2024-001",
  "issue_date": "2024-01-15",
  "expiry_date": "2026-01-15",
  "document": {
    "file_id": "file_xyz789",
    "filename": "coa_mag_stearate_2024001.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 245678,
    "checksum": "sha256:abc123..."
  },
  "extracted_data": {
    "test_results": [
      {
        "parameter": "Assay",
        "specification": "98.0 - 102.0%",
        "result": "99.5%",
        "status": "pass"
      },
      {
        "parameter": "Heavy Metals",
        "specification": "< 10 ppm",
        "result": "< 5 ppm",
        "status": "pass"
      }
    ],
    "manufacturing_date": "2024-01-10",
    "manufacturer": "Acme Chemicals GmbH"
  },
  "validation": {
    "validated_at": "2024-01-16T10:30:00Z",
    "validated_by": "user_quality_123",
    "validation_notes": "All specifications met"
  },
  "created_at": "2024-01-15T14:00:00Z",
  "updated_at": "2024-01-16T10:30:00Z"
}

Certificate Types

Type	Description
coa	Certificate of Analysis
coc	Certificate of Conformity
gmp	GMP Certificate
iso	ISO Certification
qualification	Supplier Qualification Document
audit	Audit Report

Certificate Status

Status	Description
pending	Awaiting validation
valid	Validated and current
expiring_soon	Valid but expiring within 90 days
expired	Past expiry date
rejected	Failed validation
superseded	Replaced by newer certificate

Upload Certificate

Upload a new certificate document.

POST /v1/certificates

Note

Certificates are uploaded using multipart/form-data. Include the file and metadata in a single request.

Request

curl

curl -X POST "https://api.cohera.io/v1/certificates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/coa_document.pdf" \
  -F 'metadata={
    "type": "coa",
    "name": "CoA - Magnesium Stearate - Batch 2024-001",
    "supplier_id": "ent_supplier_789",
    "component_id": "ent_component_456",
    "batch_number": "2024-001",
    "issue_date": "2024-01-15",
    "expiry_date": "2026-01-15"
  }'

Python

import requests

metadata = {
    "type": "coa",
    "name": "CoA - Magnesium Stearate - Batch 2024-001",
    "supplier_id": "ent_supplier_789",
    "component_id": "ent_component_456",
    "batch_number": "2024-001",
    "issue_date": "2024-01-15",
    "expiry_date": "2026-01-15"
}

with open("/path/to/coa_document.pdf", "rb") as f:
    response = requests.post(
        "https://api.cohera.io/v1/certificates",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        files={"file": ("coa_document.pdf", f, "application/pdf")},
        data={"metadata": json.dumps(metadata)}
    )

certificate = response.json()["data"]
print(f"Certificate ID: {certificate['id']}")
print(f"Status: {certificate['status']}")

TypeScript

const metadata = {
  type: "coa",
  name: "CoA - Magnesium Stearate - Batch 2024-001",
  supplier_id: "ent_supplier_789",
  component_id: "ent_component_456",
  batch_number: "2024-001",
  issue_date: "2024-01-15",
  expiry_date: "2026-01-15",
};

const formData = new FormData();
formData.append("file", fileBlob, "coa_document.pdf");
formData.append("metadata", JSON.stringify(metadata));

const response = await fetch("https://api.cohera.io/v1/certificates", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
  },
  body: formData,
});

const { data: certificate } = await response.json();
console.log(`Certificate ID: ${certificate.id}`);
console.log(`Status: ${certificate.status}`);

Response

{
  "data": {
    "id": "cert_abc123def456",
    "type": "coa",
    "name": "CoA - Magnesium Stearate - Batch 2024-001",
    "status": "pending",
    "supplier_id": "ent_supplier_789",
    "component_id": "ent_component_456",
    "batch_number": "2024-001",
    "issue_date": "2024-01-15",
    "expiry_date": "2026-01-15",
    "document": {
      "file_id": "file_xyz789",
      "filename": "coa_document.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 245678
    },
    "created_at": "2024-01-15T14:00:00Z"
  }
}

AI-Powered Data Extraction

After upload, Cohera’s AI agent automatically extracts data from the certificate. You can also trigger extraction manually.

POST /v1/certificates/{certificate_id}/extract

curl

curl -X POST "https://api.cohera.io/v1/certificates/cert_abc123/extract" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

response = requests.post(
    f"https://api.cohera.io/v1/certificates/{certificate_id}/extract",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

extracted = response.json()["data"]["extracted_data"]
print(f"Found {len(extracted['test_results'])} test results")

TypeScript

const response = await fetch(
  `https://api.cohera.io/v1/certificates/${certificateId}/extract`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
    },
  }
);

const { data } = await response.json();
console.log(`Found ${data.extracted_data.test_results.length} test results`);

Extraction Response

{
  "data": {
    "certificate_id": "cert_abc123",
    "extraction_status": "complete",
    "confidence_score": 0.95,
    "extracted_data": {
      "test_results": [
        {
          "parameter": "Assay",
          "specification": "98.0 - 102.0%",
          "result": "99.5%",
          "status": "pass",
          "confidence": 0.98
        },
        {
          "parameter": "Heavy Metals",
          "specification": "< 10 ppm",
          "result": "< 5 ppm",
          "status": "pass",
          "confidence": 0.96
        },
        {
          "parameter": "Loss on Drying",
          "specification": "< 2.0%",
          "result": "0.8%",
          "status": "pass",
          "confidence": 0.94
        }
      ],
      "batch_number": "2024-001",
      "manufacturing_date": "2024-01-10",
      "manufacturer": "Acme Chemicals GmbH",
      "manufacturing_site": "Hamburg, Germany"
    },
    "extracted_at": "2024-01-15T14:05:00Z"
  }
}

Validate Certificate

Validate a certificate and update its status.

POST /v1/certificates/{certificate_id}/validate

Request Body

Field	Type	Required	Description
status	string	Yes	New status (valid or rejected)
notes	string	No	Validation notes
overrides	object	No	Manual corrections to extracted data

curl

curl -X POST "https://api.cohera.io/v1/certificates/cert_abc123/validate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "valid",
    "notes": "All specifications met. Verified against component specification CS-2024-001.",
    "overrides": {
      "test_results": [
        {
          "parameter": "Assay",
          "result": "99.6%"
        }
      ]
    }
  }'

Python

response = requests.post(
    f"https://api.cohera.io/v1/certificates/{certificate_id}/validate",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "status": "valid",
        "notes": "All specifications met.",
        "overrides": {
            "test_results": [
                {"parameter": "Assay", "result": "99.6%"}
            ]
        }
    }
)

certificate = response.json()["data"]
print(f"Validation complete: {certificate['status']}")

TypeScript

const response = await fetch(
  `https://api.cohera.io/v1/certificates/${certificateId}/validate`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "valid",
      notes: "All specifications met.",
      overrides: {
        test_results: [{ parameter: "Assay", result: "99.6%" }],
      },
    }),
  }
);

const { data: certificate } = await response.json();
console.log(`Validation complete: ${certificate.status}`);

Audit Trail

All validation actions are recorded in the audit log, including the user who performed the validation and any manual overrides applied.

List Certificates

Retrieve certificates with filtering and pagination.

GET /v1/certificates

Query Parameters

Parameter	Type	Description
type	string	Filter by certificate type
status	string	Filter by status
supplier_id	string	Filter by supplier
component_id	string	Filter by component
batch_number	string	Filter by batch
expiring_before	date	Certificates expiring before date
expiring_within_days	integer	Certificates expiring within N days

Example: Find Expiring Certificates

curl

curl -X GET "https://api.cohera.io/v1/certificates?expiring_within_days=90&status=valid" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

response = requests.get(
    "https://api.cohera.io/v1/certificates",
    params={
        "expiring_within_days": 90,
        "status": "valid"
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

expiring = response.json()["data"]
print(f"Found {len(expiring)} certificates expiring within 90 days")

for cert in expiring:
    print(f"  - {cert['name']} expires {cert['expiry_date']}")

TypeScript

const params = new URLSearchParams({
  expiring_within_days: "90",
  status: "valid",
});

const response = await fetch(
  `https://api.cohera.io/v1/certificates?${params}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
    },
  }
);

const { data: expiring } = await response.json();
console.log(`Found ${expiring.length} certificates expiring within 90 days`);

expiring.forEach((cert) => {
  console.log(`  - ${cert.name} expires ${cert.expiry_date}`);
});

Get Certificate

Retrieve a single certificate by ID.

GET /v1/certificates/{certificate_id}

Download Certificate Document

Download the original certificate document.

GET /v1/certificates/{certificate_id}/document

Returns the binary file content with appropriate Content-Type and Content-Disposition headers.

curl

curl -X GET "https://api.cohera.io/v1/certificates/cert_abc123/document" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o certificate.pdf

Python

response = requests.get(
    f"https://api.cohera.io/v1/certificates/{certificate_id}/document",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

with open("certificate.pdf", "wb") as f:
    f.write(response.content)

TypeScript

const response = await fetch(
  `https://api.cohera.io/v1/certificates/${certificateId}/document`,
  {
    headers: {
      Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
    },
  }
);

const blob = await response.blob();
// Save or process the blob

Expiry Tracking

Get Expiry Summary

GET /v1/certificates/expiry-summary

Returns a summary of certificate expiry status across your organization.

Response

{
  "data": {
    "total": 1250,
    "by_status": {
      "valid": 1100,
      "expiring_soon": 85,
      "expired": 45,
      "pending": 20
    },
    "expiring_by_period": {
      "30_days": 25,
      "60_days": 45,
      "90_days": 85
    },
    "by_type": {
      "coa": {"total": 800, "expiring_soon": 50},
      "coc": {"total": 300, "expiring_soon": 25},
      "gmp": {"total": 100, "expiring_soon": 8},
      "iso": {"total": 50, "expiring_soon": 2}
    }
  }
}

Configure Expiry Alerts

Configure automated notifications for expiring certificates.

POST /v1/certificates/expiry-alerts

{
  "rules": [
    {
      "days_before_expiry": 90,
      "notify": ["quality-team@company.com"],
      "certificate_types": ["gmp", "iso"]
    },
    {
      "days_before_expiry": 30,
      "notify": ["quality-team@company.com", "procurement@company.com"],
      "certificate_types": ["coa", "coc"]
    }
  ]
}

Certificate History

View the complete history of a certificate including uploads, validations, and status changes.

GET /v1/certificates/{certificate_id}/history

Response

{
  "data": [
    {
      "action": "validated",
      "timestamp": "2024-01-16T10:30:00Z",
      "user": "user_quality_123",
      "details": {
        "status_from": "pending",
        "status_to": "valid",
        "notes": "All specifications met"
      }
    },
    {
      "action": "extracted",
      "timestamp": "2024-01-15T14:05:00Z",
      "user": "system",
      "details": {
        "extraction_confidence": 0.95,
        "test_results_count": 8
      }
    },
    {
      "action": "uploaded",
      "timestamp": "2024-01-15T14:00:00Z",
      "user": "user_intake_456",
      "details": {
        "filename": "coa_document.pdf",
        "file_size": 245678
      }
    }
  ]
}