Leads API

Capture and manage potential customers through your sales pipeline.

The Leads API allows you to create and retrieve lead records from external sources such as web forms, marketing campaigns, and third-party integrations. Leads represent prospective customers that have not yet converted, and can be tracked through your CRM until they are ready to become active customers.

Use Cases

Web Forms: Capture leads from your landing pages and contact forms
Marketing Campaigns: Import leads from ad platforms and email campaigns
Partner Integrations: Receive referrals from external systems
Sales Pipeline: Automate lead entry from your sales tools

Endpoints

Method	Endpoint	Description
`POST`	`/business/lead/create`	Create a new lead
`GET`	`/business/lead/list`	List all leads

Create Lead

Create a new lead record in your CRM.

http

POST /business/lead/create

Request Body

Field	Type	Required	Description
`name`	string	Yes	Lead's full name
`email`	string	No	Lead's email address
`phone`	string	No	Lead's phone number
`company`	string	No	Company or organization name
`jobtitle`	string	No	Lead's job title
`industry`	string	No	Industry or sector
`website`	string	No	Company or personal website
`request`	string	No	Description of their request or interest
`budget`	number	No	Estimated budget
`country`	string	No	Country
`state`	string	No	State or region
`address`	string	No	Street address
`source`	string	No	Lead source (e.g., `website`, `referral`, `ad`)
`status`	string	No	Initial status (default: `new`)

Example Request

cURLJavaScriptPHPPython

bash

curl -X POST "https://api.cashfin.africa/business/lead/create" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "[email protected]",
    "phone": "+254722000001",
    "company": "Acme Corp",
    "jobtitle": "CTO",
    "source": "website",
    "request": "Interested in enterprise billing solution",
    "budget": 50000
  }'

javascript

const response = await fetch(
  "https://api.cashfin.africa/business/lead/create",
  {
    method: "POST",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Jane Smith",
      email: "[email protected]",
      phone: "+254722000001",
      company: "Acme Corp",
      jobtitle: "CTO",
      source: "website",
      request: "Interested in enterprise billing solution",
      budget: 50000,
    }),
  }
);

const data = await response.json();
console.log(data);

php

<?php
$leadData = [
  'name'    => 'Jane Smith',
  'email'   => '[email protected]',
  'phone'   => '+254722000001',
  'company' => 'Acme Corp',
  'jobtitle'=> 'CTO',
  'source'  => 'website',
  'request' => 'Interested in enterprise billing solution',
  'budget'  => 50000,
];

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://api.cashfin.africa/business/lead/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => json_encode($leadData),
  CURLOPT_HTTPHEADER     => [
    "Authorization: cs_your_client_secret",
    "Content-Type: application/json"
  ],
]);

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

print_r($result);

python

import requests

lead_data = {
    'name':    'Jane Smith',
    'email':   '[email protected]',
    'phone':   '+254722000001',
    'company': 'Acme Corp',
    'jobtitle': 'CTO',
    'source':  'website',
    'request': 'Interested in enterprise billing solution',
    'budget':  50000,
}

response = requests.post(
    'https://api.cashfin.africa/business/lead/create',
    headers={
        'Authorization': 'cs_your_client_secret',
        'Content-Type': 'application/json'
    },
    json=lead_data
)

result = response.json()
print(result)

Success Response

json

{
  "success": true,
  "message": "Lead created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439050",
    "name": "Jane Smith",
    "email": "[email protected]",
    "phone": "+254722000001",
    "company": "Acme Corp",
    "status": "new",
    "source": "website",
    "createdat": "2024-01-15T12:00:00.000Z"
  }
}

List Leads

Retrieve a paginated list of leads with optional filters.

http

GET /business/lead/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
`status`	string	-	Filter by status (e.g., `new`, `contacted`, `qualified`, `converted`)
`source`	string	-	Filter by lead source (e.g., `website`, `referral`)

Example Request

cURLJavaScriptPHPPython

bash

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

javascript

