Guides

Accounts API

Integrate with CreditRisk endpoints using clear request and response examples.

Accounts Endpoint

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

Endpoint Details

GET /api/accounts — list accounts
GET /api/accounts/{id} — account details
POST /api/accounts — create an account

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
`page`	integer	No	Page number (default: 1)
`paging`	integer	No	Set to 0 to disable pagination and get all results
`grantor_id`	integer	No	Limit to one grantor (default: all grantors the user can access)
`status_name`	string	No	Filter by status name (exact match)
`account_name`	string	No	Filter by account name (partial match)

Response Format

Success Response (200 OK)

{
  "success": true,
  "message": "Accounts retrieved successfully",
  "data": {
    "accounts": [
      {
        "id": 123,
        "account_number": "AC001",
        "name": "Example Corp",
        "contact_tel": "0110000000",
        "grantor": { "id": 5, "name": "Example Grantor", "badge_color": "#1abc9c", "initials": "EG" },
        "status": 1,
        "status_name": "Active",
        "credit_type": "Credit",
        "credit_limit": 50000,
        "sync_id": "a1b2c3",
        "documents": [
          {
            "id": 42,
            "name": "Registration document",
            "account_id": 123,
            "app_id": 5,
            "document_id": 3,
            "filename": "registration.pdf",
            "timestamp": "2024-01-15 14:30:00",
            "created_at": "2024-01-15 14:30:00",
            "created_by": 7,
            "expiry_date": null
          }
        ],
        "final_score": 72.5,
        "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": 45, "total_pages": 1 },
    "summary": { "total_accounts": 45, "current_page_accounts": 45, "grantors_accessed": 1, "user_id": 7 }
  }
}

Both list and account detail responses include a documents array containing active document metadata from app_account_documents, or an empty array when none exist. Document content (data) is not included; this response does not provide a download.

Create Account (POST)

POST /api/accounts

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

Field	Type	Required	Description
`name`	string	Yes	Account 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)
`credit_type`	string	No	`Credit` or `Cash`
`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": "Account created successfully",
  "data": {
    "account": {
      "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/accounts?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","credit_type":"Credit"}'

Examples

Basic Request

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

  -H "Authorization: Bearer your_access_token"

With Filtering

curl -X GET "https://api.creditrisk.co.za/api/accounts?api_token=your_token&account_name=example" \

  -H "Authorization: Bearer your_access_token"

Get All Records (No Pagination)

curl -X GET "https://api.creditrisk.co.za/api/accounts?api_token=your_token&paging=0" \

  -H "Authorization: Bearer your_access_token"

Error Responses

Authentication Failed (401 Unauthorized)

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

Access Denied (403 Forbidden)

{
  "success": false,
  "error": "Access denied",
  "message": "User does not have access to any grantor accounts"
}

Test This Endpoint

Use the interactive testing tool to try this endpoint:

Go to API Testing