CloudStackly
CLOUDSTACKLY CITATION BUILDER API

Citation Builder API for agencies

Order, track and report local citations for every client from your own CRM, dashboard or client portal. Your software talks only to CloudStackly: one API key, a CloudStackly-hosted checkout, and a single report with each directory’s status and live listing URL.

Base URL
https://cloudstackly.com/api/v1
Authentication
Authorization: Bearer csk_live_…
Rate limit
120 requests per key per minute
Price
$24.99 per client location per month

1. Create an API key

Sign in to your CloudStackly workspace, open Account & Billing → Agency Integration, and create a key with the citations:read and citations:write permissions. The secret is shown once. Store it in your server’s secret manager and call the API from your backend only, never from a browser. Every key is restricted to the workspace that created it, and you can revoke it at any time.

2. How an order works

  1. Create the client with POST /clients (business name and website). Save the returned client ID.
  2. Look up the codes the order needs: a category ID from GET /citations/categories?q=…, and a country and region code from GET /citations/countries.
  3. Open checkout with POST /citations/{clientId}/checkout. Send your customer to the returned url. You can pass your own success_url so they return to your site after paying.
  4. Submit the paid order with POST /citations/{clientId}/submit once payment is complete. It is safe to retry and never charges twice.
  5. Track progress with GET /citations or GET /citations/{clientId}. Statuses refresh automatically every day. POST /citations/{clientId}/refresh fetches them on demand. Initial directory syncing commonly takes 24–72 hours; some directories take longer.

3. Endpoints

MethodEndpointPermissionPurpose
POST/clientscampaigns:writeCreate a client profile (send an Idempotency-Key header)
GET/citations/categories?q=citations:readSearch business categories; use id as sub_category_id
GET/citations/countriescitations:readSupported countries with region (state/province) codes
GET/citations/directories?country=citations:readThe directory network, optionally for one country
POST/citations/{clientId}/checkoutcitations:writeCreate or resume the hosted checkout for one client
POST/citations/{clientId}/submitcitations:writeSubmit a paid order; returns the client report
POST/citations/{clientId}/refreshcitations:writeRefresh directory statuses, live URLs and indexing now
GET/citationscitations:readAll client reports; client_id, limit (max 100), offset
GET/citations/{clientId}citations:readOne client’s citation report
GET/indexingcitations:readMonthly indexing allowance and credit balance
POST/indexing/top-upcitations:writeCheckout for 100 indexing credits ($10)

The machine-readable OpenAPI 3.1 description is at /api/v1/openapi. You can import it into Postman, Insomnia or a code generator.

4. Examples

Create the client

curl -X POST https://cloudstackly.com/api/v1/clients \
  -H "Authorization: Bearer $CLOUDSTACKLY_API_KEY" \
  -H "Idempotency-Key: crm-client-000123" \
  -H "Content-Type: application/json" \
  -d '{"business_name":"Example Locksmith","website":"https://example.com","phone":"+15125550100","city":"Austin","region":"TX","country":"US"}'

Find the category and region codes

curl "https://cloudstackly.com/api/v1/citations/categories?q=locksmith" \
  -H "Authorization: Bearer $CLOUDSTACKLY_API_KEY"

{ "query": "locksmith", "count": 1,
  "data": [ { "id": 123, "name": "Locksmith", "group": "Home Services" } ] }

Open the hosted checkout

curl -X POST "https://cloudstackly.com/api/v1/citations/CLIENT_ID/checkout" \
  -H "Authorization: Bearer $CLOUDSTACKLY_API_KEY" \
  -H "Idempotency-Key: crm-order-000123" \
  -H "Content-Type: application/json" \
  -d '{
    "billing_email": "billing@youragency.com",
    "success_url": "https://youragency.com/citations/paid?session={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://youragency.com/citations/cancelled",
    "payload": {
      "description": "A factual description of the business, its services and its service area, between 200 and 750 characters…",
      "sub_category_id": 123,
      "street": "10 Main Street",
      "city": "Austin",
      "state_iso": "TX",
      "postal_code": "78701",
      "country_iso": "US",
      "phone": "+15125550100",
      "website": "https://example.com"
    }
  }'

