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.

Testing: https://qa.connect.crfusa.com
Production: https://connect.crfusa.com

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

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"
    ]
}