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
- Create the client with
POST /clients(business name and website). Save the returned client ID. - Look up the codes the order needs: a category ID from
GET /citations/categories?q=…, and a country and region code fromGET /citations/countries. - Open checkout with
POST /citations/{clientId}/checkout. Send your customer to the returnedurl. You can pass your ownsuccess_urlso they return to your site after paying. - Submit the paid order with
POST /citations/{clientId}/submitonce payment is complete. It is safe to retry and never charges twice. - Track progress with
GET /citationsorGET /citations/{clientId}. Statuses refresh automatically every day.POST /citations/{clientId}/refreshfetches them on demand. Initial directory syncing commonly takes 24–72 hours; some directories take longer.
3. Endpoints
| Method | Endpoint | Permission | Purpose |
|---|---|---|---|
| POST | /clients | campaigns:write | Create a client profile (send an Idempotency-Key header) |
| GET | /citations/categories?q= | citations:read | Search business categories; use id as sub_category_id |
| GET | /citations/countries | citations:read | Supported countries with region (state/province) codes |
| GET | /citations/directories?country= | citations:read | The directory network, optionally for one country |
| POST | /citations/{clientId}/checkout | citations:write | Create or resume the hosted checkout for one client |
| POST | /citations/{clientId}/submit | citations:write | Submit a paid order; returns the client report |
| POST | /citations/{clientId}/refresh | citations:write | Refresh directory statuses, live URLs and indexing now |
| GET | /citations | citations:read | All client reports; client_id, limit (max 100), offset |
| GET | /citations/{clientId} | citations:read | One client’s citation report |
| GET | /indexing | citations:read | Monthly indexing allowance and credit balance |
| POST | /indexing/top-up | citations:write | Checkout 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
| Status | Meaning |
|---|---|
| 400 | A field is missing or invalid. The error text says which one. |
| 401 / 403 | The key is missing, revoked, or lacks the required permission. |
| 404 | The client is not in your workspace, or has no citation order yet. |
| 409 | Conflict: payment not yet confirmed, an order already in progress, or an Idempotency-Key reused with different input. |
| 429 | Rate limit reached. Wait for Retry-After seconds. |
| 5xx | Temporary 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.