{ "url": "https://checkout.stripe.com/c/pay/cs_live_…", "session_id": "cs_live_…" }

Repeating the call with the same Idempotency-Key returns the same open checkout. Set hide_address to true for a service-area business that doesn’t show its street address.

Submit after payment

curl -X POST "https://cloudstackly.com/api/v1/citations/CLIENT_ID/submit" \
  -H "Authorization: Bearer $CLOUDSTACKLY_API_KEY"

{ "client_id": "…", "payment_confirmed": true,
  "message": "Payment is confirmed and the citation order has been submitted.",
  "timeline": "Initial directory syncing commonly takes 24–72 hours; some publishers take longer. …",
  "report": { … } }

If the response contains submission_needs_attention: true, the payment is safe. Read error, correct the business details, and call submit again. Don’t open a second checkout.

5. The citation report

GET /citations/{clientId}, submit and refresh all return the same report format:

{
  "client_id": "8c1f…",
  "business_name": "Example Locksmith",
  "location": "Austin, TX, US",
  "order_status": "completed",
  "payment": { "status": "completed", "amount_cents": 2499, "updated_at": "2026-11-08T10:02:11Z" },
  "citation": {
    "status": "submitted",
    "last_synced_at": "2026-11-09T06:00:04Z",
    "directory_count": 2,
    "live_count": 1,
    "directories": [
      { "name": "Google Maps", "status": "Live", "live_url": "https://maps.google.com/?cid=…",
        "issue": null, "tier": "premium", "updated_at": "2026-11-09T05:58:40Z" },
      { "name": "Yelp", "status": "Action required", "live_url": null,
        "issue": "Phone number could not be verified.", "tier": "additional", "updated_at": "2026-11-09T05:58:40Z" }
    ],
    "indexed_url_count": 0,
    "indexing": [ { "url": "https://maps.google.com/?cid=…", "status": "submitted", "checked_at": null } ]
  },
  "attention": null
}

Use live_url as proof of a live listing and issue to show your client what needs fixing. Directory names and counts depend on the client’s country and category. The example values above are illustrative.

6. Errors, limits and retries

StatusMeaning
400A field is missing or invalid. The error text says which one.
401 / 403The key is missing, revoked, or lacks the required permission.
404The client is not in your workspace, or has no citation order yet.
409Conflict: payment not yet confirmed, an order already in progress, or an Idempotency-Key reused with different input.
429Rate limit reached. Wait for Retry-After seconds.
5xxTemporary problem. Retry with backoff; submit and refresh are safe to repeat.

Every error body has the same shape: { "error": "…" }. Successful responses include X-RateLimit-Limit and X-RateLimit-Remaining headers.

7. Billing and indexing

Citation management ordered through the API is a monthly subscription of $24.99 per client location until cancelled, paid through the CloudStackly-hosted checkout. Eligible live listing URLs are submitted for indexing automatically using the workspace’s indexing allowance. GET /indexing shows the balance, and POST /indexing/top-up opens a $10 checkout for 100 more credits. CloudStackly reports listing and submission status. It doesn’t guarantee search-engine indexing or rankings.

Need a hand?

Your workspace also has an MCP endpoint at https://cloudstackly.com/api/mcp for AI agents. Send the same API key as a Bearer token. Its citation tools follow the same steps as above: cloudstackly_citation_categories, cloudstackly_create_citation_order (returns the checkout link a person pays; the tool never charges by itself), cloudstackly_submit_citation_order, cloudstackly_get_citation_report and cloudstackly_refresh_citations, plus country and directory lookups. The same key can also create AWS and Cloud Link campaigns. Keys created before citation access was added need a new key with the citation permissions. Questions about an integration? Contact the CloudStackly team.

Create your workspace and API key ↗

Chat on WhatsApp