{
  "openapi": "3.1.0",
  "info": {
    "title": "SMS Philippines Contact API",
    "version": "1.0.0",
    "description": "Manage contact groups and contacts. Mobile numbers are accepted in 09XXXXXXXXX, +639XXXXXXXXX or 639XXXXXXXXX form and normalized to 639XXXXXXXXX. Typical flow: create a group, create contacts, then add those contacts to the group.",
    "contact": { "url": "https://smsphilippines.com/developers" }
  },
  "externalDocs": { "url": "https://smsphilippines.com/developers" },
  "servers": [{ "url": "https://api.contact.smsphilippines.com" }],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/groups": {
      "post": {
        "operationId": "createGroup",
        "summary": "Create a group",
        "description": "Group names must be unique per account.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": { "name": { "type": "string" }, "description": { "type": "string" } }
              },
              "example": { "name": "Weekend Sale", "description": "Customers opted in for weekend promos" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Group created.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "data": {
                    "group": {
                      "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
                      "name": "Weekend Sale",
                      "description": "Customers opted in for weekend promos",
                      "created_at": "2026-09-10T02:00:00.000Z"
                    }
                  },
                  "error": null
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "get": {
        "operationId": "listGroups",
        "summary": "List groups",
        "description": "Each group includes a live contact_count.",
        "responses": {
          "200": {
            "description": "Your groups.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "data": {
                    "groups": [
                      {
                        "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
                        "name": "Weekend Sale",
                        "description": "Customers opted in for weekend promos",
                        "created_at": "2026-09-10T02:00:00.000Z",
                        "contact_count": 2
                      }
                    ],
                    "returned": 1
                  },
                  "error": null
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/contacts": {
      "post": {
        "operationId": "createContacts",
        "summary": "Create contacts",
        "description": "contact may be a single object or an array. Accepted immediately and processed in the background (202); the contacts are not necessarily queryable the instant this call returns.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["contact"],
                "properties": {
                  "contact": {
                    "oneOf": [
                      { "$ref": "#/components/schemas/ContactInput" },
                      { "type": "array", "items": { "$ref": "#/components/schemas/ContactInput" } }
                    ]
                  }
                }
              },
              "example": {
                "contact": [
                  { "mobile_number": "09171234567", "first_name": "Juan", "last_name": "Dela Cruz" },
                  { "mobile_number": "09181234567", "first_name": "Maria", "last_name": "Santos" }
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Contacts accepted for background processing.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "data": { "upload_id": "4b1e6f2a-1c2d-4e3f-9a0b-1c2d3e4f5a6b", "accepted": 2, "chunks": 1, "message": "Accepted 2 contacts for processing" },
                  "error": null
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "413": { "description": "Import exceeds the 15MB limit." }
        }
      }
    },
    "/groups/contacts": {
      "post": {
        "operationId": "addContactsToGroup",
        "summary": "Add contacts to a group",
        "description": "All-or-nothing: if any contact_id doesn't belong to your account, nothing is added and the response lists the offending ids.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["group_id", "contact_ids"],
                "properties": {
                  "group_id": { "type": "string", "format": "uuid" },
                  "contact_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }
                }
              },
              "example": { "group_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "contact_ids": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"] }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contacts added.",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "data": { "group_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "requested": 1, "added": 1, "already_members": 0 },
                  "error": null
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "description": "The group was not found on your account." }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key from the SMS Philippines dashboard." }
    },
    "schemas": {
      "ContactInput": {
        "type": "object",
        "required": ["mobile_number"],
        "properties": {
          "mobile_number": { "type": "string" },
          "first_name": { "type": "string" },
          "last_name": { "type": "string" }
        }
      }
    },
    "responses": {
      "BadRequest": { "description": "Missing or invalid fields." },
      "Unauthorized": { "description": "Missing or invalid API key (MISSING_AUTH)." }
    }
  }
}