Vendors API

Manage your supplier and vendor directory programmatically.

The Vendors API lets you create and maintain supplier profiles, sync vendor data from external procurement systems, and retrieve vendor information for use in bills, expenses, and purchase orders.

Use Cases

ERP Sync: Keep vendor records in sync between Cashfin and your ERP
Onboarding Automation: Automatically register new suppliers as they are approved
Procurement Workflows: Look up vendor details when creating purchase orders

Endpoints

Method	Endpoint	Description
`POST`	`/business/vendor/create`	Create a new vendor
`GET`	`/business/vendor/list`	List all vendors
`GET`	`/business/vendor/details/:id`	Get vendor details
`PATCH`	`/business/vendor/update/:id`	Update a vendor

Create Vendor

Create a new vendor record.

http

POST /business/vendor/create

Request Body

Field	Type	Required	Description
`name`	string	Yes	Vendor name (must be unique)
`type`	string	Yes	`individual` or `business`
`phone`	string	Yes	Contact phone number
`email`	string	No	Contact email address
`company`	string	No	Company name
`industry`	string	No	Industry or sector
`country`	string	No	Country
`city`	string	No	City
`address`	string	No	Street address
`website`	string	No	Website URL
`tax`	string	No	Tax identification number

Example Request

cURLJavaScriptPHPPython

bash

curl -X POST "https://api.cashfin.africa/business/vendor/create" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Supplies Ltd",
    "type": "business",
    "phone": "+254700000001",
    "email": "[email protected]",
    "company": "Acme Supplies Ltd",
    "industry": "Manufacturing",
    "country": "Kenya",
    "city": "Nairobi"
  }'

javascript

const response = await fetch(
  "https://api.cashfin.africa/business/vendor/create",
  {
    method: "POST",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Acme Supplies Ltd",
      type: "business",
      phone: "+254700000001",
      email: "[email protected]",
      company: "Acme Supplies Ltd",
      industry: "Manufacturing",
      country: "Kenya",
      city: "Nairobi",
    }),
  }
);
const data = await response.json();

php

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://api.cashfin.africa/business/vendor/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => json_encode([
    'name'     => 'Acme Supplies Ltd',
    'type'     => 'business',
    'phone'    => '+254700000001',
    'email'    => '[email protected]',
    'country'  => 'Kenya',
  ]),
  CURLOPT_HTTPHEADER     => [
    "Authorization: cs_your_client_secret",
    "Content-Type: application/json"
  ],
]);

$result = json_decode(curl_exec($curl), true);

python

import requests

response = requests.post(
    'https://api.cashfin.africa/business/vendor/create',
    headers={
        'Authorization': 'cs_your_client_secret',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Acme Supplies Ltd',
        'type': 'business',
        'phone': '+254700000001',
        'email': '[email protected]',
        'country': 'Kenya',
        'city': 'Nairobi',
    }
)

Success Response

json

{
  "success": true,
  "message": "Vendor created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439060",
    "name": "Acme Supplies Ltd",
    "type": "business",
    "phone": "+254700000001",
    "email": "[email protected]",
    "company": "Acme Supplies Ltd",
    "country": "Kenya",
    "active": true,
    "sourceorigin": "api",
    "createdat": "2024-01-15T12:00:00.000Z"
  }
}

List Vendors

Retrieve a paginated list of vendors.

http

GET /business/vendor/list

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	10	Results per page (max: 100)
`search`	string	-	Search by name, email, phone, or company

Example Request

cURLJavaScriptPython

bash

curl -X GET "https://api.cashfin.africa/business/vendor/list?page=1&limit=10" \
  -H "Authorization: cs_your_client_secret"

javascript

const response = await fetch(
  "https://api.cashfin.africa/business/vendor/list?page=1&limit=10",
  {
    headers: { Authorization: "cs_your_client_secret" },
  }
);
const data = await response.json();

python

import requests

response = requests.get(
    'https://api.cashfin.africa/business/vendor/list',
    headers={'Authorization': 'cs_your_client_secret'},
    params={'page': 1, 'limit': 10}
)

Success Response

json

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439060",
      "name": "Acme Supplies Ltd",
      "type": "business",
      "email": "[email protected]",
      "phone": "+254700000001",
      "country": "Kenya",
      "balance": 0,
      "active": true,
      "createdat": "2024-01-15T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 15,
    "page": 1,
    "limit": 10,
    "pages": 2
  }
}

Get Vendor Details

Retrieve full details of a specific vendor.

http

GET /business/vendor/details/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Vendor ID (MongoDB ObjectID)

Example Request

cURLJavaScriptPython

