Create Lead Data Field

POST

client-api.e-so.in/api/engage/v1/lead-data-fields

1. Purpose

This endpoint allows you to create a new lead data field for a specific business. Lead data fields are used to store custom information about leads, such as their job title, industry, or any other relevant data.

2. Authentication

This endpoint requires authentication using a Bearer Token.

• Required auth mechanisms: Bearer Token

• Header format example

Authorization: Bearer your_bearer_token

• Error states for invalid/missing credentials:   
  401 Unauthorized: Missing or invalid Bearer Token.

3. Request Specifications

• Complete header requirements:

  • Content-Type: application/json

  • Authorization: Bearer your_bearer_token

• Supported media types: application/json

• Path parameters: None

• Query parameters: None

4. Request Body

{
  "display_name": string,
  "field_name": string,
  "field_type": string,
  "field_options": array[string], (optional)
  "display_in_filter": boolean (optional)
}

• JSON schema validation rules:

  • display_name: Required string.

  • field_name: Required string.

  • field_type: Required string, must be one of the following values: "string", "boolean", "numeric", "date".

  • field_options: Optional array of strings. Each string must have at least 1 character.

  • display_in_filter: Optional boolean.

• Example request body:

{
  "display_name": "Job Title",
  "field_name": "job_title",
  "field_type": "string",
  "display_in_filter": true
}

{
  "display_name": "Date of Birth",
  "field_name": "date_of_birth",
  "field_type": "date"
}

{
  "display_name": "Subscription Plan",
  "field_name": "subscription_plan",
  "field_type": "string",
  "field_options": ["Free", "Basic", "Premium"]
}

5. Response Handling

• Success response (HTTP 200):

  • Complete field descriptions: The response body will contain a serialized JSON object with the following structure:

{
  "status": 200,
  "success": true,
  "message": "Lead Data Field created",
  "payload": {
    "id": 123,
    "display_name": "Job Title",
    "field_name": "job_title",
    "field_type": "string",
    "field_options": null,
    "display_in_filter": true,
    "created_at": "2024-03-18T10:00:00.000Z",
    "updated_at": "2024-03-18T10:00:00.000Z"
  }
}

Sample response body:

{
      "status": 200,
      "success": true,
      "message": "success.",
      "payload": [
        {
          "id": 123,
          "display_name": "Job Title",
          "field_name": "job_title",
          "field_type": "string",
          "field_options": null,
          "is_default": false,
          "display_in_filter": true,
          "created_at": "2024-03-18T10:00:00.000Z",
          "updated_at": "2024-03-18T10:00:00.000Z"
        },
        {
          "id": 456,
          "display_name": "Company",
          "field_name": "company",
          "field_type": "string",
          "field_options": null,
          "is_default": false,
          "display_in_filter": true,
          "created_at": "2024-03-18T10:00:00.000Z",
          "updated_at": "2024-03-18T10:00:00.000Z"
        }
      ]
    }

• Error responses (4xx/5xx):

  • 400 Bad Request: Invalid request body. The response body will contain details about the validation errors.

  • 401 Unauthorized: Missing or invalid Bearer Token.

  • 403 Forbidden: Lead Data Field limit exceeded.

  • 500 Internal Server Error: An unexpected error occurred on the server.

  • Error code taxonomy: N/A

  • Human-readable messages: The response body will contain a message field with a human-readable error message.

  • Troubleshooting guidance: Check the request body for validation errors. Ensure that the Bearer Token is valid and has the necessary permissions. If the Lead Data Field limit is exceeded, upgrade your plan.

6. Advanced Details

• Rate limiting thresholds: The API is rate-limited to 60 requests per minute.

• Idempotency key support: Not supported.

• Request deduplication window: Not supported.

• Pagination/cursor-based navigation: Not applicable.

• Webhook integration patterns: Not applicable.

7. Code Samples

• cURL command:

curl -X POST \
  https://client-api.e-so.in/engage/v1/lead-data-fields \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_bearer_token' \
  -d '{
        "display_name": "Job Title",
        "field_name": "job_title",
        "field_type": "string",
        "display_in_filter": true
      }'

• JavaScript fetch example:

const url = "https://client-api.e-so.in/engage/v1/lead-data-fields";
const data = {
  display_name: "Job Title",
  field_name: "job_title",
  field_type: "string",
  display_in_filter: true,
};
fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer your_bearer_token",
  },
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((data) => console.log(data));