{
  "openapi": "3.1.0",
  "info": {
    "title": "Pingback Connect API",
    "description": "Public API v2 for managing contacts in Pingback Connect.",
    "version": "2.0.0",
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://connect.pingback.com/v2"
    }
  ],
  "tags": [
    {
      "name": "Contacts",
      "description": "Operations related to contacts"
    }
  ],
  "security": [
    {
      "apiKeyAuth": []
    }
  ],
  "paths": {
    "/contacts": {
      "get": {
        "tags": ["Contacts"],
        "summary": "List contacts",
        "description": "Returns a paginated list of contacts. Each page contains 10 results.",
        "parameters": [
          { "$ref": "#/components/parameters/DeveloperMode" },
          { "$ref": "#/components/parameters/ApiKey" },
          {
            "name": "page",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "example": 0
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of contacts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactListResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "page": 0,
                      "total": 2042,
                      "data": [
                        {
                          "id": "36c8c534-fcca-4f79-b3e6-c492f82c2c61",
                          "email": "henriqueapi123@gmail.com",
                          "status": "active",
                          "source": "PublicApi",
                          "origin": null,
                          "segmentedListsIds": [
                            "6a14938e-04eb-42e3-baf7-b3f78fe78f9f"
                          ],
                          "createdAt": "2025-12-22T18:11:43.719Z",
                          "attributes": {
                            "name": "Henrique Braga",
                            "value": "50000000"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "post": {
        "tags": ["Contacts"],
        "summary": "Create contact",
        "description": "Creates a new contact.",
        "parameters": [
          { "$ref": "#/components/parameters/DeveloperMode" },
          { "$ref": "#/components/parameters/ApiKey" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactCreate"
              },
              "examples": {
                "create": {
                  "value": {
                    "email": "example@email.com",
                    "origin": {
                      "url": "https://pingback.com",
                      "utmSource": "source"
                    },
                    "attributes": {
                      "name": "Henrique Braga",
                      "phone": "+5531993732129"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Contact created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactBasicResponse"
                },
                "examples": {
                  "created": {
                    "value": {
                      "id": "36c8c534-fcca-4f79-b3e6-c492f82c2c61",
                      "email": "example@email.com"
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "422": { "$ref": "#/components/responses/UnprocessableEntity" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/contacts/{email}": {
      "get": {
        "tags": ["Contacts"],
        "summary": "Get contact",
        "description": "Retrieve a contact by email.",
        "parameters": [
          { "$ref": "#/components/parameters/DeveloperMode" },
          { "$ref": "#/components/parameters/ApiKey" },
          { "$ref": "#/components/parameters/EmailPath" }
        ],
        "responses": {
          "200": {
            "description": "Contact details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Contact"
                },
                "examples": {
                  "success": {
                    "value": {
                      "id": "36c8c534-fcca-4f79-b3e6-c492f82c2c61",
                      "email": "henriqueapi123@gmail.com",
                      "status": "active",
                      "source": "PublicApi",
                      "origin": null,
                      "firstConversionEvent": null,
                      "segmentedLists": [],
                      "deals": [],
                      "createdAt": "2025-12-22T18:11:43.719Z",
                      "attributes": {
                        "name": "Henrique Braga"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "put": {
        "tags": ["Contacts"],
        "summary": "Update contact",
        "description": "Update contact attributes by email.",
        "parameters": [
          { "$ref": "#/components/parameters/DeveloperMode" },
          { "$ref": "#/components/parameters/ApiKey" },
          { "$ref": "#/components/parameters/EmailPath" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactUpdate"
              },
              "examples": {
                "update": {
                  "value": {
                    "phone": "+5531993732129",
                    "position": "developer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactBasicResponse"
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "422": { "$ref": "#/components/responses/UnprocessableEntity" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "delete": {
        "tags": ["Contacts"],
        "summary": "Delete contact",
        "description": "Delete a contact by email.",
        "parameters": [
          { "$ref": "#/components/parameters/DeveloperMode" },
          { "$ref": "#/components/parameters/ApiKey" },
          { "$ref": "#/components/parameters/EmailPath" }
        ],
        "responses": {
          "200": {
            "description": "Contact deleted"
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "DeveloperMode": {
        "name": "developer-mode",
        "in": "header",
        "required": true,
        "schema": { "type": "boolean" }
      },
      "ApiKey": {
        "name": "x-api-key",
        "in": "header",
        "required": true,
        "schema": { "type": "string" }
      },
      "EmailPath": {
        "name": "email",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "format": "email" }
      }
    },
    "schemas": {
      "ContactCreate": {
        "type": "object",
        "required": ["email"],
        "properties": {
          "email": { "type": "string", "format": "email" },
          "origin": { "$ref": "#/components/schemas/ContactOrigin" },
          "attributes": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "nullable": true
            }
          }
        }
      },
      "ContactUpdate": {
        "type": "object",
        "additionalProperties": {
          "type": "string",
          "nullable": true
        }
      },
      "ContactBasicResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "email": { "type": "string", "format": "email" }
        }
      },
      "Contact": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "email": { "type": "string", "format": "email" },
          "status": { "$ref": "#/components/schemas/ContactStatus" },
          "source": { "$ref": "#/components/schemas/ContactSource" },
          "origin": {
            "$ref": "#/components/schemas/ContactOrigin",
            "nullable": true
          },
          "firstConversionEvent": { "type": ["object", "null"] },
          "segmentedLists": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/SegmentedList" }
          },
          "deals": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Deal" }
          },
          "createdAt": { "type": "string", "format": "date-time" },
          "attributes": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "nullable": true
            }
          }
        }
      },
      "ContactListResponse": {
        "type": "object",
        "properties": {
          "page": { "type": "integer" },
          "total": { "type": "integer" },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ContactListItem" }
          }
        }
      },
      "ContactListItem": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "email": { "type": "string", "format": "email" },
          "status": { "$ref": "#/components/schemas/ContactStatus" },
          "source": { "$ref": "#/components/schemas/ContactSource" },
          "origin": {
            "$ref": "#/components/schemas/ContactOrigin",
            "nullable": true
          },
          "segmentedListsIds": {
            "type": "array",
            "items": { "type": "string", "format": "uuid" }
          },
          "createdAt": { "type": "string", "format": "date-time" },
          "attributes": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "nullable": true
            }
          }
        }
      },
      "ContactOrigin": {
        "type": "object",
        "properties": {
          "url": { "type": "string" },
          "utmSource": { "type": "string" },
          "utmCampaign": { "type": "string" },
          "utmMedium": { "type": "string" },
          "utmTerm": { "type": "string" },
          "utmContent": { "type": "string" }
        }
      },
      "SegmentedList": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "Deal": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "pipelineId": { "type": "string", "format": "uuid" },
          "stageId": { "type": "string", "format": "uuid" },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "deletedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          }
        }
      },
      "ContactStatus": {
        "type": "string",
        "enum": [
          "active",
          "inactive",
          "invalid",
          "unverified",
          "unsubscribed",
          "bounced",
          "complained"
        ]
      },
      "ContactSource": {
        "type": "string",
        "enum": [
          "Form",
          "PublicApi",
          "Import",
          "User",
          "Blog",
          "System",
          "Webhook"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "integer" },
          "message": { "type": "string" }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Request body missing or malformed",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "UnprocessableEntity": {
        "description": "Validation error",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Conflict": {
        "description": "Contact conflict",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "NotFound": {
        "description": "Contact not found",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Forbidden": {
        "description": "Invalid or missing API key",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    }
  }
}