Generics

Generics represent generic medicine names (active ingredients) used in pharmaceutical catalogs. A generic like "Paracetamol" can be linked to multiple branded products (Panadol, Tylenol, Adol). Generic names are validated for global uniqueness.

The Generic Object

{
  "id": "GEN001",
  "generic_code": "GEN001",
  "organization_id": "org_abc123",
  "name_en": "Paracetamol",
  "name_ar": "باراسيتامول",
  "products": ["prd_001", "prd_002", "prd_003"],
  "product_count": 45,
  "common_brands": ["Panadol", "Tylenol", "Adol"],
  "created": "2024-01-15T10:30:00Z",
  "updated": "2024-01-16T14:22:00Z"
}

Fields

Field	Type	Description
`id`	string	Internal Linkit ID
`generic_code`	string	Your unique identifier
`name_en`	string	Generic name in English
`name_ar`	string	Generic name in Arabic
`products`	array	Product IDs containing this generic
`product_count`	integer	Number of associated products
`common_brands`	array	Common brand names for this generic

List Generics

GET /api/v1/generics

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`search`	string	-	Search in generic names
`has_products`	boolean	-	Filter generics with/without products

Example Request

curl -X GET "https://linkit.works/api/v1/generics?search=paracetamol&limit=25" \
  -H "Authorization: Bearer your_token_here"

const response = await fetch(
  'https://linkit.works/api/v1/generics?search=paracetamol&limit=25',
  { headers: { 'Authorization': 'Bearer your_token_here' } }
);
const generics = await response.json();

import requests

response = requests.get(
    'https://linkit.works/api/v1/generics',
    params={'search': 'paracetamol', 'limit': 25},
    headers={'Authorization': 'Bearer your_token_here'}
)
generics = response.json()

Get Single Generic

GET /api/v1/generics/code/{genericCode}

Returns the full generic object including product associations and common brands.

Create Generic

POST /api/v1/generics

Request Body

{
  "generic_code": "GEN-IBUP",
  "name_en": "Ibuprofen",
  "name_ar": "إيبوبروفين",
  "products": ["prd_123", "prd_456"]
}

Required Fields

Field	Type	Constraints
`generic_code`	string	Max 50 chars, unique

Optional Fields

Field	Type	Constraints
`name_en`	string	Max 255 chars, globally unique
`name_ar`	string	Max 255 chars
`products`	array	Product IDs to associate

Generic names are validated for global uniqueness. You cannot create "Paracetamol" if it already exists with a different code.

Update Generic

PUT /api/v1/generics/code/{genericCode}

Full replacement. Include all fields you want to keep.

Delete Generic

DELETE /api/v1/generics/code/{genericCode}

Parameter	Type	Default	Description
`force`	boolean	false	Delete even if the generic has associated products

Deletion behavior

By default, generics with associated products cannot be deleted. With force=true, products are unassigned (not deleted).

Search Generics

Advanced search with fuzzy matching.

POST /api/v1/generics/search

Request Body

{
  "query": "para",
  "has_products": true,
  "page": 1,
  "limit": 25
}

Returns results ordered by relevance, same pagination structure as list.

Bulk Operations

POST /api/v1/generics/bulk

{
  "mode": "upsert",
  "generics": [
    { "generic_code": "GEN001", "name_en": "Paracetamol", "name_ar": "باراسيتامول" },
    { "generic_code": "GEN002", "name_en": "Ibuprofen", "name_ar": "إيبوبروفين" }
  ]
}

Modes: create, update, upsert. Max 1,000 per request.

Clear Cache

Admin-only endpoint to clear cached generic data. Cache rebuilds automatically on subsequent requests.

POST /api/v1/generics/cache/clear

Admin only

Requires admin privileges. Use sparingly.

Error Responses

409 Conflict (Duplicate Code)

{
  "code": 409,
  "error": "Generic with this code already exists",
  "details": { "generic_code": "GEN001", "existing_id": "r1234567890" }
}

409 Conflict (Duplicate Name)

{
  "code": 409,
  "error": "Generic with this name already exists",
  "details": { "name_en": "Paracetamol", "existing_code": "GEN001" }
}

Products

Link generics to products.

Brands

Brand management alongside generics.

Generics

Products

Brands

On this page