Skip to main content
POST
/
api
/
serviceRequests
/
createServiceRequest
Create Service Request
curl --request POST \
  --url https://api.example.com/api/serviceRequests/createServiceRequest \
  --header 'Content-Type: application/json' \
  --data '
{
  "request_id": 123,
  "customer_id": 123,
  "applicant_name": "<string>",
  "service_type": 123,
  "address": "<string>",
  "department": 123,
  "email": "<string>",
  "whatsapp": "<string>",
  "phone": "<string>",
  "ext": "<string>",
  "addressObj": {
    "address_formatted": "<string>",
    "address_place_id": "<string>",
    "description": "<string>",
    "lat": 123,
    "lng": 123,
    "address_components": {}
  },
  "requested_delivery_date": "<string>",
  "comments": "<string>",
  "company_name": "<string>",
  "tax_id": "<string>",
  "vendor_id": 123,
  "changed_by": 123,
  "change_reason": "<string>"
}
'
{
  "success": true,
  "request": {
    "request": {
      "request_id": 123,
      "request_uuid": "<string>",
      "customer_id": 123,
      "contact_name": "<string>",
      "contact_email": "<string>",
      "contact_phone": "<string>",
      "whatsapp": "<string>",
      "service_type": 123,
      "service_type_name": "<string>",
      "department_id": 123,
      "department_name": "<string>",
      "address": "<string>",
      "requested_delivery_date": "<string>",
      "comments": "<string>",
      "created_at": "<string>",
      "created_by": 123,
      "current_status": 123,
      "company_name": "<string>",
      "tax_id": "<string>"
    },
    "assignment": {
      "assignment_id": 123,
      "vendor_id": 123,
      "vendor_name": "<string>",
      "vendor_email": "<string>",
      "vendor_phone": "<string>",
      "assigned_at": "<string>",
      "is_current": true
    },
    "error": "<string>"
  }
}

​
Overview

Creates a new service request in the system. The endpoint handles:
  • Request creation with full contact and service details
  • Automatic or manual vendor assignment
  • Multi-channel notifications (email, WhatsApp, push, web)
  • Address geocoding and validation
  • SLA tracking initialization

​
Request Body

​
Core Fields

​
request_id
integer
If provided, updates an existing request instead of creating new one
​
customer_id
integer
Customer ID if request is for an existing customer
​
applicant_name
string
required
Full name of the person requesting the service
​
service_type
integer
required
Service type ID (e.g., PTAR installation, maintenance, etc.)
​
address
string
required
Service delivery address (plain text)
​
department
integer
required
Department ID for the service location

​
Contact Information

​
email
string
Contact email address
​
whatsapp
string
WhatsApp number in international format (e.g., +502 5555-1234)
​
phone
string
Phone number (required if whatsapp is not provided)
​
ext
string
Phone extension number

​
Address Object

​
addressObj
object
Structured address information from geocoding
​
address_formatted
string
Formatted address string
​
address_place_id
string
Google Maps Place ID
​
description
string
Address description
​
lat
number
Latitude coordinate
​
lng
number
Longitude coordinate
​
address_components
object
Detailed address components from geocoding API

​
Additional Fields

​
requested_delivery_date
string
Requested delivery date in ISO 8601 format
​
comments
string
Additional comments or special instructions
​
company_name
string
Company name if applicable
​
tax_id
string
Tax ID (NIT) of the applicant
​
vendor_id
integer
Manually assign request to specific vendor (overrides automatic assignment)
​
changed_by
integer
User ID creating/updating the request
​
change_reason
string
Reason for creating/updating (used for audit trail)

​
Response Fields

​
success
boolean
required
Indicates if the request was created successfully
​
request
object
required
Created request details
​
request
object
The created service request
​
request_id
integer
Unique request identifier
​
request_uuid
string
UUID for public tracking
​
customer_id
integer
Associated customer ID
​
contact_name
string
Contact person name
​
contact_email
string
Contact email
​
contact_phone
string
Contact phone
​
whatsapp
string
WhatsApp number
​
service_type
integer
Service type ID
​
service_type_name
string
Service type name
​
department_id
integer
Department ID
​
department_name
string
Department name
​
address
string
Service address
​
requested_delivery_date
string
Requested delivery date
​
comments
string
Additional comments
​
created_at
string
Creation timestamp (ISO 8601)
​
created_by
integer
User who created the request
​
current_status
integer
Initial status (typically 1 for created)
​
company_name
string
Company name
​
tax_id
string
Tax ID
​
assignment
object
Vendor assignment details
​
assignment_id
integer
Assignment record ID
​
vendor_id
integer
Assigned vendor user ID
​
vendor_name
string
Vendor full name
​
vendor_email
string
Vendor email address
​
vendor_phone
string
Vendor phone number
​
assigned_at
string
Assignment timestamp (ISO 8601)
​
is_current
boolean
Whether this is the current active assignment
​
error
string
Error message if creation failed

​
Request Lifecycle

