{"openapi":"3.1.0","info":{"title":"LocalCitationPro Agency API","version":"1.0.0","summary":"Order citation building and other local SEO packages from prepaid agency credit; track orders; download reports.","description":"Authenticate every call with `Authorization: Bearer lcp_live_…` (keys are created on the agency dashboard at /my-orders/agency/). All prices are decided by the server from the catalogue and your agency discount — never send a price. Placing an order charges your prepaid credit immediately and cannot be undone through the API. Recommended flow for an assistant: GET /me/ (balance) → GET /packages/ (codes, prices) → POST /quote/ (confirm with the human) → POST /orders/ with an Idempotency-Key → GET /orders/{orderNumber}/ for status and the report. Paths end with a trailing slash. Optional: PUT /webhook/ with an https URL to be POSTed a signed order.delivered message instead of polling.","contact":{"email":"info@localcitationpro.com","url":"https://localcitationpro.com/agency-api/"}},"servers":[{"url":"https://localcitationpro.com/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"lcp_live_…"}},"schemas":{"OrderRequest":{"type":"object","required":["planCode","business"],"properties":{"planCode":{"type":"string","description":"Package code from GET /packages/, e.g. CITE-02","example":"CITE-02"},"citationCountry":{"type":"string","description":"2-letter ISO country the citations are for. Required for citation packages.","example":"US"},"fastDelivery":{"type":"boolean","default":false,"description":"1-day delivery where sold (see fastDeliveryUsd on the package)."},"addons":{"type":"array","items":{"type":"string"},"description":"Extra ids from GET /packages/, e.g. [\"add-100\"]. One of each at most."},"quantity":{"type":"integer","minimum":1,"maximum":500,"default":1,"description":"Locations for a multi-location business. Usually omitted."},"business":{"type":"object","required":["businessName"],"description":"businessName plus website or gbp are required; the rest can be added later on the order page.","properties":{"businessName":{"type":"string"},"phone":{"type":"string"},"address":{"type":"string"},"zip":{"type":"string"},"website":{"type":"string"},"gbp":{"type":"string"},"category":{"type":"string"},"email":{"type":"string"},"hours":{"type":"string"},"since":{"type":"string"},"payments":{"type":"string"},"keywords":{"type":"string"},"description":{"type":"string"},"socials":{"type":"string"},"assets":{"type":"string"}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"PlacedOrder":{"type":"object","properties":{"orderNumber":{"type":"string","example":"LCP-2026-0052"},"status":{"type":"string","example":"paid"},"statusLabel":{"type":"string"},"totalCents":{"type":"integer"},"currency":{"type":"string"},"dueDate":{"type":"string","format":"date"},"orderPageUrl":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri"}}}}},"paths":{"/me/":{"get":{"operationId":"getMe","summary":"Agency name, balance and discount","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"agency":{"name":"Local Map Booster","email":"admin@localmapbooster.com","status":"approved"},"balanceCents":52500,"balanceUsd":525,"currency":"usd","discountPercent":0,"key":{"prefix":"lcp_live_Ab3dEf","label":"Claude"}}}}},"401":{"description":"Bad key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/packages/":{"get":{"operationId":"listPackages","summary":"Orderable packages, priced after discount, plus country capacity","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"discountPercent":0,"currency":"usd","families":[{"key":"citation","title":"Citation building","packages":[{"code":"CITE-02","name":"Growth","tag":"50 citation sites","description":"50 local directories — your choice or mine.","listPriceUsd":25,"priceUsd":25,"deliveryDays":3,"fastDeliveryUsd":10,"citationSites":50,"requiresCitationCountry":true,"extras":[{"id":"add-100","name":"Add 100 more sites","description":"…","listPriceUsd":35,"priceUsd":35,"extraDays":5,"citations":100}]}]}],"citationCountries":[{"code":"US","name":"United States","maxListingsPerBusiness":1000},{"code":"IE","name":"Ireland","maxListingsPerBusiness":100}]}}}},"401":{"description":"Bad key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/quote/":{"post":{"operationId":"quoteOrder","summary":"Price and check an order without charging","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRequest"},"example":{"planCode":"CITE-02","citationCountry":"US","fastDelivery":false,"addons":[],"business":{"businessName":"Summit Plumbing Co.","phone":"+1 (555) 012-3456","address":"123 Main St, Austin, TX","zip":"78701","website":"https://summitplumbing.com","gbp":"https://maps.app.goo.gl/example","category":"Plumber","email":"hello@summitplumbing.com","hours":"Mon–Fri 9am–6pm","description":"Family-run plumbing company serving Austin since 2014."}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"quote":{"package":{"code":"CITE-02","name":"Growth","tag":"50 citation sites"},"quantity":1,"extras":[],"fastDelivery":false,"citationCountry":"US","listCents":2500,"discountCents":0,"totalCents":2500,"currency":"usd","deliveryDays":3,"balanceCents":52500,"canAfford":true}}}}},"400":{"description":"invalid_order","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"401":{"description":"Bad key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/orders/":{"get":{"operationId":"listOrders","summary":"List orders","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["active","paid","in_progress","submitted","delivered","cancelled","refunded"]}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Created on or after"},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":500}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"order":{"orderNumber":"LCP-2026-0052","status":"paid","statusLabel":"Queued","totalCents":2500,"currency":"usd","dueDate":"2026-09-24","orderPageUrl":"https://localcitationpro.com/order/<token>/","url":"https://localcitationpro.com/api/v1/orders/LCP-2026-0052/"},"balanceCents":50000}}}},"401":{"description":"Bad key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"post":{"operationId":"placeOrder","summary":"Place one order (charges credit)","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Any unique string (UUID recommended). A retry with the same key and body returns the first answer instead of placing again. Remembered 24 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRequest"},"example":{"planCode":"CITE-02","citationCountry":"US","fastDelivery":false,"addons":[],"business":{"businessName":"Summit Plumbing Co.","phone":"+1 (555) 012-3456","address":"123 Main St, Austin, TX","zip":"78701","website":"https://summitplumbing.com","gbp":"https://maps.app.goo.gl/example","category":"Plumber","email":"hello@summitplumbing.com","hours":"Mon–Fri 9am–6pm","description":"Family-run plumbing company serving Austin since 2014."}}}}},"responses":{"201":{"description":"Placed","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/PlacedOrder"},"balanceCents":{"type":"integer"}}},"example":{"order":{"orderNumber":"LCP-2026-0052","status":"paid","statusLabel":"Queued","totalCents":2500,"currency":"usd","dueDate":"2026-09-24","orderPageUrl":"https://localcitationpro.com/order/<token>/","url":"https://localcitationpro.com/api/v1/orders/LCP-2026-0052/"},"balanceCents":50000}}}},"400":{"description":"invalid_order or insufficient_credit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"401":{"description":"Bad key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"409":{"description":"request_in_progress — retry shortly","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"422":{"description":"idempotency_mismatch","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/orders/bulk/":{"post":{"operationId":"placeBulkOrders","summary":"Place up to 500 orders in one call (charges credit)","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Any unique string (UUID recommended). A retry with the same key and body returns the first answer instead of placing again. Remembered 24 hours."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orders"],"properties":{"orders":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/OrderRequest"}}}},"example":{"orders":[{"planCode":"CITE-02","citationCountry":"US","fastDelivery":false,"addons":[],"business":{"businessName":"Summit Plumbing Co.","phone":"+1 (555) 012-3456","address":"123 Main St, Austin, TX","zip":"78701","website":"https://summitplumbing.com","gbp":"https://maps.app.goo.gl/example","category":"Plumber","email":"hello@summitplumbing.com","hours":"Mon–Fri 9am–6pm","description":"Family-run plumbing company serving Austin since 2014."}},{"planCode":"CITE-02","citationCountry":"US","fastDelivery":false,"addons":[],"business":{"businessName":"Riverside Dental","website":"https://riversidedental.com","address":"9 Oak Ave, Denver, CO","phone":"+1 (555) 987-6543"}}]}}}},"responses":{"201":{"description":"All placed","content":{"application/json":{"schema":{"type":"object"},"example":{"ok":true,"placed":[{"orderNumber":"LCP-2026-0053","status":"paid","statusLabel":"Queued","totalCents":2500,"currency":"usd","dueDate":"2026-09-24","orderPageUrl":"https://localcitationpro.com/order/<token>/","url":"https://localcitationpro.com/api/v1/orders/LCP-2026-0053/"},{"orderNumber":"LCP-2026-0054","status":"paid","statusLabel":"Queued","totalCents":2500,"currency":"usd","dueDate":"2026-09-24","orderPageUrl":"https://localcitationpro.com/order/<token>/","url":"https://localcitationpro.com/api/v1/orders/LCP-2026-0054/"}],"placedCount":2,"totalCents":5000,"balanceCents":45000}}}},"207":{"description":"Stopped part-way: `placed` lists what was created, `stoppedAt` says which failed and why","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_order (with index)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"401":{"description":"Bad key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"402":{"description":"insufficient_credit — nothing placed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/orders/{orderNumber}/":{"get":{"operationId":"getOrder","summary":"One order: details, timeline, report and files","parameters":[{"name":"orderNumber","in":"path","required":true,"schema":{"type":"string","example":"LCP-2026-0052"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"order":{"orderNumber":"LCP-2026-0052","status":"delivered","statusLabel":"Delivered","package":{"code":"CITE-02","name":"Growth","tag":"50 citation sites"},"quantity":1,"extras":[],"business":{"businessName":"Summit Plumbing Co.","website":"https://summitplumbing.com","citationCountry":"US"},"selectedSites":[],"timeline":[{"at":"2026-09-21T10:15:00Z","kind":"payment","label":"Paid from agency credit","detail":"Thank you — your order is queued and we'll begin shortly."},{"at":"2026-09-23T16:02:00Z","kind":"status","label":"Delivered","detail":null}],"report":{"viewUrl":"https://localcitationpro.com/order/<token>/report/","pdfUrl":"https://localcitationpro.com/order/<token>/report/?print=1","excel":{"name":"Summit Plumbing Co. — citations.xlsx","href":"https://drive.google.com/uc?export=download&id=…"},"files":[{"id":"…","title":"Screenshots.zip","kind":"file","sizeBytes":1048576,"downloadUrl":"https://localcitationpro.com/api/report-files/<id>/?token=…"}]}}}}}},"401":{"description":"Bad key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/ledger/":{"get":{"operationId":"getLedger","summary":"Credit history","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"balanceCents":50000,"currency":"usd","entries":[{"id":"…","kind":"order_charge","label":"Order","amountCents":-2500,"orderNumber":"LCP-2026-0052","note":"LCP-2026-0052","createdAt":"2026-09-21T10:15:00Z"},{"id":"…","kind":"topup","label":"Credit added","amountCents":52500,"orderNumber":null,"note":"Card top-up","createdAt":"2026-09-20T09:00:00Z"}]}}}},"401":{"description":"Bad key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/webhook/":{"get":{"operationId":"getWebhook","summary":"Current webhook URL and last delivery result","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Bad key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"put":{"operationId":"setWebhook","summary":"Set or replace the webhook URL (https only); returns the signing secret once","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}},"example":{"url":"https://example.com/hooks/localcitationpro"}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object"},"example":{"webhook":{"agency_id":"…","url":"https://example.com/hooks/localcitationpro","active":true,"last_attempt_at":null,"last_status":null,"last_error":null,"created_at":"2026-09-21T18:00:00Z"},"secret":"whsec_…","note":"Store the secret now; it is not shown again."}}}},"400":{"description":"invalid_url","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"401":{"description":"Bad key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"delete":{"operationId":"removeWebhook","summary":"Remove the webhook","responses":{"200":{"description":"OK"},"401":{"description":"Bad key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"post":{"operationId":"testWebhook","summary":"Send a test event to the webhook now","responses":{"200":{"description":"Result of the attempt","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"no_webhook","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"401":{"description":"Bad key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}}}}