Suppliers API

The Suppliers API provides specialized endpoints for managing pharmaceutical suppliers, tracking qualification status, and assessing supplier risk.

Supplier Model

Suppliers are entities with type supplier and additional supplier-specific attributes and relationships.

{
  "id": "ent_supplier_abc123",
  "type": "supplier",
  "name": "Acme Chemicals GmbH",
  "supplier_code": "SUP-2024-001",
  "attributes": {
    "country": "DE",
    "region": "EMEA",
    "qualification_status": "qualified",
    "qualification_date": "2024-01-15",
    "next_audit_date": "2025-01-15",
    "risk_level": "low",
    "risk_score": 25,
    "primary_contact": {
      "name": "Hans Mueller",
      "email": "h.mueller@acme-chemicals.de",
      "phone": "+49 40 1234567"
    },
    "address": {
      "street": "Industriestrasse 42",
      "city": "Hamburg",
      "postal_code": "20095",
      "country": "DE"
    },
    "certifications": ["ISO 9001", "ISO 14001", "GMP"],
    "categories": ["API", "Excipients"]
  },
  "relationships": [
    {
      "type": "supplies",
      "target_id": "ent_component_456",
      "target_name": "Magnesium Stearate"
    }
  ],
  "metrics": {
    "total_components": 12,
    "active_certificates": 45,
    "expiring_certificates": 3,
    "open_deviations": 1,
    "on_time_delivery_rate": 98.5
  },
  "created_at": "2024-01-10T09:00:00Z",
  "updated_at": "2024-01-20T14:30:00Z"
}

Qualification Status

Status	Description
`new`	Newly added, not yet evaluated
`evaluation`	Under evaluation
`qualified`	Approved for use
`conditional`	Approved with conditions
`suspended`	Temporarily suspended
`disqualified`	Not approved for use

Risk Levels

Level	Score Range	Description
`critical`	76-100	Immediate action required
`high`	51-75	Significant concerns
`medium`	26-50	Some concerns
`low`	0-25	Acceptable risk

List Suppliers

Retrieve suppliers with filtering.

GET /v1/suppliers

Query Parameters

Parameter	Type	Description
`qualification_status`	string	Filter by qualification status
`risk_level`	string	Filter by risk level
`country`	string	Filter by country code
`region`	string	Filter by region (EMEA, APAC, Americas)
`category`	string	Filter by supplier category
`has_expiring_certificates`	boolean	Suppliers with expiring certificates
`audit_due_before`	date	Suppliers with audits due before date

Example Request

curl -X GET "https://api.cohera.io/v1/suppliers?qualification_status=qualified&risk_level=low,medium" \
  -H "Authorization: Bearer YOUR_API_KEY"

