Synup Connected Accounts API

openapi: 3.2.0
info:
  title: Synup Connected Accounts API
  version: '4'
  description: 'REST API v4 for the Synup local marketing platform: business locations, listing syndication to 80+ directories, review/interaction aggregation and response, review campaigns, local rank tracking and grid-rank heatmaps, local and social posts, AI post ideas, menus, connected accounts, users and profile analytics.


    ASSEMBLED BY API EVANGELIST from the per-endpoint OpenAPI documents Synup publishes on its own documentation host (developer.synup.com, Apidog project 797384). Every operation, parameter, response, example and schema below is verbatim provider content; only the merge into a single document is ours. Source index: https://developer.synup.com/llms.txt'
  contact:
    name: Synup Developer Documentation
    url: https://developer.synup.com/
  x-assembled-by: api-evangelist enrichment pipeline (local-v1)
  x-assembled-from: 506 per-endpoint OpenAPI fragments published at https://developer.synup.com/<slug>.md
  x-assembled-date: '2026-08-13'
servers:
- url: https://api.synup.com/api/v4
  description: Base ENV (as published in every Synup doc fragment). Tenant workspace domains (https://<workspace>.synup.com/api/v4) also serve the same API.
tags:
- name: Connected Accounts
paths:
  /connected-accounts/apple-confirmed-matches:
    get:
      summary: Apple confirmed matches
      deprecated: false
      description: '<span style="font-size: 14px;">

        Returns the confirmed matches between Synup locations and Apple Business listings for a connected Apple account. These are produced after a location has been connected via the Apple Business Connect OAuth flow (see Connect link for Apple). Results are paginated.

        </span>'
      operationId: appleConfirmedMatches
      tags:
      - Connected Accounts
      parameters:
      - name: accountId
        in: query
        description: Account ID.
        required: true
        example: QWNjb3VudDoxMjM=
        schema:
          type: string
      - name: connectedAccountId
        in: query
        description: ID of the connected Apple account.
        required: true
        example: Q29ubmVjdGVkQWNjb3VudDo0NTY=
        schema:
          type: string
      - name: page
        in: query
        description: Page number (1-based).
        required: true
        example: 1
        schema:
          type: integer
      - name: Synup-Version
        in: header
        description: API version date (YYYY-MM-DD).
        required: true
        example: '2026-04-17'
        schema:
          type: string
      - name: Authorization
        in: header
        description: API key for authentication.
        required: true
        example: API T9V35W3xxxxxxxxxxx
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      appleConfirmedMatches:
                        $ref: '#/components/schemas/AppleConfirmedMatches'
                    x-apidog-orders:
                    - appleConfirmedMatches
                    x-apidog-ignore-properties: []
                x-apidog-orders:
                - data
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: ''
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apidog-orders: []
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: ''
      security: []
      x-apidog-folder: Connected Accounts
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/797384/apis/api-40050924-run
  /connected-accounts/connect-apple/bulk:
    post:
      summary: Bulk connect link for Apple
      deprecated: false
      description: '<span style="font-size: 14px;">

        Generates an Apple Business Connect OAuth link that connects **multiple locations** in a single authorization flow. Unlike Connect link for Apple, no `locationId` is supplied — the set is account/platform-scoped. Redirect the user to the returned `url`; the link is valid for 1 day.


        Use `platform` to target `local` (default) or `social`, and `entityId` to supply the brand ID when `platform` is `social`.


        **Apple OAuth link variants:**

        - **Connect link for Apple** — single location (`locationId`).

        - **Bulk connect link for Apple** — multiple locations (this endpoint).

        - **Renew connect link for Apple** — re-authorize an expired/revoked token.

        </span>'
      operationId: bulkConnectLinkForApple
      tags:
      - Connected Accounts
      parameters:
      - name: Synup-Version
        in: header
        description: API version date (YYYY-MM-DD).
        required: true
        example: '2026-04-17'
        schema:
          type: string
      - name: Authorization
        in: header
        description: API key for authentication.
        required: true
        example: API T9V35W3xxxxxxxxxxx
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppleOauthBulkRequest'
            example:
              input:
                successUrl: https://app.synup.com/apple/success
                errorUrl: https://app.synup.com/apple/error
                platform: local
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      bulkConnectLinkForApple:
                        $ref: '#/components/schemas/AppleOauthBulkPayload'
                    x-apidog-orders:
                    - bulkConnectLinkForApple
                    x-apidog-ignore-properties: []
                x-apidog-orders:
                - data
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: ''
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apidog-orders: []
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: ''
      security: []
      x-apidog-folder: Connected Accounts
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/797384/apis/api-39902193-run
  /connected-accounts/confirm-matches:
    post:
      summary: Confirm Connected Account Matches
      deprecated: false
      description: '<span style="font-size: 14px;">

        This API confirms suggested matches between locations in your account and profiles from Google My Business or Facebook Pages that were previously recommended.


        **Behavior:**

        - Requires base64-encoded match record IDs in a specific format, depending on the account type.

        - Once confirmed, the system links the location with the external listing for ongoing management.

        </span>'
      tags:
      - Connected Accounts
      parameters:
      - name: Authorization
        in: header
        description: API key for authentication
        required: true
        example: API T9V35W3xxxxxxxxxxx
        schema:
          type: string
      - name: Content-Type
        in: header
        description: ''
        required: true
        example: application/json
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmMatchesRequest'
            example:
              input:
                matchRecordIds:
                - R21iTG9jYXRpb25NYXRjaGVkRGF0YTplNGZhNTFkYi04NWEwLTRjYzItYjdmMS01OWNhMzQ1NjlhZWM=
                - R21iTG9jYXRpb25NYXRjaGVkRGF0YSI6MWFjMDdiN2ItMjUyYi00NTdkLTlhM2ItMTk4NzEzYzNkZjQz
      responses:
        '200':
          description: Match confirmation process completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmMatchesResponse'
              examples:
                '1':
                  summary: All matches confirmed successfully
                  value:
                    data:
                      confirmConnectMatches:
                        success: true
                '2':
                  summary: Some matches failed to confirm
                  value:
                    data:
                      confirmConnectMatches:
                        success: false
                        failedIds:
                        - e4fa51db-85a0-4cc2-b7f1-59ca34569aec
          headers: {}
          x-apidog-name: OK
        '400':
          description: Invalid request - Malformed base64 strings or invalid format
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apidog-orders: []
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: Bad Request
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apidog-orders: []
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: Unauthorized
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apidog-orders: []
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: Forbidden
      security: []
      x-apidog-folder: Connected Accounts
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/797384/apis/api-13680753-run
  /connected-accounts/connect-listing:
    post:
      summary: Connect a location with a listing of a connected account
      deprecated: false
      description: "<span style=\"font-size: 14px;\">\n\nThis API links a location in your account with a listing from a connected Google My Business or Facebook Page account.\n\n**Required Fields:**\n- locationId – Base64-encoded unique identifier of the location.\n- connectedAccountListingId – The ID of the listing, retrieved from the Fetch Listings API.\n- connectedAccountId – The ID of the connected account managing the listing.\n    \n**Behavior:**\n- Establishes a direct connection between the location and the listing.\n- Enables the system to sync and manage the listing’s data.\n</span>"
      tags:
      - Connected Accounts
      parameters:
      - name: Authorization
        in: header
        description: API key for authentication
        required: true
        example: API T9V35W3xxxxxxxxxxx
        schema:
          type: string
      - name: Content-Type
        in: header
        description: ''
        required: true
        example: application/json
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectListingRequest'
            example:
              input:
                locationId: TG9jYXRpb246NzM5MzM=
                connectedAccountId: 3db66afa-151d-4212-a8b7-949f9fe9aaf9
                connectedAccountListingId: R21iQnVsa0RhdGFMYWtlOmMyMWRiOWY5LTZmYTctNDE0My1hNDU2LTQzMjZkMmZiN2UwZg==
      responses:
        '200':
          description: Connection process completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectListingResponse'
              examples:
                '1':
                  summary: Successful connection
                  value:
                    data:
                      connectListing:
                        message: null
                        success: true
                '2':
                  summary: Failed connection - Internal System Error
                  value:
                    data:
                      connectListing:
                        message: Internal System Error
                        success: false
                '3':
                  summary: Failed Connection
                  value:
                    data:
                      confirmConnectMatches:
                        failedIds:
                        - 76151840-2c2e-46f7-8ea1-408ee19d37a2
                        success: false
          headers: {}
          x-apidog-name: OK
        '400':
          description: Invalid request - Malformed base64 string or invalid IDs
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apidog-orders: []
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: Bad Request
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apidog-orders: []
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: Unauthorized
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apidog-orders: []
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: Forbidden
        '404':
          description: Not Found - Location or listing not found
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apidog-orders: []
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: Record Not Found
      security: []
      x-apidog-folder: Connected Accounts
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/797384/apis/api-13680763-run
  /connected-accounts/connect-facebook:
    post:
      summary: Connect Facebook Page to Account
      deprecated: false
      description: "\n<span style=\"font-size: 14px;\">\n\nThis API initiates the process of connecting a new Facebook Page account to the system. The response provides a URL for the user to complete Facebook’s OAuth authentication flow.\n\n**Important Notes:**\n- The response includes a URL that the user must visit to authenticate and connect their Facebook Page account.\n- The provided URL is valid for 24 hours.\n- When the user accesses the URL, they are redirected to Facebook’s OAuth authentication flow.\n- During OAuth, the user must:\n    - Review and accept Facebook’s terms and conditions.\n    - Grant necessary permissions for integration.\n- After OAuth authentication:\n    - If successful, the user is redirected to the successUrl specified in the request.\n    - If permissions are declined or the process fails, the user is redirected to the errorUrl.\n</span>"
      operationId: connectFacebookAccount
      tags:
      - Connected Accounts
      parameters:
      - name: Authorization
        in: header
        description: API key for authentication
        required: true
        example: API T9V35W3xxxxxxxxxxx
        schema:
          type: string
      - name: Content-Type
        in: header
        description: ''
        required: true
        example: application/json
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  type: object
                  required:
                  - errorUrl
                  - successUrl
                  properties:
                    errorUrl:
                      type: string
                      description: Redirect URL in case of Error
                      examples:
                      - http://www.errorurl.com
                    successUrl:
                      type: string
                      description: Redirect URL in case of Success
                      examples:
                      - http://www.successurl.com
                  x-apidog-orders:
                  - errorUrl
                  - successUrl
              x-apidog-orders:
              - input
            example:
              input:
                errorUrl: http://www.errorurl.com
                successUrl: http://www.successurl.com
      responses:
        '200':
          description: Successfully generated connection URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      bulkConnectLinkForFacebook:
                        type: object
                        properties:
                          errors:
                            type:
                            - array
                            - 'null'
                            items:
                              type: string
                            description: Array of error messages if any
                          success:
                            type: boolean
                            description: True if the request was successful, otherwise False
                          url:
                            type: string
                            description: The URL which needs to be visited to initiate the connect process
                            examples:
                            - http://synup.com/locations/redirect_oauth_bulk/facebook?token=9009dc92-2b18-421f-b856-d157f3f06d6b
                        x-apidog-orders:
                        - errors
                        - success
                        - url
                    x-apidog-orders:
                    - bulkConnectLinkForFacebook
                x-apidog-orders:
                - data
              example:
                data:
                  bulkConnectLinkForFacebook:
                    errors: null
                    success: true
                    url: https://claim.verifymybiz.com/locations/redirect_oauth_bulk/facebook?onboarding=false&platform=local&token=bfac8e06-8d72-4810-9c50-ae7ee12a7b52
          headers: {}
          x-apidog-name: OK
        '400':
          description: Bad request - invalid input
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apidog-orders: []
          headers: {}
          x-apidog-name: Bad Request
      security: []
      x-apidog-folder: Connected Accounts
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/797384/apis/api-13675265-run
  /connected-accounts/connect-google:
    post:
      summary: Connect Google Profile to Account
      deprecated: false
      description: "<span style=\"font-size: 14px;\">\n\nThis API initiates the process of connecting a new Google My Business (GMB) account to the system. The response provides a URL for the user to complete Google's OAuth authentication flow.\n\n**Important Notes:**\n- The response includes a URL that the user must visit to authenticate and connect their GMB account.\n- The provided URL is valid for 24 hours.\n- When the user accesses the URL, they are redirected to Google’s OAuth authentication flow.\n- During OAuth, the user must:\n    - Review and accept Google’s terms and conditions.\n    - Grant necessary permissions for integration.\n- After OAuth authentication:\n    - If successful, the user is redirected to the successUrl provided in the request.\n    - If permissions are declined or the process fails, the user is redirected to the errorUrl.\n</span>"
      operationId: connectGoogleAccount
      tags:
      - Connected Accounts
      parameters:
      - name: Authorization
        in: header
        description: API key for authentication
        required: true
        example: API T9V35W3xxxxxxxxxxx
        schema:
          type: string
      - name: Content-Type
        in: header
        description: ''
        required: true
        example: application/json
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  type: object
                  required:
                  - errorUrl
                  - successUrl
                  properties:
                    errorUrl:
                      type: string
                      description: Redirect URL in case of Error
                      examples:
                      - http://www.errorurl.com
                    successUrl:
                      type: string
                      description: Redirect URL in case of Success
                      examples:
                      - http://www.successurl.com
                  x-apidog-orders:
                  - errorUrl
                  - successUrl
              x-apidog-orders:
              - input
            example:
              input:
                errorUrl: http://www.errorurl.com
                successUrl: http://www.successurl.com
      responses:
        '200':
          description: Successfully generated connection URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      bulkConnectLinkForGoogle:
                        type: object
                        properties:
                          errors:
                            type:
                            - array
                            - 'null'
                            items:
                              type: string
                            description: Array of error messages if any
                          success:
                            type: boolean
                            description: True if the request was successful, otherwise False
                          url:
                            type: string
                            description: The URL which needs to be visited to initiate the connect process
                            examples:
                            - http://synup.com/locations/redirect_oauth_bulk/google?token=9009dc92-2b18-421f-b856-d157f3f06d6b
                        x-apidog-orders:
                        - success
                        - url
                        - errors
                    x-apidog-orders:
                    - bulkConnectLinkForGoogle
                x-apidog-orders:
                - data
              example:
                data:
                  bulkConnectLinkForGoogle:
                    clientMutationId: null
                    errors: null
                    success: true
                    url: https://claim.verifymybiz.com/locations/redirect_oauth_bulk/google_oauth2?onboarding=false&platform=local&token=47cc832a-31ce-4de5-8768-c541a8331800
          headers: {}
          x-apidog-name: OK
        '400':
          description: Bad request - invalid input
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apidog-orders: []
          headers: {}
          x-apidog-name: Bad Request
      security: []
      x-apidog-folder: Connected Accounts
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/797384/apis/api-13675039-run
  /connected-accounts/connect-apple:
    post:
      summary: Connect link for Apple
      deprecated: false
      description: '<span style="font-size: 14px;">

        Generates an Apple Business Connect OAuth link for a **single location**. Redirect the user to the returned `url` to authorize the connection; on completion Apple redirects back to your `successUrl` (or `errorUrl` on failure). The link is valid for 1 day.


        **Apple OAuth link variants:**

        - **Connect link for Apple** — connects a single location (this endpoint; takes a `locationId`).

        - **Bulk connect link for Apple** — connects multiple locations in one flow (account/platform-scoped; no `locationId`).

        - **Renew connect link for Apple** — re-authorizes an expired or revoked token for an existing connection.

        </span>'
      operationId: connectLinkForApple
      tags:
      - Connected Accounts
      parameters:
      - name: Synup-Version
        in: header
        description: API version date (YYYY-MM-DD).
        required: true
        example: '2026-04-17'
        schema:
          type: string
      - name: Authorization
        in: header
        description: API key for authentication.
        required: true
        example: API T9V35W3xxxxxxxxxxx
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppleOauthRequest'
            example:
              input:
                locationId: TG9jYXRpb246MQ==
                successUrl: https://app.synup.com/apple/success
                errorUrl: https://app.synup.com/apple/error
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      connectLinkForApple:
                        $ref: '#/components/schemas/AppleOauthPayload'
                    x-apidog-orders:
                    - connectLinkForApple
                    x--orders:
                    - connectLinkForApple
                    x--ignore-properties: []
                x-apidog-orders:
                - data
                x--orders:
                - data
                x--ignore-properties: []
          headers: {}
          x-apidog-name: ''
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apidog-orders: []
                x--orders: []
                x--ignore-properties: []
          headers: {}
          x-apidog-name: ''
      security: []
      x-apidog-folder: Connected Accounts
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/797384/apis/api-40051582-run
  /locations/create/gmb-listing:
    post:
      summary: Create GMB Listing
      deprecated: false
      description: '<span style="font-size: 14px;">

        Create a GMB listing for the location with ID TG9jYXRpb246MTQwNTU= and connect it to a Google account

        </span>

        '
      tags:
      - Connected Accounts
      parameters:
      - name: locationId
        in: query
        description: The ID of the location for which GMB listing will be created. Encoded format
        required: true
        example: TG9jYXRpb246MTQwNTU=
        schema:
          type: string
      - name: connectedAccountId
        in: query
        description: "The ID of the connected Google account to associate with the listing\t"
        required: true
        example: bc818dc7-1576-4e50-a69d-c69d12221234
        schema:
          type: string
      - name: folderId
        in: query
        description: "The Google My Business folder ID where the listing should be created. You can get this ID from the List folders endpoint. If not provided, it will create under Ungrouped (Primary Group)\t"
        required: false
        example: accounts/1154433325552997863009
        schema:
          type: string
      - name: Authorization
        in: header
        description: ''
        required: true
        example: API T9V35W3xxxxxxxxxxx
        schema:
          type: string
      - name: Content-Type
        in: header
        description: ''
        required: false
        example: application/json
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      createGmbListingForLocation:
                        type: object
                        properties:
                          success:
                            type: boolean
                          errors:
                            type: 'null'
                        required:
                        - success
                        - errors
                        x-apidog-orders:
                        - success
                        - errors
                    required:
                    - createGmbListingForLocation
                    x-apidog-orders:
                    - createGmbListingForLocation
                required:
                - data
                x-apidog-orders:
                - data
              example:
                data:
                  createGmbListingForLocation:
                    success: true
                    errors: null
          headers: {}
          x-apidog-name: Success
      security: []
      x-apidog-folder: Connected Accounts
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/797384/apis/api-19189800-run
  /connected-accounts/create-location-from-listing:
    post:
      summary: create location from connected account listing
      deprecated: false
      description: '<span style="font-size: 14px;">

        This API creates a new location in the system from an existing connected account listing (Google My Business or Facebook page) that has been previously fetched and stored in the bulk data lake.

        What This API Does:

        Takes a listing from your connected account''s bulk data (Google or Facebook)

        Fetches the latest information from the platform (Google/Facebook API)

        Creates a new location in Synup with all the business details

        Automatically links the location to the connected account

        Important Prerequisites:

        You must already have a connected account (Google or Facebook) with valid credentials

        The account must have completed the bulk listing fetch process

        The listing must be available in the bulk data lake (not yet connected to a location)

        The listing must belong to the specified connected account

        Request Parameters:

        connectedAccountId (required): UUID of your connected Google/Facebook account

        connectedAccountListingId (required): Encoded ID of the listing from bulk data (format: GmbBulkDataLake:xxx or FbBulkDataLake:xxx)

        tenure (optional): Billing tenure for the location (e.g., "Monthly", "Yearly")

        API Behavior:

        For Google My Business: Fetches latest location data including name, address, hours, categories, phone, photos, and attributes

        For Facebook: Fetches latest page data including name, location, hours, categories, description, and contact info

        Validates that credentials are still valid before proceeding

        Checks if the listing is already connected to prevent duplicates

        Creates location with proper state mapping (uses reverse geocoding for Facebook if needed)

        Response:

        On success: Returns success: true with the new location_id (database ID)

        On failure: Returns success: false with error code and message

        Common Error Codes:



# --- truncated at 32 KB (110 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/synup/refs/heads/main/openapi/synup-connected-accounts-api-openapi.yml