Connections Endpoint

Ця сторінка також доступна українською.

Overview

The new Connections endpoint provides a single API call to retrieve all of a user’s connected services — Google Ads accounts and Google Business Profile (GBP) locations — grouped by company. Before: the frontend had to call separate endpoints for Google Ads customers and GBP locations, often repeating requests per company (N+1 problem). After: one GET /api/v1/companies/me/connections call returns everything.

Endpoints

Endpoint	Returns	Use case
`GET /api/v1/companies/me/connections`	`list[CompanyWithConnections]`	Dashboard / sidebar — fetch all connections across all companies at once
`GET /api/v1/companies/me/{company_id}/connections`	`CompanyWithConnections`	Company detail page — fetch connections for a specific company

Both require a valid Authorization: Bearer <token> header.

Response format

Both endpoints return the same shape — a company object with two connection arrays. The “all connections” endpoint wraps it in a list.

`CompanyWithConnections`

integer

required

The company ID.

string

required

The company name.

string (ISO 8601)

required

When the company was created.

string (ISO 8601)

required

When the company was last updated.

GoogleAdsCustomer[]

required

Connected Google Ads accounts. Empty array if none.

Show GoogleAdsCustomer fields

integer

required

Customer ID.

string

required

Human-readable account name.

string

required

E.g. "USD", "UAH".

string

required

E.g. "America/New_York".

string

required

E.g. "ENABLED".

boolean

required

Whether this is a manager (MCC) account.

string (ISO 8601)

required

When linked.

string (ISO 8601)

required

Last update.

boolean

Always true in this response.

boolean

Always false in this response.

GoogleBusinessLocation[]

required

Connected GBP locations. Empty array if none.

Show GoogleBusinessLocation fields

string

required

Google identifier for this location.

string

required

Location name (e.g. business name).

string | null

External identifier for the location.

string | null

Link to the location on Google Maps.

object | null

Physical address of the storefront.

Show Address fields

string | null

CLDR region code (e.g. "UA", "US").

string | null

BCP-47 language code.

string | null

Postal code.

string | null

State / province / oblast.

string | null

City / town.

string | null

Neighborhood / district.

string[]

Street-level address lines.

Example request and response

curl -X GET "https://api.cattix.com/api/v1/companies/me/connections" \
  -H "Authorization: Bearer YOUR_TOKEN"

import httpx

response = httpx.get(
    "https://api.cattix.com/api/v1/companies/me/connections",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
)
data = response.json()

Response (200 OK):

[
  {
    "id": 1,
    "name": "My Agency",
    "date_added": "2025-06-15T10:30:00",
    "date_updated": "2025-12-01T14:22:00",
    "google_ads_customers": [
      {
        "id": 1234567890,
        "descriptive_name": "Client Store",
        "currency_code": "USD",
        "time_zone": "America/New_York",
        "status": "ENABLED",
        "manager": false,
        "date_added": "2025-07-01T09:00:00",
        "date_updated": "2025-11-20T08:15:00",
        "is_active": true,
        "is_deleted": false
      }
    ],
    "google_business_locations": [
      {
        "id": "locations/abc123",
        "title": "Client Store — Downtown",
        "store_code": "STORE-001",
        "maps_uri": "https://maps.google.com/?cid=123456",
        "storefront_address": {
          "region_code": "US",
          "language_code": "en",
          "postal_code": "10001",
          "administrative_area": "NY",
          "locality": "New York",
          "sublocality": null,
          "address_lines": ["123 Main St"]
        }
      }
    ]
  },
  {
    "id": 2,
    "name": "Side Project",
    "date_added": "2025-09-10T12:00:00",
    "date_updated": "2025-09-10T12:00:00",
    "google_ads_customers": [],
    "google_business_locations": []
  }
]

Companies with no connections still appear in the response — their google_ads_customers and google_business_locations arrays are empty. This lets you show “No connections yet” UI without extra logic.

Single-company endpoint

To fetch connections for a specific company, use the company ID in the path:

curl -X GET "https://api.cattix.com/api/v1/companies/me/42/connections" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns a single object (not an array):

{
  "id": 42,
  "name": "My Agency",
  "date_added": "2025-06-15T10:30:00",
  "date_updated": "2025-12-01T14:22:00",
  "google_ads_customers": [ ... ],
  "google_business_locations": [ ... ]
}

What gets filtered out

The backend automatically excludes inactive or deleted resources. You do not need to filter on the frontend side. The following are excluded:

Excluded when…	Example
Company is soft-deleted	Company was removed by admin
User membership is inactive	User was removed from a company
Connection link is inactive	Google Ads account was unlinked
Resource itself is inactive / deleted	Google Ads account was suspended

Caching

Responses are cached on the backend (Redis). You do not need to implement any caching logic on the frontend. The cache is automatically invalidated when:

A company is created, updated, or deleted
A member is added to or removed from a company
A Google Ads account or GBP location is linked / unlinked

This means calling the endpoint after any mutation will return fresh data.

Migration guide

If you are currently fetching Google Ads customers and GBP locations from separate endpoints:

Replace multiple calls with one

Replace individual calls to Google Ads and GBP endpoints with a single call to GET /api/v1/companies/me/connections.

Update your data model

The response groups connections under each company. Map your UI state accordingly:

interface CompanyWithConnections {
  id: number;
  name: string;
  date_added: string;
  date_updated: string;
  google_ads_customers: GoogleAdsCustomer[];
  google_business_locations: GoogleBusinessLocation[];
}

// The "all connections" endpoint returns:
type AllConnections = CompanyWithConnections[];

Remove client-side filtering

The backend already filters out inactive / deleted resources. Remove any frontend is_active / is_deleted checks.

Remove client-side caching (optional)

If you had client-side caching for connection data, it can be simplified or removed since the backend now caches the response.

Getting started

Customization

Writing content

AI tools

Google Ads

Companies

Campaigns

Overview

Endpoints

Response format

`CompanyWithConnections`

Example request and response

Single-company endpoint

What gets filtered out

Caching

Migration guide

​Overview

​Endpoints

​Response format

​CompanyWithConnections

​Example request and response

​Single-company endpoint

​What gets filtered out

​Caching

​Migration guide

Overview

Endpoints

Response format

`CompanyWithConnections`

Example request and response

Single-company endpoint

What gets filtered out

Caching

Migration guide