response = requests.get(
    "https://api.cohera.io/v1/suppliers",
    params={
        "qualification_status": "qualified",
        "risk_level": "low,medium"
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

suppliers = response.json()["data"]
for supplier in suppliers:
    print(f"{supplier['name']} - Risk: {supplier['attributes']['risk_level']}")

const params = new URLSearchParams({
  qualification_status: "qualified",
  risk_level: "low,medium",
});

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

const { data: suppliers } = await response.json();
suppliers.forEach((supplier) => {
  console.log(`${supplier.name} - Risk: ${supplier.attributes.risk_level}`);
});

Get Supplier

Retrieve a single supplier with full details.

GET /v1/suppliers/{supplier_id}

Query Parameters

Parameter	Type	Description
`include`	string	Include related data: `components`, `certificates`, `quality_events`, `metrics`

curl -X GET "https://api.cohera.io/v1/suppliers/ent_supplier_abc123?include=components,certificates,metrics" \
  -H "Authorization: Bearer YOUR_API_KEY"

response = requests.get(
    f"https://api.cohera.io/v1/suppliers/{supplier_id}",
    params={"include": "components,certificates,metrics"},
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

supplier = response.json()["data"]
print(f"Supplier: {supplier['name']}")
print(f"Components: {len(supplier['components'])}")
print(f"On-time delivery: {supplier['metrics']['on_time_delivery_rate']}%")

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

const { data: supplier } = await response.json();
console.log(`Supplier: ${supplier.name}`);
console.log(`Components: ${supplier.components.length}`);
console.log(`On-time delivery: ${supplier.metrics.on_time_delivery_rate}%`);

Create Supplier

Create a new supplier.

POST /v1/suppliers

curl -X POST "https://api.cohera.io/v1/suppliers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PharmaChem Industries",
    "supplier_code": "SUP-2024-002",
    "attributes": {
      "country": "US",
      "region": "Americas",
      "primary_contact": {
        "name": "John Smith",
        "email": "j.smith@pharmachem.com",
        "phone": "+1 555 123 4567"
      },
      "address": {
        "street": "123 Industrial Blvd",
        "city": "Newark",
        "state": "NJ",
        "postal_code": "07102",
        "country": "US"
      },
      "categories": ["Excipients", "Packaging"]
    }
  }'

payload = {
    "name": "PharmaChem Industries",
    "supplier_code": "SUP-2024-002",
    "attributes": {
        "country": "US",
        "region": "Americas",
        "primary_contact": {
            "name": "John Smith",
            "email": "j.smith@pharmachem.com",
            "phone": "+1 555 123 4567"
        },
        "address": {
            "street": "123 Industrial Blvd",
            "city": "Newark",
            "state": "NJ",
            "postal_code": "07102",
            "country": "US"
        },
        "categories": ["Excipients", "Packaging"]
    }
}

response = requests.post(
    "https://api.cohera.io/v1/suppliers",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json=payload
)

supplier = response.json()["data"]
print(f"Created supplier: {supplier['id']}")

const payload = {
  name: "PharmaChem Industries",
  supplier_code: "SUP-2024-002",
  attributes: {
    country: "US",
    region: "Americas",
    primary_contact: {
      name: "John Smith",
      email: "j.smith@pharmachem.com",
      phone: "+1 555 123 4567",
    },
    address: {
      street: "123 Industrial Blvd",
      city: "Newark",
      state: "NJ",
      postal_code: "07102",
      country: "US",
    },
    categories: ["Excipients", "Packaging"],
  },
};

const response = await fetch("https://api.cohera.io/v1/suppliers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

const { data: supplier } = await response.json();
console.log(`Created supplier: ${supplier.id}`);

Update Qualification Status

Update a supplier’s qualification status with required documentation.

POST /v1/suppliers/{supplier_id}/qualification

Request Body

Field	Type	Required	Description
`status`	string	Yes	New qualification status
`effective_date`	date	Yes	Date the status takes effect
`reason`	string	Yes	Reason for status change
`next_review_date`	date	No	Next review or audit date
`conditions`	array	No	Conditions for conditional approval
`documents`	array	No	Supporting document IDs

curl -X POST "https://api.cohera.io/v1/suppliers/ent_supplier_abc123/qualification" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "qualified",
    "effective_date": "2024-01-20",
    "reason": "Successfully completed qualification audit. All criteria met.",
    "next_review_date": "2025-01-20",
    "documents": ["cert_audit_report_123"]
  }'

response = requests.post(
    f"https://api.cohera.io/v1/suppliers/{supplier_id}/qualification",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "status": "qualified",
        "effective_date": "2024-01-20",
        "reason": "Successfully completed qualification audit. All criteria met.",
        "next_review_date": "2025-01-20",
        "documents": ["cert_audit_report_123"]
    }
)

const response = await fetch(
  `https://api.cohera.io/v1/suppliers/${supplierId}/qualification`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "qualified",
      effective_date: "2024-01-20",
      reason: "Successfully completed qualification audit. All criteria met.",
      next_review_date: "2025-01-20",
      documents: ["cert_audit_report_123"],
    }),
  }
);

Risk Assessment

Get Risk Assessment

Retrieve the current risk assessment for a supplier.

GET /v1/suppliers/{supplier_id}/risk

Response

