Guides

Suppliers API

Integrate with CreditRisk endpoints using clear request and response examples.

Suppliers Endpoint

Retrieve and create suppliers for the grantors you have access to.

Endpoint Details

GET /api/suppliers — list suppliers
GET /api/suppliers/{id} — supplier details
POST /api/suppliers — create a supplier

Authentication Required

API Token: Required in URL parameter ?api_token=xxx
User Token: Required in Authorization header Bearer {access_token}

Query Parameters

Parameter	Type	Required	Description
`api_token`	string	Yes	Your API access token
`grantor_id`	integer	No	Limit to one grantor (default: all grantors the user can access)
`supplier_name`	string	No	Filter by supplier name (partial match)
`page`	integer	No	Page number (default: 1, 100 per page)
`paging`	integer	No	Set to 0 to disable pagination and get all results

Response Format

Success Response (200 OK)

{
  "success": true,
  "message": "Suppliers retrieved successfully",
  "data": {
    "suppliers": [
      {
        "id": 456,
        "account_number": "SUP001",
        "name": "Supplier Corp Ltd",
        "contact_tel": "0111234567",
        "grantor": { "id": 5, "name": "Example Grantor", "badge_color": "#1abc9c", "initials": "EG" },
        "status": 1,
        "status_name": "Active",
        "created_date": "2024-01-01 10:00:00",
        "last_updated": "2024-01-15 14:30:00"
      }
    ],
    "pagination": { "current_page": 1, "per_page": 100, "total_results": 25, "total_pages": 1 },
    "summary": { "total_suppliers": 25, "grantors_accessed": 1, "user_id": 7 }
  }
}

Create Supplier (POST)

POST /api/suppliers

Send a JSON body (or form data) with the same authentication as above. The supplier is created as active with the default starting status.

Field	Type	Required	Description
`name`	string	Yes	Supplier name
`grantor_id`	integer	Yes	Grantor the record is created under (you must have access)
`company_type_id`	integer	Yes	Active company type ID (see company_types endpoint)
`email`	string	One of email / contact_tel	Valid email address. Required if send_app_invite is true
`contact_tel`	string	One of email / contact_tel	Contact telephone / cell number
`trading_name`	string	No	Trading name
`contact_name`	string	No	Contact person
`account_number`	string	No	Your account number
`account_reg_no`	string	No	Registration number. Must be unique (409 if it already exists)
`address_unit_no`, `address_complex`, `address_street_no`, `address_street_name`, `address_suburb`, `address_town`, `address_province`, `address_postal_code`, `address_country`	string	No	Address fields
`send_app_invite`	boolean	No	Send an application invite to `email` after creation (default false)

Success Response (200 OK)

{
  "success": true,
  "message": "Supplier created successfully",
  "data": {
    "supplier": {
      "id": 123,
      "name": "Example Corp",
      "email": "contact@example.com",
      "status": 1,
      "active": true,
      "grantor": { "id": 5, "name": "Example Grantor", "initials": "EG" },
      "created_by": 7,
      "send_app_invite": false,
      "application_invite": null
    }
  }
}

Errors: 400 missing/invalid fields, 403 no access to the grantor, 409 duplicate account_reg_no.

Example

curl -X POST "https://api.creditrisk.co.za/api/suppliers?api_token=your_token" \

  -H "Authorization: Bearer your_user_token" -H "Content-Type: application/json" \

  -d '{"name":"Example Corp","grantor_id":5,"company_type_id":1,"email":"contact@example.com"}'

Examples

Basic Request

curl -X GET "https://api.creditrisk.co.za/api/suppliers?api_token=your_token" \

  -H "Authorization: Bearer your_access_token"

Filter by Name

curl -X GET "https://api.creditrisk.co.za/api/suppliers?api_token=your_token&supplier_name=supplier" \

  -H "Authorization: ******"

Error Responses

Authentication Failed (401 Unauthorized)

{
  "success": false,
  "error": "Authentication failed",
  "message": "Invalid or expired access token"
}

Access Denied (403 Forbidden)

{
  "success": false,
  "message": "Access denied to specified grantor"
}

Test This Endpoint

Use the interactive testing tool to try this endpoint:

Go to API Testing