{ "openapi": "3.1.0", "info": { "title": "Wi Grow API", "version": "1.0.0", "description": "REST API for Wi Grow by Wi Develop. JSON over HTTPS.\n\n**Authentication:** create a key in the app (Developer API) and send it as `Authorization: Bearer wg_\u2026`. Keys have the `read` and/or `write` permission and belong to one business.\n\n**Plan:** the API is available on plans that include \"Developer API access\".\n\n**Rate limit:** per key, per minute (60 by default). Every response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`; over the limit you get 429 with `Retry-After`.\n\n**Pagination:** `page` and `per_page` (1\u2013100, default 25); lists return `data`, `meta` and `links`.\n\n**Idempotency:** POST requests accept an `Idempotency-Key` header (kept 24 hours). A retry with the same key and body returns the first response with `Idempotent-Replayed: true`.\n\n**Errors:** always `{\"error\": {\"code\", \"message\", \"details\"?}}`.\n\n**Versioning:** the version is in the path (`/api/v1`). Fields may be added within v1; nothing is removed or renamed without a new version.", "contact": { "name": "Wi Develop", "url": "https://widevelop.us" } }, "servers": [ { "url": "{baseUrl}/api/v1", "variables": { "baseUrl": { "default": "https://wigrow.example", "description": "Your Wi Grow address" } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account" }, { "name": "Leads" }, { "name": "Email" }, { "name": "CRM" }, { "name": "Webhooks" } ], "paths": { "/me": { "get": { "operationId": "getMe", "summary": "The key and its workspace", "tags": [ "Account" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Me" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-scope": "read" } }, "/balances": { "get": { "operationId": "getBalances", "summary": "Lead, credit and pay-as-you-go balances", "tags": [ "Account" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Balances" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-scope": "read" } }, "/usage": { "get": { "operationId": "listUsage", "summary": "Usage transactions (balance history)", "tags": [ "Account" ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "leads", "credits", "balance" ] }, "description": "Only leads, credits or the pay-as-you-go balance (amounts in minor units)." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Entries on or after this time." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageEntry" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" } }, "/business-profile": { "get": { "operationId": "getBusinessProfile", "summary": "Your business profile", "tags": [ "Account" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/BusinessProfile" }, { "type": "null" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-scope": "read" } }, "/customer-profiles": { "get": { "operationId": "listCustomerProfiles", "summary": "Ideal customer profiles", "tags": [ "Leads" ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerProfile" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" } }, "/contacts": { "get": { "operationId": "listContacts", "summary": "Leads (contacts)", "tags": [ "Leads" ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "lead_status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "new", "qualified", "needs_review", "disqualified" ] }, "description": "Filter by lead status." }, { "name": "company_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Only leads at this company." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Search name or email." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Changed on or after this time (for syncing)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" }, "post": { "operationId": "createContact", "summary": "Add a lead", "description": "Same checks as a CSV import: email format, your do-not-contact list and duplicates. No leads or credits are charged. Send an Idempotency-Key header to retry safely.", "parameters": [ { "$ref": "#/components/parameters/idempotency" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewContact" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "202": { "description": "Possible duplicate: held for review in the app", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "null" }, "status": { "type": "string", "const": "held_for_review" }, "message": { "type": "string" } } } } } }, "409": { "description": "Already in your leads (code \"duplicate\", details.contact_id), or an Idempotency-Key conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid fields, or the person is on your do-not-contact list (code \"suppressed\").", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-scope": "write", "tags": [ "Leads" ] } }, "/contacts/{contact}": { "get": { "operationId": "getContact", "summary": "One lead", "tags": [ "Leads" ], "parameters": [ { "name": "contact", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" } }, "/companies": { "get": { "operationId": "listCompanies", "summary": "Companies", "tags": [ "Leads" ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by name." }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact domain, e.g. acme.com." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" } }, "/companies/{company}": { "get": { "operationId": "getCompany", "summary": "One company", "tags": [ "Leads" ], "parameters": [ { "name": "company", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Company" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" } }, "/campaigns": { "get": { "operationId": "listCampaigns", "summary": "Campaigns", "tags": [ "Email" ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "active", "paused", "completed", "cancelled" ] }, "description": "Filter by status." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" } }, "/campaigns/{campaign}": { "get": { "operationId": "getCampaign", "summary": "One campaign", "tags": [ "Email" ], "parameters": [ { "name": "campaign", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Campaign" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" } }, "/conversations": { "get": { "operationId": "listConversations", "summary": "Conversations (sales inbox)", "tags": [ "Email" ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "needs_reply", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Only conversations waiting for your answer." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Only this lead." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" } }, "/conversations/{conversation}": { "get": { "operationId": "getConversation", "summary": "One conversation with its messages", "tags": [ "Email" ], "parameters": [ { "name": "conversation", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Conversation" }, { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" } }, "/opportunities": { "get": { "operationId": "listOpportunities", "summary": "Opportunities (deals)", "tags": [ "CRM" ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "won", "lost" ] }, "description": "Filter by status." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" } }, "/opportunities/{opportunity}": { "get": { "operationId": "getOpportunity", "summary": "One opportunity", "tags": [ "CRM" ], "parameters": [ { "name": "opportunity", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Opportunity" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" } }, "/meetings": { "get": { "operationId": "listMeetings", "summary": "Meetings", "tags": [ "CRM" ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Starting on or after." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Starting before." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Meeting" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" } }, "/meetings/{meeting}": { "get": { "operationId": "getMeeting", "summary": "One meeting", "tags": [ "CRM" ], "parameters": [ { "name": "meeting", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Meeting" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" } }, "/webhooks": { "get": { "operationId": "listWebhooks", "summary": "Webhook endpoints", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" }, "post": { "operationId": "createWebhook", "summary": "Add a webhook endpoint", "description": "The URL must be a public https address. The response contains the signing secret, shown only this once.", "parameters": [ { "$ref": "#/components/parameters/idempotency" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "contact.created", "reply.received", "meeting.scheduled", "opportunity.won" ] } } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "example": "whsec_\u2026" } } } ] } } } } } }, "409": { "description": "Idempotency-Key conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-scope": "write", "tags": [ "Webhooks" ] } }, "/webhooks/{webhook}": { "get": { "operationId": "getWebhook", "summary": "One endpoint with its last 20 deliveries", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "recent_deliveries": { "type": "array", "items": { "type": "object" } } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-scope": "read" }, "delete": { "operationId": "deleteWebhook", "summary": "Remove a webhook endpoint", "parameters": [ { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Removed" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-scope": "write", "tags": [ "Webhooks" ] } } }, "webhooks": { "contact.created": { "post": { "summary": "A lead was added (research, import, the API or by hand).", "parameters": [ { "name": "Wi-Grow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\" using your endpoint secret>. Reject if the time is more than 5 minutes off." }, { "name": "Wi-Grow-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "contact.created" } }, { "name": "Wi-Grow-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "type": "string", "const": "contact.created" }, "data": { "$ref": "#/components/schemas/Contact" } } } ] } } } }, "responses": { "2XX": { "description": "Any 2xx means received. Anything else (or no answer within 10 seconds) is retried after 1 min, 5 min, 30 min, 2 h and 6 h; 15 failures in a row switch the endpoint off." } } } }, "reply.received": { "post": { "summary": "A lead replied to an email.", "parameters": [ { "name": "Wi-Grow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\" using your endpoint secret>. Reject if the time is more than 5 minutes off." }, { "name": "Wi-Grow-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "reply.received" } }, { "name": "Wi-Grow-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "type": "string", "const": "reply.received" }, "data": { "type": "object", "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "contact_id": { "type": [ "integer", "null" ] }, "from": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "received_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } ] } } } }, "responses": { "2XX": { "description": "Any 2xx means received. Anything else (or no answer within 10 seconds) is retried after 1 min, 5 min, 30 min, 2 h and 6 h; 15 failures in a row switch the endpoint off." } } } }, "meeting.scheduled": { "post": { "summary": "A meeting was confirmed in the calendar.", "parameters": [ { "name": "Wi-Grow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\" using your endpoint secret>. Reject if the time is more than 5 minutes off." }, { "name": "Wi-Grow-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "meeting.scheduled" } }, { "name": "Wi-Grow-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "type": "string", "const": "meeting.scheduled" }, "data": { "$ref": "#/components/schemas/Meeting" } } } ] } } } }, "responses": { "2XX": { "description": "Any 2xx means received. Anything else (or no answer within 10 seconds) is retried after 1 min, 5 min, 30 min, 2 h and 6 h; 15 failures in a row switch the endpoint off." } } } }, "opportunity.won": { "post": { "summary": "A deal was marked won.", "parameters": [ { "name": "Wi-Grow-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\" using your endpoint secret>. Reject if the time is more than 5 minutes off." }, { "name": "Wi-Grow-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "opportunity.won" } }, { "name": "Wi-Grow-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "type": "string", "const": "opportunity.won" }, "data": { "$ref": "#/components/schemas/Opportunity" } } } ] } } } }, "responses": { "2XX": { "description": "Any 2xx means received. Anything else (or no answer within 10 seconds) is retried after 1 min, 5 min, 30 min, 2 h and 6 h; 15 failures in a row switch the endpoint off." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "wg_ + 40 characters", "description": "API key from the app. Shown once when created; stored only as a hash." } }, "parameters": { "page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "per_page": { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "idempotency": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Any unique string (1\u2013120 visible ASCII characters) to make retries safe." } }, "responses": { "Unauthenticated": { "description": "Missing, wrong, revoked or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthenticated", "message": "Missing, wrong, revoked or expired API key." } } } } }, "Forbidden": { "description": "The key lacks the permission (insufficient_scope), the plan has no API access (plan_required) or the account is suspended (account_suspended).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission (insufficient_scope), the plan has no API access (plan_required) or the account is suspended (account_suspended)." } } } } }, "NotFound": { "description": "Not found (or not in your business).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Not found (or not in your business)." } } } } }, "ValidationFailed": { "description": "Some fields are not valid; see details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Some fields are not valid; see details." } } } } }, "RateLimited": { "description": "Too many requests.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code, e.g. not_found, validation_failed, insufficient_scope, rate_limited, duplicate, suppressed." }, "message": { "type": "string" }, "details": { "type": "object", "description": "Field errors (validation_failed) or extra information.", "additionalProperties": true } } } } }, "PageMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } } }, "PageLinks": { "type": "object", "properties": { "next": { "type": [ "string", "null" ], "format": "uri" }, "prev": { "type": [ "string", "null" ], "format": "uri" } } }, "Me": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "name": { "type": "string" } } }, "key": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string", "example": "wg_7Kd2xQab" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "write" ] } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "Balances": { "type": "object", "properties": { "leads": { "type": "integer" }, "credits": { "type": "integer" }, "balance": { "type": "integer", "description": "Pay-as-you-go balance in minor units of the currency (cents for USD)." }, "currency": { "type": "string" } } }, "UsageEntry": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string", "enum": [ "leads", "credits", "balance" ] }, "type": { "type": "string", "enum": [ "grant", "consume", "reserve", "release", "expire", "revoke", "adjust" ] }, "quantity": { "type": "integer", "description": "Positive adds to the balance, negative spends." }, "balance_after": { "type": "integer" }, "reference_type": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BusinessProfile": { "type": "object", "properties": { "business_name": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "products_services": { "type": [ "string", "null" ] }, "value_proposition": { "type": [ "string", "null" ] }, "customer_types": {}, "target_countries": {}, "target_markets": {}, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CustomerProfile": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "industries": { "type": "array", "items": { "type": "string" } }, "keywords": { "type": "array", "items": { "type": "string" } }, "company_sizes": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } }, "job_titles": { "type": "array", "items": { "type": "string" } }, "seniorities": { "type": "array", "items": { "type": "string" } }, "departments": { "type": "array", "items": { "type": "string" } }, "excluded_industries": { "type": "array", "items": { "type": "string" } }, "min_score": { "type": [ "integer", "null" ] }, "require_email": { "type": "boolean" }, "archived": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Company": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "size_range": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Contact": { "type": "object", "properties": { "id": { "type": "integer" }, "full_name": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "job_title": { "type": [ "string", "null" ] }, "seniority": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "stage": { "type": [ "string", "null" ] }, "email_status": { "type": [ "string", "null" ], "enum": [ "verified", "accept_all", "unverified", "invalid", "unknown", "none", null ] }, "lead_status": { "type": "string", "enum": [ "new", "qualified", "needs_review", "disqualified" ] }, "score": { "type": [ "integer", "null" ] }, "acquisition": { "type": "string", "enum": [ "research", "credits", "import", "manual", "duplicate_review", "api" ] }, "company": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "domain": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "last_interaction_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "NewContact": { "type": "object", "description": "A name or an email address is required, and a company name or website.", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "full_name": { "type": "string" }, "email": { "type": "string" }, "job_title": { "type": "string" }, "company_name": { "type": "string" }, "website": { "type": "string" }, "industry": { "type": "string" }, "company_size": { "type": "string" }, "country": { "type": "string" }, "linkedin": { "type": "string" }, "icp_id": { "type": "integer", "description": "Score the lead against this customer profile." } } }, "Campaign": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "objective": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "completed", "cancelled" ] }, "timezone": { "type": "string" }, "send_days": { "type": "array", "items": { "type": "integer" } }, "window_start": { "type": "string" }, "window_end": { "type": "string" }, "daily_limit": { "type": "integer" }, "paused_reason": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subject": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "needs_reply": { "type": "boolean" }, "unread": { "type": "boolean" }, "contact_id": { "type": [ "integer", "null" ] }, "campaign_id": { "type": [ "string", "null" ], "format": "uuid" }, "last_message_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Message": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "sent", "received" ] }, "kind": { "type": "string", "enum": [ "reply", "auto_reply", "bounce" ] }, "from": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "intent": { "type": [ "string", "null" ] }, "at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Opportunity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "won", "lost" ] }, "stage": { "type": [ "string", "null" ] }, "currency": { "type": "string", "example": "USD" }, "estimated_value": { "type": [ "integer", "null" ], "description": "Minor units (cents)." }, "actual_value": { "type": [ "integer", "null" ], "description": "Agreed amount in minor units, won deals only." }, "expected_close_date": { "type": [ "string", "null" ], "format": "date" }, "company_id": { "type": [ "integer", "null" ] }, "contact_id": { "type": [ "integer", "null" ] }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "lost_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Meeting": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "scheduled", "unknown", "failed", "cancelled", "logged" ] }, "starts_at": { "type": [ "string", "null" ], "format": "date-time" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time" }, "timezone": { "type": "string" }, "location": { "type": [ "string", "null" ] }, "conference_url": { "type": [ "string", "null" ] }, "contact_id": { "type": [ "integer", "null" ] }, "opportunity_id": { "type": [ "string", "null" ], "format": "uuid" }, "attendees": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "response": { "type": [ "string", "null" ] } } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "contact.created", "reply.received", "meeting.scheduled", "opportunity.won" ] } }, "active": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookEnvelope": { "type": "object", "description": "Body of every webhook delivery. Verify the Wi-Grow-Signature header before trusting it.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Delivery id; the same id is sent again on retries, so use it to ignore duplicates." }, "event": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "data": { "type": "object" } } } } } }