Generate Leads via Forms

This tutorial guides you through using a standalone form to capture information and automatically create a lead record in the CRM. You will learn how to fetch a form's structure and submit user data to generate a new lead.

This guide is designed for developers implementing lead generation forms on marketing websites, landing pages, or any custom front-end application.

Prerequisites

Before you begin, make sure you have the following:

• Configured Form: You must have a form created in the CarePortals CRM. The Form ID is required for the API calls and can be found in the Forms section of the CRM.
• Organization ID (<ORG_ID>): If you are using a custom domain, you must send the Organization ID (<ORG_ID>) in the request header. This header is not required for requests made from a CarePortals subdomain.

Flow Overview

Here's a high-level overview of the lead generation flow:

1. Retrieve the Form Structure: Fetch the complete configuration of the form, including its fields and validation rules, to render it on your front end.
2. Submit the Form and Create a Lead: Send the user's submitted data to the API to create a new lead record in the CRM.

Step 1: Retrieve the Form Structure

Before displaying a form, you need to fetch its configuration, including all its fields, labels, and validation rules. You can get this structure by calling the Retrieve a Form by ID endpoint. The form's ID can be found within the Forms section of the CRM Portal.

curl -X GET 'https://public-api.portals.care/form/60d5f2a9a0b3f1001fbaa458' \
-H 'organization: <ORG_ID>'

{
  "_id": "60d5f2a9a0b3f1001fbaa458",
  "name": "Marketing Campaign Lead Form",
  "description": "Form to capture new leads from the fall marketing campaign.",
  "organization": "<ORG_ID>",
  "fields": [
    {
      "name": "firstName",
      "label": "First Name",
      "type": "text",
      "required": true,
      "placeholder": "Enter your first name"
    },
    {
      "name": "lastName",
      "label": "Last Name",
      "type": "text",
      "required": true,
      "placeholder": "Enter your last name"
    },
    {
      "name": "email",
      "label": "Email Address",
      "type": "email",
      "required": true,
      "placeholder": "Enter your email"
    },
    {
      "name": "consent",
      "label": "I agree to receive marketing communications.",
      "type": "checkbox",
      "required": true
    }
  ]
}

The endpoint returns a 200 OK status and the form object, including its name and an array of key-value pairs that you will use to build the form UI dynamically.

Step 2: Submit the Form and Create a Lead

After a user fills out the form on your custom front-end, you submit their data to create a lead record in the CRM. This is accomplished by calling the Submit a Form endpoint. The request body must include the formId and a values object containing the user's submissions, which will automatically generate a new lead in Care Portals.

curl -X POST 'https://public-api.portals.care/form' \
-H 'organization: <ORG_ID>' \
-H 'Content-Type: application/json' \
-d '{
  "formId": "60d5f2a9a0b3f1001fbaa458",
  "values": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "consent": true
  }
}'

{
  "status": "success",
  "message": "Form submitted successfully."
}

A successful request returns a 201 Created status code and a confirmation object, indicating that the submission was received and a lead has been created.