{
  "data": {
    "supplier_id": "ent_supplier_abc123",
    "risk_score": 25,
    "risk_level": "low",
    "assessment_date": "2024-01-15",
    "next_assessment_date": "2024-07-15",
    "factors": [
      {
        "category": "quality_history",
        "score": 5,
        "weight": 0.3,
        "weighted_score": 1.5,
        "details": "1 minor deviation in past 12 months"
      },
      {
        "category": "delivery_performance",
        "score": 10,
        "weight": 0.2,
        "weighted_score": 2.0,
        "details": "98.5% on-time delivery rate"
      },
      {
        "category": "financial_stability",
        "score": 15,
        "weight": 0.15,
        "weighted_score": 2.25,
        "details": "Stable financials, D&B rating: 4A1"
      },
      {
        "category": "geographic_risk",
        "score": 20,
        "weight": 0.15,
        "weighted_score": 3.0,
        "details": "Germany - low regulatory risk"
      },
      {
        "category": "single_source",
        "score": 50,
        "weight": 0.1,
        "weighted_score": 5.0,
        "details": "Sole supplier for 2 components"
      },
      {
        "category": "certification_status",
        "score": 10,
        "weight": 0.1,
        "weighted_score": 1.0,
        "details": "All certifications current"
      }
    ],
    "recommendations": [
      "Consider qualifying alternate supplier for single-source components",
      "Schedule next quality audit before 2025-01-15"
    ]
  }
}

Update Risk Assessment

Manually update or override risk assessment factors.

POST /v1/suppliers/{supplier_id}/risk

{
  "assessment_date": "2024-01-20",
  "factors": [
    {
      "category": "financial_stability",
      "score": 30,
      "details": "Recent acquisition - monitoring integration"
    }
  ],
  "notes": "Updated based on Q4 financial review"
}

Supplier Components

List Components

Get all components supplied by a supplier.

GET /v1/suppliers/{supplier_id}/components

curl -X GET "https://api.cohera.io/v1/suppliers/ent_supplier_abc123/components" \
  -H "Authorization: Bearer YOUR_API_KEY"

response = requests.get(
    f"https://api.cohera.io/v1/suppliers/{supplier_id}/components",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

components = response.json()["data"]
for component in components:
    print(f"{component['name']} - Primary: {component['is_primary_supplier']}")

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

const { data: components } = await response.json();
components.forEach((component) => {
  console.log(`${component.name} - Primary: ${component.is_primary_supplier}`);
});

Response

{
  "data": [
    {
      "id": "ent_component_456",
      "name": "Magnesium Stearate",
      "component_code": "COMP-001",
      "is_primary_supplier": true,
      "status": "active",
      "active_certificates": 5,
      "last_delivery": "2024-01-10"
    },
    {
      "id": "ent_component_789",
      "name": "Microcrystalline Cellulose",
      "component_code": "COMP-002",
      "is_primary_supplier": false,
      "status": "active",
      "active_certificates": 3,
      "last_delivery": "2024-01-05"
    }
  ]
}

Supplier Certificates

List Certificates

Get all certificates for a supplier.

GET /v1/suppliers/{supplier_id}/certificates

Query Parameters

Parameter	Type	Description
`type`	string	Filter by certificate type
`status`	string	Filter by certificate status
`component_id`	string	Filter by component

Approved Vendor List (AVL)

Export AVL

Export the Approved Vendor List in various formats.

GET /v1/suppliers/avl/export

Query Parameters

Parameter	Type	Description
`format`	string	Export format: `csv`, `xlsx`, `pdf`
`status`	string	Filter by qualification status
`include_components`	boolean	Include component details

curl -X GET "https://api.cohera.io/v1/suppliers/avl/export?format=xlsx&status=qualified" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o approved_vendor_list.xlsx

response = requests.get(
    "https://api.cohera.io/v1/suppliers/avl/export",
    params={
        "format": "xlsx",
        "status": "qualified",
        "include_components": True
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

with open("approved_vendor_list.xlsx", "wb") as f:
    f.write(response.content)

const params = new URLSearchParams({
  format: "xlsx",
  status: "qualified",
  include_components: "true",
});

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

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