When a service request is created:
  1. Validation: Required fields are validated (name, service type, address, department, contact method)
  2. Creation: Request is inserted via fn_create_service_request database function
  3. Vendor Assignment:
    • If vendor_id provided: Manual assignment to specified vendor
    • Otherwise: Automatic assignment based on workload and service line
  4. Notifications: Multi-channel notifications sent to:
    • Vendor: Email, WhatsApp, web, and push notifications with request details
    • Client: Email or WhatsApp confirmation with tracking link
  5. Status: Initial status set to 1 (Created)

​
Notification Templates

​
Vendor Notification (WhatsApp)

Template: nueva_solicitud_de_servicio
  • Request ID
  • Service type
  • Contact name and phone
  • Service address
  • Requested date
  • Tracking link button

​
Client Notification (WhatsApp)

Template: solicitud_recibida_cliente (requires HTTPS logo URL)
  • Client name
  • Request ID
  • Service type
  • Requested date
  • Vendor contact email

​
Email Notifications

Both vendor and client receive HTML emails with:
  • Request details table
  • Call-to-action button to view request
  • Next steps information

​
Example Request

curl -X POST https://api.ambiotec-sa.com/api/serviceRequests/createServiceRequest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "applicant_name": "María González",
    "service_type": 1,
    "address": "5a Avenida 12-34 Zona 9, Guatemala",
    "department": 5,
    "email": "[email protected]",
    "phone": "+502 2234-5678",
    "whatsapp": "+502 5555-9876",
    "company_name": "Industrias Ejemplo S.A.",
    "tax_id": "98765432-1",
    "requested_delivery_date": "2026-04-20T00:00:00Z",
    "comments": "Requiere instalación urgente",
    "changed_by": 42,
    "addressObj": {
      "address_formatted": "5a Avenida 12-34, Zona 9, Guatemala, Guatemala",
      "address_place_id": "ChIJXZSrXXb3YI8RYV4hnz7K7Y4",
      "description": "5a Avenida 12-34 Zona 9",
      "lat": 14.6099,
      "lng": -90.5252,
      "address_components": {
        "street_number": "12-34",
        "route": "5a Avenida",
        "locality": "Guatemala",
        "administrative_area_level_1": "Guatemala",
        "country": "Guatemala"
      }
    }
  }'

​
Example Response

{
  "success": true,
  "request": {
    "fn_create_service_request": {
      "request": {
        "request_id": 12346,
        "request_uuid": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
        "customer_id": null,
        "contact_name": "María González",
        "contact_email": "[email protected]",
        "contact_phone": "+502 2234-5678",
        "whatsapp": "+502 5555-9876",
        "service_type": 1,
        "service_type_name": "PTAR Installation",
        "department_id": 5,
        "department_name": "Guatemala",
        "address": "5a Avenida 12-34, Zona 9, Guatemala, Guatemala",
        "requested_delivery_date": "2026-04-20T00:00:00Z",
        "comments": "Requiere instalación urgente",
        "created_at": "2026-03-03T10:30:45Z",
        "created_by": 42,
        "current_status": 1,
        "company_name": "Industrias Ejemplo S.A.",
        "tax_id": "98765432-1"
      },
      "assignment": {
        "assignment_id": 789,
        "vendor_id": 25,
        "vendor_name": "Carlos Méndez",
        "vendor_email": "[email protected]",
        "vendor_phone": "+502 5551-2345",
        "assigned_at": "2026-03-03T10:30:45Z",
        "is_current": true
      }
    }
  }
}

​
Error Responses

​
400 Bad Request - Missing Required Fields

{
  "error": "applicant_name es obligatorio"
}

{
  "error": "service_type es obligatorio"
}

{
  "error": "address es obligatorio"
}

{
  "error": "department es obligatorio"
}

{
  "error": "Debe enviar al menos uno: phone o whatsapp"
}

​
500 Internal Server Error

{
  "error": "Error al crear la solicitud de servicio"
}

​
Notes

  • Contact Requirement: At least one of phone or whatsapp must be provided
  • Vendor Assignment: If vendor_id is not specified, the system automatically assigns a vendor based on service line and workload distribution
  • Manual Assignment: When vendor_id is provided, the request is assigned to that specific vendor using fn_reassign_seller
  • Geocoding: The addressObj should contain geocoded address information for better location tracking
  • Notifications:
    • Vendor receives notifications via email, WhatsApp (if phone available), web, and push
    • Client receives email (if provided) or WhatsApp notification
    • System sends copy of vendor email to [email protected]
  • WhatsApp Requirements:
    • Client WhatsApp notification requires WHATSAPP_BRAND_LOGO_URL to be configured with HTTPS URL
    • Templates must be pre-approved in WhatsApp Business API
  • Tracking: Each request gets a UUID for public tracking via /window-tracking/{request_uuid} endpoint
  • Audit Trail: Use changed_by and change_reason for audit logging

Build docs developers (and LLMs) love

Get started for freeTalk to us