{
  "openapi": "3.1.0",
  "info": {
    "title": "Run My Ads API",
    "version": "1.0.0",
    "description": "The endpoints the Run My Ads Zapier app uses: test the key, subscribe to New Lead, New Booked Call and New Ad Alert webhooks, and send booked calls and sales back. Human-readable docs: https://runmyads.com/docs/api",
    "contact": {
      "email": "support@runmyads.com"
    }
  },
  "externalDocs": {
    "url": "https://runmyads.com/docs/api"
  },
  "servers": [
    {
      "url": "https://app.runmyads.com"
    }
  ],
  "security": [
    {
      "bearerKey": []
    },
    {
      "apiKeyHeader": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "The account's Conversions key (starts with vcbo_). An admin makes it at https://app.runmyads.com/ads/conversions."
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "The same Conversions key, in this header instead."
      }
    }
  },
  "paths": {
    "/api/webhooks/rma/zapier/auth": {
      "get": {
        "operationId": "testKey",
        "summary": "Test the key",
        "responses": {
          "200": {
            "description": "The key works.",
            "content": {
              "application/json": {
                "example": {
                  "ok": true,
                  "agency_name": "Acme Roofing"
                }
              }
            }
          },
          "401": {
            "description": "No key, or the key is wrong or retired."
          },
          "429": {
            "description": "Too many calls a minute with one key."
          },
          "503": {
            "description": "A temporary problem. Try again shortly."
          }
        }
      }
    },
    "/api/webhooks/rma/zapier/subscribe": {
      "post": {
        "operationId": "subscribeWebhook",
        "summary": "Subscribe a webhook",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "event",
                  "target_url"
                ],
                "properties": {
                  "event": {
                    "type": "string",
                    "enum": [
                      "ads.lead_created",
                      "ads.call_booked",
                      "ads.alert"
                    ]
                  },
                  "target_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "A Zapier hook address on hooks.zapier.com."
                  }
                }
              },
              "example": {
                "event": "ads.lead_created",
                "target_url": "https://hooks.zapier.com/hooks/standard/1234567/abcdef/"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Subscribed.",
            "content": {
              "application/json": {
                "example": {
                  "id": "3b2a8c1d-5e4f-4a6b-9c8d-7e6f5a4b3c2d"
                }
              }
            }
          },
          "400": {
            "description": "Unknown event, a target_url that is not a Zapier hook address, or a body that is not JSON."
          },
          "401": {
            "description": "No key, or the key is wrong or retired."
          },
          "413": {
            "description": "The body is over 16 KB."
          },
          "429": {
            "description": "Too many calls a minute with one key."
          },
          "503": {
            "description": "A temporary problem. Try again shortly."
          }
        }
      },
      "delete": {
        "operationId": "unsubscribeWebhook",
        "summary": "Unsubscribe a webhook",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removed.",
            "content": {
              "application/json": {
                "example": {
                  "ok": true
                }
              }
            }
          },
          "400": {
            "description": "id is missing or not a valid id."
          },
          "401": {
            "description": "No key, or the key is wrong or retired."
          },
          "429": {
            "description": "Too many calls a minute with one key."
          },
          "503": {
            "description": "A temporary problem. Try again shortly."
          }
        }
      }
    },
    "/api/webhooks/rma/zapier/triggers": {
      "get": {
        "operationId": "sampleRecord",
        "summary": "Get a made-up sample record for a trigger",
        "parameters": [
          {
            "name": "event",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "ads.lead_created",
                "ads.call_booked",
                "ads.alert"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list with one sample record.",
            "content": {
              "application/json": {
                "example": [
                  {
                    "id": "9f1c5a2e-7b3d-4c8a-9e11-2f6d8b4a0c73",
                    "first_name": "Jane",
                    "last_name": "Doe",
                    "email": "jane@example.com",
                    "phone": "+15551234567",
                    "state": "TX",
                    "zip": "77002",
                    "created_at": "2026-10-29T14:32:00.000Z",
                    "source": "lead_form",
                    "platform": "meta",
                    "campaign_id": "120210000000000001",
                    "adset_id": "120210000000000002",
                    "ad_id": "120210000000000003",
                    "event_id": "lead_9f1c5a2e",
                    "occurred_at": "2026-10-29T14:32:00.000Z"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "event is missing or unknown."
          },
          "401": {
            "description": "No key, or the key is wrong or retired."
          },
          "429": {
            "description": "Too many calls a minute with one key."
          },
          "503": {
            "description": "A temporary problem. Try again shortly."
          }
        }
      }
    },
    "/api/webhooks/rma/conversions": {
      "post": {
        "operationId": "sendResult",
        "summary": "Send a result (lead, booked call, sale and more)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "event"
                ],
                "description": "Send email or phone (or both). order_id is required for resold and cross_sold.",
                "properties": {
                  "event": {
                    "type": "string",
                    "enum": [
                      "lead",
                      "contacted",
                      "booked",
                      "showed",
                      "sold",
                      "resold",
                      "cross_sold",
                      "refund",
                      "bad_lead"
                    ]
                  },
                  "email": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string"
                  },
                  "first_name": {
                    "type": "string"
                  },
                  "last_name": {
                    "type": "string"
                  },
                  "value": {
                    "type": "number"
                  },
                  "currency": {
                    "type": "string",
                    "description": "Three letters, for example USD."
                  },
                  "order_id": {
                    "type": "string"
                  },
                  "external_id": {
                    "type": "string"
                  },
                  "occurred_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Within the last two years."
                  },
                  "test": {
                    "type": "boolean",
                    "description": "true checks the connection and the match, and saves nothing."
                  },
                  "source": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "event": "sold",
                "source": "zapier",
                "email": "jane@example.com",
                "value": 1200,
                "currency": "USD",
                "external_id": "deal_123"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Read and saved.",
            "content": {
              "application/json": {
                "example": {
                  "ok": true,
                  "matched": true,
                  "event_id": "crm_webhook:deal_123:sold",
                  "duplicate": false
                }
              }
            }
          },
          "400": {
            "description": "The body cannot be read; the reply's error says what to fix."
          },
          "401": {
            "description": "No key, or the key is wrong or retired."
          },
          "404": {
            "description": "No key was sent, or it does not start with vcbo_."
          },
          "413": {
            "description": "The body is over 512 KB, or more than 100 events."
          },
          "429": {
            "description": "Too many calls a minute with one key."
          },
          "503": {
            "description": "A temporary problem. Try again shortly."
          }
        }
      }
    }
  }
}