SIFA Search Youth

A REST API workflow that provides flexible search capabilities for youth entrepreneur records in the SIFA database. The workflow accepts either phone number or name-based searches and returns matching youth profiles with their business and demographic information.

Purpose

No business context provided yet — add a context.md to enrich this documentation.

This workflow serves as a search API endpoint for finding youth entrepreneurs in the SIFA system. It enables users to locate specific individuals either by their phone number (for exact matches) or by their names (for partial matches), returning comprehensive profile information including demographics, location, and business ownership status.

How It Works

1. Webhook Reception: The workflow receives a POST request with search parameters including search type and relevant search terms
2. Phone Normalization: Incoming phone numbers are standardized to international format (+254 prefix for Kenyan numbers)
3. Search Type Detection: The system determines whether to perform a phone-based or name-based search
4. Database Query Execution:
   • For phone searches: Exact match against the normalized phone number
   • For name searches: Partial matching against both first and second names using case-insensitive LIKE queries
5. Result Formatting: Search results are structured into a consistent JSON format with metadata
6. Response Delivery: The formatted results are returned to the client with appropriate CORS headers

Workflow Diagram

graph TD
    A[Webhook] --> B[Normalize Phone]
    B --> C{Search By Phone?}
    C -->|Yes| D[Search By Phone]
    C -->|No| E[Search By Name]
    D --> F[Format Phone Results]
    E --> G[Format Name Results]
    F --> H[Respond Phone Results]
    G --> I[Respond Name Results]

Trigger

Webhook: POST request to /sifa-search-youth

The workflow is triggered by HTTP POST requests containing search parameters in the request body.

Nodes Used

Node Type	Node Name	Purpose
Webhook	Webhook	Receives incoming search requests via HTTP POST
Code	Normalize Phone	Standardizes phone numbers to international format
If	Search By Phone?	Routes execution based on search type parameter
Postgres	Search By Phone	Executes exact phone number match query
Postgres	Search By Name	Executes partial name match query
Code	Format Phone Results	Structures phone search results into API response format
Code	Format Name Results	Structures name search results into API response format
Respond to Webhook	Respond Phone Results	Returns phone search results to client
Respond to Webhook	Respond Name Results	Returns name search results to client

External Services & Credentials Required

Database

• PostgreSQL Database: Contains the youthEntrepreneursReal table
• Required Credential: Postgres account (ID: EJPqF6MDH1ZwAzyv)

Database Schema

The workflow queries the following fields from youthEntrepreneursReal: - id - Unique identifier - firstName - Youth's first name - secondName - Youth's second name - phoneNumber - Contact phone number - gender - Gender information - age - Age of the youth - county - County location - ward - Ward location - businessOwned - Business ownership status - channel - Registration channel

Environment Variables

No environment variables are required for this workflow.

Data Flow

Input Format

{
  "searchType": "phone" | "name",
  "phoneNumber": "0712345678",  // Required for phone search
  "firstName": "John",          // Required for name search
  "secondName": "Doe"           // Optional for name search
}

Output Format

{
  "found": true,
  "count": 2,
  "records": [
    {
      "id": 123,
      "firstName": "John",
      "secondName": "Doe",
      "phoneNumber": "+254712345678",
      "gender": "Male",
      "age": 25,
      "county": "Nairobi",
      "ward": "Westlands",
      "businessOwned": true,
      "channel": "Online"
    }
  ]
}

Phone Number Normalization

• Numbers starting with "0" are converted to "+254" format
• Numbers starting with "254" get "+" prefix added
• Other formats are left unchanged

Error Handling

The workflow includes basic error handling through: - Always Output Data: Both database nodes are configured to always return data, even on query failures - Result Filtering: The formatting nodes filter out empty results before structuring the response - CORS Headers: All responses include appropriate CORS headers for cross-origin requests

Known Limitations

• Search results are limited to 10 records per query
• Name searches use partial matching which may return many results for common names
• No authentication or rate limiting is implemented
• Phone number normalization is specific to Kenyan numbers (+254)

Related Workflows

No related workflows identified in the current context.

Setup Instructions

1. Import the Workflow

   • Copy the workflow JSON and import it into your n8n instance
   • The workflow will be created with the name "SIFA Search Youth"

2. Configure Database Connection

   • Set up a PostgreSQL credential named "Postgres account"
   • Ensure the database contains the youthEntrepreneursReal table with the required schema

3. Activate the Workflow

   • Enable the workflow to activate the webhook endpoint
   • Note the webhook URL provided by n8n

4. Test the Integration

   • Send a POST request to the webhook URL with sample search data
   • Verify that the database queries execute successfully and return expected results

5. Configure CORS (if needed)

   • The workflow includes CORS headers for cross-origin requests
   • Modify the Access-Control-Allow-Origin header if you need to restrict access to specific domains