const params = new URLSearchParams({
  page: 1,
  limit: 10,
  status: "new",
});

const response = await fetch(
  `https://api.cashfin.africa/business/lead/list?${params}`,
  {
    headers: {
      Authorization: "cs_your_client_secret",
    },
  }
);

const data = await response.json();
console.log(data);

php

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://api.cashfin.africa/business/lead/list?page=1&limit=10&status=new",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => [
    "Authorization: cs_your_client_secret"
  ],
]);

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

print_r($result);

python

import requests

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

result = response.json()
print(result)

Success Response

json

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439050",
      "name": "Jane Smith",
      "email": "[email protected]",
      "phone": "+254722000001",
      "company": "Acme Corp",
      "status": "new",
      "source": "website",
      "country": null,
      "budget": 50000,
      "createdat": "2024-01-15T12:00:00.000Z",
      "updatedat": "2024-01-15T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "pages": 5
  }
}

Lead Statuses

Status	Description
`new`	Newly created lead, not yet contacted
`contacted`	Initial contact has been made
`qualified`	Lead has been qualified as a prospect
`converted`	Lead converted to a customer
`lost`	Lead did not convert

Lead Object Reference

Field	Type	Description
`_id`	string	Unique lead identifier (MongoDB ObjectID)
`name`	string	Lead's full name
`email`	string	Email address
`phone`	string	Phone number
`company`	string	Company or organization name
`jobtitle`	string	Job title
`industry`	string	Industry or sector
`website`	string	Website URL
`request`	string	Description of the lead's interest or request
`budget`	number	Estimated budget
`country`	string	Country
`state`	string	State or region
`address`	string	Street address
`source`	string	Origin of the lead
`status`	string	Current status in the pipeline
`sourceorigin`	string	Creation channel: `api` or `dashboard`
`active`	boolean	Whether the lead is active
`createdat`	string	ISO 8601 creation timestamp
`updatedat`	string	ISO 8601 last update timestamp

Error Responses

Missing Required Field

json

{
  "success": false,
  "error": "Key: 'ApiLeadRequest.Name' Error:Field validation for 'Name' failed on the 'required' tag"
}

Internal Error

json

{
  "success": false,
  "error": "Error creating lead"
}

Use Cases

Capture Web Form Submissions

javascript

// Triggered when a visitor submits your contact form
async function handleContactForm(formData) {
  const response = await fetch(
    "https://api.cashfin.africa/business/lead/create",
    {
      method: "POST",
      headers: {
        Authorization: API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: formData.fullName,
        email: formData.email,
        phone: formData.phone,
        company: formData.company,
        request: formData.message,
        source: "website",
      }),
    }
  );

  const result = await response.json();
  if (result.success) {
    console.log("Lead captured:", result.data._id);
  }
}

Import Leads in Bulk

javascript

async function importLeads(leads) {
  const results = await Promise.allSettled(
    leads.map((lead) =>
      fetch("https://api.cashfin.africa/business/lead/create", {
        method: "POST",
        headers: {
          Authorization: API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(lead),
      }).then((r) => r.json())
    )
  );

  const succeeded = results.filter((r) => r.status === "fulfilled" && r.value.success).length;
  console.log(`Imported ${succeeded} of ${leads.length} leads`);
}

Leads API ​

Endpoints ​

Create Lead ​

Request Body ​

Example Request ​

Success Response ​

List Leads ​

Query Parameters ​

Example Request ​

Success Response ​

Lead Statuses ​

Lead Object Reference ​

Error Responses ​

Missing Required Field ​

Internal Error ​

Use Cases ​

Capture Web Form Submissions ​

Import Leads in Bulk ​

Leads API

Endpoints

Create Lead

Request Body

Example Request

Success Response

List Leads

Query Parameters

Example Request

Success Response

Lead Statuses

Lead Object Reference

Error Responses

Missing Required Field

Internal Error

Use Cases

Capture Web Form Submissions

Import Leads in Bulk