bash

curl -X GET "https://api.cashfin.africa/business/vendor/details/507f1f77bcf86cd799439060" \
  -H "Authorization: cs_your_client_secret"

javascript

const vendorId = "507f1f77bcf86cd799439060";

const response = await fetch(
  `https://api.cashfin.africa/business/vendor/details/${vendorId}`,
  {
    headers: { Authorization: "cs_your_client_secret" },
  }
);
const data = await response.json();

python

import requests

vendor_id = '507f1f77bcf86cd799439060'

response = requests.get(
    f'https://api.cashfin.africa/business/vendor/details/{vendor_id}',
    headers={'Authorization': 'cs_your_client_secret'}
)

Success Response

json

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439060",
    "name": "Acme Supplies Ltd",
    "type": "business",
    "email": "[email protected]",
    "phone": "+254700000001",
    "company": "Acme Supplies Ltd",
    "industry": "Manufacturing",
    "country": "Kenya",
    "city": "Nairobi",
    "address": null,
    "tax": null,
    "website": null,
    "balance": 0,
    "active": true,
    "createdat": "2024-01-15T12:00:00.000Z",
    "updatedat": "2024-01-15T12:00:00.000Z"
  }
}

Update Vendor

Update fields on an existing vendor. Only provided fields will be changed.

http

PATCH /business/vendor/update/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Vendor ID (MongoDB ObjectID)

Request Body

All fields are optional.

Field	Type	Description
`name`	string	Vendor name
`type`	string	`individual` or `business`
`phone`	string	Contact phone
`email`	string	Contact email
`company`	string	Company name
`industry`	string	Industry
`country`	string	Country
`city`	string	City
`address`	string	Street address
`website`	string	Website URL
`tax`	string	Tax ID

Example Request

cURLJavaScriptPython

bash

curl -X PATCH "https://api.cashfin.africa/business/vendor/update/507f1f77bcf86cd799439060" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+254700000099",
    "city": "Mombasa"
  }'

javascript

const vendorId = "507f1f77bcf86cd799439060";

const response = await fetch(
  `https://api.cashfin.africa/business/vendor/update/${vendorId}`,
  {
    method: "PATCH",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ phone: "+254700000099", city: "Mombasa" }),
  }
);

python

import requests

vendor_id = '507f1f77bcf86cd799439060'

response = requests.patch(
    f'https://api.cashfin.africa/business/vendor/update/{vendor_id}',
    headers={'Authorization': 'cs_your_client_secret'},
    json={'phone': '+254700000099', 'city': 'Mombasa'}
)

Success Response

json

{
  "success": true,
  "message": "Vendor updated successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439060",
    "modified": 1
  }
}

Error Responses

Duplicate Vendor Name

json

{
  "success": false,
  "error": "Vendor with this name already exists"
}

Vendor Not Found

json

{
  "success": false,
  "error": "Vendor not found"
}

Invalid Vendor ID

json

{
  "success": false,
  "error": "Invalid vendor ID format"
}

Vendor Object Reference

Field	Type	Description
`_id`	string	Unique vendor identifier
`name`	string	Vendor name
`type`	string	`individual` or `business`
`phone`	string	Contact phone number
`email`	string	Contact email address
`company`	string	Company name
`industry`	string	Industry or sector
`country`	string	Country
`city`	string	City
`address`	string	Street address
`website`	string	Website URL
`tax`	string	Tax identification number
`balance`	number	Outstanding balance owed to vendor
`sourceorigin`	string	Creation channel: `api` or `dashboard`
`active`	boolean	Whether the vendor is active
`createdat`	string	ISO 8601 creation timestamp
`updatedat`	string	ISO 8601 last update timestamp

Vendors API ​

Endpoints ​

Create Vendor ​

Request Body ​

Example Request ​

Success Response ​

List Vendors ​

Query Parameters ​

Example Request ​

Success Response ​

Get Vendor Details ​

Path Parameters ​

Example Request ​

Success Response ​

Update Vendor ​

Path Parameters ​

Request Body ​

Example Request ​

Success Response ​

Error Responses ​

Duplicate Vendor Name ​

Vendor Not Found ​

Invalid Vendor ID ​

Vendor Object Reference ​

Vendors API

Endpoints

Create Vendor

Request Body

Example Request

Success Response

List Vendors

Query Parameters

Example Request

Success Response

Get Vendor Details

Path Parameters

Example Request

Success Response

Update Vendor

Path Parameters

Request Body

Example Request

Success Response

Error Responses

Duplicate Vendor Name

Vendor Not Found

Invalid Vendor ID

Vendor Object Reference