Skip to content

Lead Management API

Connect’s lead management API supports the following scenarios:

  • Updating a single lead’s stage
  • Getting a single lead’s required documents

Anatomy of a request

All API requests to Connect contain a few critical components; an HTTP Method, API key, a Partner Route, a Path, and a Host.

HTTP Method

All HTTP requests have a method; in our API we use primarily ‘GET’, ‘POST’, and ‘DELETE’.

API Key

An API key (provided on request) must be included in the headers of every request sent to Connect. This value should be kept secret and not shared for any reason.

For example: x-api-key: CfDJ8Ke4rggGedRLnLycPTg...

Partner Route

Every partner has a unique route, which is part of your path. For a partner named ‘My Finances’ your route might be something like my-finances. This partner route will be given to you by Connect along with your API key.

Path

Each endpoint is identified by a combination of method and path, for example POST /api/v1/my-finances/leads?leadId=abc-123... combines the POST method with the /api/v1/my-finances/Leads path to get a single lead. In this example, we also attached a QueryString, which adds parameters to the call, these are the values following the ? question mark.

Host

The ‘host’ is also called the domain. Our partners have access to two hosts; one you can use for testing and one for your live/production environment.

Putting it all together, you will will see an HTTP request that looks like the following:

Example cURL request
curl \
  --location --request POST 'https://qa.connect.crfusa.com/api/v1/your-partner-route/leads' \
  --header 'x-api-key: yourapikeyhereCfDJ8Jnsgoaz8OhPpzNEDyvffeyourapikeyhere' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "id": "9c30a205-a60e-47cb-94b4-6d45cd4c2179",
      "status": "Contacted"
  }'

Submitting a test lead

Refer to ‘Submitting a test lead’ in the webhooks documentation.

Testing the API

We recommend using postman to test our API interactively.

Configuring the ‘Authorization’ tab

You can find a lead’s ‘ID’ by visiting the partner portal’s leads report

Updating a lead’s stage

Update a single editable lead owned by your lending partner account. Note that once a lead is funded it is no longer editable.

HTTP Method: POST
Path: /api/v1/{PartnerRoute}/Leads

Input body:

{
    "id":                 <guid>,
    "status":             <leadstatus>,
    "fundeddate":         <datetime option>,
    "fundedamount":       <decimal option>,
    "fundedinterestrate": <decimal option>,
    "fundedapr":          <decimal option>,
    "fundedtermmonths":   <int option>,
    "fundedamortizationmonths": <int option>,
    "disqualifiedreason": <disqualifiedreason option>,
    "withdrawnreason":    <withdrawnreason option>,
    "additionalinfo":     <string option>,
    "willreceivetechnicalassistance": <bool option>,
    "technicalassistanceoptions": <technicalassistance array>
}

leadstatus

The lead status is intended to flow from top to bottom, for example Reviewed goes to Contacted, which goes to Qualified, which goes to Funded. Funded, Disqualified, and Withdrawn are considered ‘terminal’ states, where the lead is considered closed, however leads can be moved from Disqualified or Withdrawn back to a non-terminal state.

Funded is final, so the lead can no longer be updated.

Lead statuses can be skipped entirely; once the lead is ‘Matched’, it can go straight to Funded, Withdrawn or Disqualified, but this is discouraged since it likely fails to track several internal status changes that the service partner is likely following internally.

  • Matched: The initial state, the applicant has chosen your product
  • Reviewed: Service partner has viewed submitted applicant form
  • Contacted: Prospective applicant has been contacted by the product owner, but has not submitted an application to the service partner
  • Qualified: Lead is marked qualified
  • Funded: Lead has been completed / funded
  • Disqualified: Lead was disqualified
  • Withdrawn: Lead stopped responding

withdrawnreason

  • BorrowerStoppedResponding: Applicant stopped responding
  • Duplicate: Applicant form was a duplicate request
  • LostBidToCompetitor: Bid was lost
  • FraudOrSpam: Lead was fraudulent or spam
  • Other: Withdrawn for any other reason

disqualifiedreason

  • EligibilityIssue: Disqualified because of eligibility issue
  • CreditIssue: Disqualified because of credit issue
  • CashFlowIssue: Disqualified because of cash flow issue
  • CollateralIssue: Disqualified because of collateral issue
  • LoanUseIssue: Disqualified because of loan use issue
  • PersonalGuaranteeIssue: Disqualified because of personal guarantee issue
  • Other: Disqualified for any other reason

technicalassistance

  • Accounting: Accounting
  • BusinessPlan: Business Plan
  • BuyOrSellABusiness: Buy/Sell a business
  • CashFlowManagement: Cash-flow management
  • CompanyFormation: Company formation / startup
  • CustomerRelations: Customer relations
  • CreditCounseling: Credit counseling
  • FinancingOrCapital: Financing or capital
  • Franchising: Franchising
  • GovernmentContracting: Government Contracting
  • HumanResourcesAndManagement: Human Resources & Management
  • InternationalTrade: International Trade
  • LegalIssues: Legal Issues
  • MarketingOrSales: Marketing or Sales
  • PrivateSectorProcurement: Private sector procurement
  • TaxPlanning: Tax planning
  • TechnologyAndECommerce: Technology and E-Commerce

Response

The response content will be empty, the status code will indicate the result of the operation.

Response Code

  • 200 - Lead status was updated
  • 400 - Bad request
  • 401 - Request could not be authorized
  • 404 - Editable lead could not be found

Examples:

Mark a lead as ‘Contacted’

Url: POST https://connect.crfusa.com/api/v1/testpartner/leads

Authorization: CfDJ8Ke4rggGedRLnLycPTgRgpNjR3Wa4wee...

Body:

{
    "id": "eaffba05-c56c-47a0-8c79-507aafc9f1d1",
    "status": "Contacted"
}

Mark a lead as ‘Funded’

Url: POST https://connect.crfusa.com/api/v1/testpartner/leads

Authorization: CfDJ8Ke4rggGedRLnLycPTgRgpNjR3Wa4wee...

Body:

{
    "id": "eaffba05-c56c-47a0-8c79-507aafc9f1d1",
    "status": "Funded",
    "fundedamount": 50000,
    "fundedinterestrate": 5.5,
    "fundedapr": 10.0,
    "fundedtermmonths": 24,
    "fundedamortizationmonths": 24,
    "willreceivetechnicalassistance": true,
    "technicalassistanceoptions": [
        "PrivateSectorProcurement"
    ]
}

Mark a lead as ‘Disqualified’

Url: POST https://connect.crfusa.com/api/v1/testpartner/leads

Authorization: CfDJ8Ke4rggGedRLnLycPTgRgpNjR3Wa4wee...

Body:

{
    "id": "eaffba05-c56c-47a0-8c79-507aafc9f1d1",
    "status": "Disqualified",
    "disqualifiedreason": "EligibilityIssue",
    "additionalinfo": "The lead was ineligible because xyz. This is custom text",
    "willreceivetechnicalassistance": true,
    "technicalassistanceoptions": [
        "PrivateSectorProcurement"
    ]
}