Creating a Segment

POST

client-api.e-so.in/api/engage/v1/segments

1. Purpose

This endpoint allows you to create a new segment. Segments are used to group leads based on specific criteria.

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

Schema definition:

{
  "name": string,
  "description": string | null,
  "type": string,
  "definitions": [
    {
      "type": string,
      "data_field_id": number | null,
      "evaluation": string,
      "value": string | null,
      "tags": number[] | null,
      "date": {
        "duration": number | null,
        "unit": string,
        "duration_from": number | null,
        "duration_to": number | null
      } | null
    }
  ]
}

JSON schema validation rules:
- name: Required string, max length 30.
- description: Optional nullable string.
- type: Required string, must be one of the following values: "default", "shop_order".
- definitions: Required array, min length 1. Each element must be an object with the following properties:
  - type: Required string, must be one of the following values: "tag", "lead_data_field", "order_status", "order_amount", "order_date", "product_name".
  - data_field_id: Optional number, required when type is "lead_data_field", must exist in the lead_data_fields table for the business.
  - evaluation: Required string, must be one of the following values: "exact_match", "contains", "include", "exclude", "before", "after", "between", "equal_to", "less_then", "greater_then", "true", "false".
  - value: Optional string, required when evaluation is one of the following: "contains", "exact_match", "equal_to", "greater_then", "less_then".
  - tags: Optional array of numbers, required when type is "tag".
  - date: Optional object, required when evaluation is one of the following: "after", "before", "between".
    - duration: Optional number, required when evaluation is one of the following: "after", "before".
    - unit: Required string when evaluation is one of the following: "after", "before", must be one of the following values: "hours", "minutes", "days".
    - duration_from: Optional number, required when evaluation is "between".
    - duration_to: Optional number, required when evaluation is "between".
- Order-related definition types ("order_status", "order_amount", "order_date", "product_name") are only allowed if the segment type is "shop_order".
Example request body:

{
  "name": "High Value Leads",
  "description": "Leads with order amount greater than 100",
  "type": "shop_order",
  "definitions": [
    {
      "type": "order_amount",
      "evaluation": "greater_then",
      "value": "100"
    }
  ]
}

{
  "name": "Leads Interested in Product A",
  "description": "Leads who have purchased Product A",
  "type": "shop_order",
  "definitions": [
    {
      "type": "product_name",
      "evaluation": "contains",
      "value": "Product A"
    }
  ]
}

{
  "name": "Premium Customers",
  "description": "Leads which is marked as premium on one of the lead data field",
  "type": "default",
  "definitions": [
    {
      "type": "lead_data_field",
      "evaluation": "exact_match",
      "data_field_id": 343
    }
  ]
}

5. Response Handling

Success response (HTTP 201):
- Complete field descriptions: The response body will contain a serialized JSON object with the following structure:

{
  "status": 201,
  "success": true,
  "message": "Segment created successfully!",
  "payload": {
    // The created segment object
  }
}

Sample response body:

{
  "status": 201,
  "success": true,
  "message": "Segment created successfully!",
  "payload": {
    "id": 1,
    "name": "High Value Leads",
    "description": "Leads with order amount greater than 100",
    "type": "shop_order",
    "definitions": [
      {
        "type": "order_amount",
        "evaluation": "greater_then",
        "value": "100"
      }
    ],
    "business_id": 123,
    "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.
- 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.

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/segments \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_bearer_token' \
  -d '{
        "name": "High Value Leads",
        "description": "Leads with order amount greater than 100",
        "type": "shop_order",
        "definitions": [
          {
            "type": "order_amount",
            "evaluation": "greater_then",
            "value": "100"
          }
        ]
      }'

JavaScript fetch example:

const url = 'https://client-api.e-so.in/engage/v1/segments';
const data = {
  "name": "High Value Leads",
  "description": "Leads with order amount greater than 100",
  "type": "shop_order",
  "definitions": [
    {
      "type": "order_amount",
      "evaluation": "greater_then",
      "value": "100"
    }
  ]
};
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));