preload
+44 330 174 0598

API Developer Guide

Overview

Welcome to the API Developer Guide. Please use the sandbox URL for testing purposes. When using the production version, ensure you have the production key and access. If you would like to opt into the program, please contact support@ecoachmanager.com.

Authentication

To access the API, you must first log in using your credentials:

POST /api/auth/login

Request

URL: /api/auth/login

Method: POST

Content-Type: application/json

Body Parameters

  • username (string) - Your username
  • password (string) - Your password

Example Request

{
  "username": "your_username",
  "password": "your_password"
}

Example Response

{
  "token": "abc123xyz456"
}

Using the Token

Include the token in the header of your API requests:

Authorization: Bearer your_token_here

Example Authenticated Request

GET /api/your_endpoint
Host: api.yourdomain.com
Authorization: Bearer abc123xyz456

IP address is not authorized

{
    "error": "Access denied: your IP address is not authorized."
}

Get Tags List

This endpoint retrieves all available tags from the system database (tb_tags_ecm). Each tag record includes its unique ID and name.

Request

URL: /api/tags

Method: GET

Content-Type: application/json

Headers

Authorization: Bearer your_token_here
AccessKey: your_secret_key_here

Example Request

GET /api/tags
Host: api.ecoachmanager.com
Authorization: Bearer abc123xyz456
AccessKey: your_secret_key_here

Notes

  • This endpoint does not require body parameters.
  • Returned list is ordered by tag_id in ascending order.
  • If no tags exist, an empty array will be returned with a success status.

Example Responses

Success

{
  "status": "success",
  "count": 66,
  "results": [
    { "tag_id": "1", "tag_name": "Verification Needed" },
    { "tag_id": "2", "tag_name": "ECM" },
    { "tag_id": "3", "tag_name": "Verification Completed" },
    { "tag_id": "4", "tag_name": "Imported from DTE" }
  ]
}

HTTP: 200 OK

No Tags Found

{
  "status": "success",
  "count": 0,
  "results": [],
  "message": "No tags found."
}

HTTP: 200 OK

Database Error

{
  "status": "error",
  "message": "Database error occurred while retrieving tags.",
  "error": "SQLSTATE[HY000]: General error",
  "code": 500
}

HTTP: 500 Internal Server Error

Unexpected Error

{
  "status": "error",
  "message": "An unexpected error occurred while retrieving tags.",
  "error": "Internal system exception",
  "code": 500
}

HTTP: 500 Internal Server Error

Replace Tag & Update Contact Log


This endpoint replaces an existing tag (oldTag) with a new one (newTag) for multiple bookings. Optionally, it also inserts a contact log entry for each updated booking when contactlog data is provided.

Request

URL: /api/tags/replace

Method: POST

Content-Type: application/json

Headers

Authorization: Bearer your_token_here
AccessKey: your_secret_key_here

Request Body

{
  "bookingIds": [1015437, 1015433],
  "oldTag": "Verification Needed",
  "newTag": "Verification Confirmed",
  "contactlog": {
    "operation": "AI Verification",
    "calledTime": "2025-11-12 03:33:33",
    "note": "Verification completed successfully. Customer confirmed details by phone.",
    "callTranscript": "AI: Hello, confirming your booking.\nCustomer: Yes, correct.\n..."
  }
}

Body Parameters

  • bookingIds (array, required) - List of booking (quote) IDs to update. Must be a non-empty array.
  • oldTag (string, required) - Existing tag name that will be replaced.
  • newTag (string, required) - Target tag name that will replace the old tag.
  • contactlog (object, optional) - If provided, a contact log entry will be created for each updated booking.
    • operation (string, default: "AI Verification") - Type of action or operation name.
    • calledTime (string, format: "YYYY-MM-DD HH:MM:SS") - The timestamp of the contact call. If missing, current time is used.
    • note (string) - Description or summary of the call.
    • callTranscript (string) - Detailed conversation text between AI and customer.

Validation Rules

  • Authentication: Requires a valid user with user_id from userPermission.
  • Booking IDs: Must be an array and not empty. Otherwise, request fails with code 400.
  • Tag Names: Both oldTag and newTag must exist in tb_tags_ecm.
  • Contact Log Format: Must be a JSON object if present; otherwise error 400.
  • Date Validation: calledTime must follow format YYYY-MM-DD HH:MM:SS. If invalid, the system rolls back and returns an error.
  • Atomicity: All updates and logs are executed within a database transaction. Any failure rolls back all changes.

Example Request

POST /api/tags/replace
Host: api.ecoachmanager.com
Authorization: Bearer abc123xyz456
AccessKey: your_secret_key_here

Example Responses

Success

{
  "status": "success",
  "message": "Processed 2 booking(s). Updated: 2, Skipped: 0",
  "updated": 2,
  "skipped": 0,
  "results": [
    {
      "quote_id": 1015437,
      "cust_id": 41828,
      "old_tag": "Verification Needed",
      "new_tag": "Verification Confirmed",
      "rows_updated": 1,
      "status": "updated",
      "contact_log_result": {
        "operation": "AI Verification",
        "dateTime": "2025-11-12 19:37:03",
        "calledTime": "2025-11-12 03:33:33",
        "note": "Verification completed successfully. Customer confirmed details by phone.",
        "callTranscript": "AI: Hello, confirming your booking.\nCustomer: Yes, correct.\n..."
      }
    }
  ]
}

HTTP: 200 OK

Partial Success (Some Skipped)

{
  "status": "success",
  "message": "Processed 3 booking(s). Updated: 2, Skipped: 1",
  "results": [
    {
      "quote_id": 1015401,
      "status": "skipped",
      "reason": "Old tag 'Verification Needed' not found."
    }
  ]
}

Missing Required Fields

{
  "status": "error",
  "error": "Missing required fields: oldTag or newTag.",
  "code": 400
}

Booking IDs Invalid

{
  "status": "error",
  "error": "Field bookingIds must be a non-empty array.",
  "code": 400
}

Tag Not Found

{
  "status": "error",
  "error": "Old tag or new tag not found in tb_tags_ecm.",
  "code": 400
}

Invalid calledTime Format

{
  "status": "error",
  "error": "Invalid calledTime format '2025/11/12 08:00'. Please use 'YYYY-MM-DD HH:MM:SS' (example: 2025-11-12 19:37:03).",
  "code": 400
}

Contactlog Must Be Object

{
  "status": "error",
  "error": "Field contactlog must be an object.",
  "code": 400
}

Internal Server Error (Rollback)

{
  "status": "error",
  "message": "Failed to update tags or insert contact logs.",
  "error": "SQLSTATE[HY000]: General error: ...",
  "code": 500
}

HTTP: 500 Internal Server Error

Group Transportation Thecoachcompany
CPT Member

contact us

sales@thecoachcompany.co.uk

Nationwide: +44 330 174 0598

Payment
Copyright © 2025 - coachcompany.co.uk             Terms and Conditions             Privacy             Sitemap             Operators             Policies and Statements             coachcompany.co.uk is a software platform facilitating or enabling the taking or communication of bookings for ODBS operators in WA