# Get Location where app is installed GET https://services.leadconnectorhq.com/oauth/installed-locations This API allows you fetch location where app is installed upon ## Authentication Send `Authorization: Bearer ` using: - **Agency token: OAuth access token only (Private Integration Tokens are not accepted).** Scopes: `oauth.readonly` ## Parameters ### Header Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Version` | string | Yes | API Version | ### Query Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `pageSize` | number | No | Max items per page (1-100). Replaces legacy `limit` parameter per AIP-158. | | `pageToken` | string | No | Opaque token returned in a previous response to fetch the next page. Replaces legacy `skip` parameter per AIP-158. | | `query` | string | No | Literal installed-location name search. Leading and trailing whitespace is ignored. | | `isInstalled` | boolean | No | Filters out location which are installed for specified app under the specified company | | `restrictToUserLocations` | boolean | No | When true, restricts the list to locations the current user has access to (for restricted agency admins and account admins). When false or omitted, no user-based filter is applied for installed list; for backward compatibility, install list (isInstalled=false) is still filtered by user when this param is omitted. | | `companyId` | string | Yes | Parameter to search by the companyId | | `appId` | string | Yes | Parameter to search by the appId | | `versionId` | string | No | VersionId of the app | | `onTrial` | boolean | No | Filters out locations which are installed for specified app in trial mode | | `planId` | string | No | Filters out location which are installed for specified app under the specified planId | | `locationId` | string | No | locationId | ## OpenAPI Specification ```json { "openapi": "3.0.0", "info": { "title": "LeadConnector API", "version": "v3" }, "servers": [ { "url": "https://services.leadconnectorhq.com" } ], "paths": { "/oauth/installed-locations": { "get": { "summary": "Get Location where app is installed", "operationId": "getLocationWhereAppIsInstalled", "description": "This API allows you fetch location where app is installed upon", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Max items per page (1-100). Replaces legacy `limit` parameter per AIP-158.", "schema": { "default": 20, "example": 20, "type": "number" } }, { "name": "pageToken", "required": false, "in": "query", "description": "Opaque token returned in a previous response to fetch the next page. Replaces legacy `skip` parameter per AIP-158.", "schema": { "example": "eyJza2lwIjoyMH0", "type": "string" } }, { "name": "query", "required": false, "in": "query", "description": "Literal installed-location name search. Leading and trailing whitespace is ignored.", "schema": { "maxLength": 100, "example": "location name", "type": "string" } }, { "name": "isInstalled", "required": false, "in": "query", "description": "Filters out location which are installed for specified app under the specified company", "schema": { "example": true, "type": "boolean" } }, { "name": "restrictToUserLocations", "required": false, "in": "query", "description": "When true, restricts the list to locations the current user has access to (for restricted agency admins and account admins). When false or omitted, no user-based filter is applied for installed list; for backward compatibility, install list (isInstalled=false) is still filtered by user when this param is omitted.", "schema": { "example": true, "type": "boolean" } }, { "name": "companyId", "required": true, "in": "query", "description": "Parameter to search by the companyId", "schema": { "example": "tDtDnQdgm2LXpyiqYvZ6", "type": "string" } }, { "name": "appId", "required": true, "in": "query", "description": "Parameter to search by the appId", "schema": { "example": "tDtDnQdgm2LXpyiqYvZ6", "type": "string" } }, { "name": "versionId", "required": false, "in": "query", "description": "VersionId of the app", "schema": { "example": "tDtDnQdgm2LXpyiqYvZ6", "type": "string" } }, { "name": "onTrial", "required": false, "in": "query", "description": "Filters out locations which are installed for specified app in trial mode", "schema": { "example": true, "type": "boolean" } }, { "name": "planId", "required": false, "in": "query", "description": "Filters out location which are installed for specified app under the specified planId", "schema": { "example": true, "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "description": "locationId", "schema": { "example": "1245", "type": "string" } }, { "name": "Version", "in": "header", "description": "API Version", "required": true, "schema": { "type": "string", "enum": [ "v3" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInstalledLocationsV3SuccessfulResponseDto" } } } }, "400": { "description": "Invalid argument (AIP error envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AipErrorResponseDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedDTO" } } } }, "404": { "description": "App not found (AIP error envelope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AipErrorResponseDto" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableDTO" } } } } }, "security": [ { "Agency-Access-Only": [ "oauth.readonly" ] } ] } } }, "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access-Only": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account.", "type": "http" }, "Agency-Access": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.", "type": "http" }, "Agency-Access-Only": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Agency.", "type": "http" } }, "schemas": { "GetInstalledLocationsV3SuccessfulResponseDto": { "type": "object", "properties": { "items": { "description": "List of locations with their installation status for the requested app", "example": [ { "_id": "0IHuJvc2ofPAAA8GzTRi", "name": "John Deo", "address": "47 W 13th St, New York, NY 10011, USA", "isInstalled": true } ], "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "example": "0IHuJvc2ofPAAA8GzTRi", "description": "Location ID" }, "name": { "type": "string", "example": "John Deo", "description": "Name of the location" }, "address": { "type": "string", "example": "47 W 13th St, New York, NY 10011, USA", "description": "Address linked to location" }, "isInstalled": { "type": "boolean", "example": true, "description": "Check if the requested app is installed for following location" }, "versionId": { "type": "string", "example": "6578278e879ad2646715ba9c", "description": "Version ID of the installed app version for this location" }, "installedAt": { "format": "date-time", "type": "string", "example": "2024-01-15T10:30:00.000Z", "description": "Timestamp when the app was installed on this location" } }, "required": [ "_id", "name", "address" ], "title": "InstalledLocationSchema" } }, "pagination": { "description": "Pagination metadata (AIP-158)", "allOf": [ { "type": "object", "properties": { "totalRecords": { "type": "number", "example": 1231, "description": "Total number of records matching the query across all pages" }, "hasNextPage": { "type": "boolean", "example": true, "description": "True when a next page is available" }, "hasPrevPage": { "type": "boolean", "example": false, "description": "True when a previous page is available" }, "nextPageToken": { "type": "string", "example": "eyJvZmZzZXQiOjIwfQ", "description": "Opaque token to fetch the next page" }, "prevPageToken": { "type": "string", "example": "eyJvZmZzZXQiOjB9", "description": "Opaque token to fetch the previous page" }, "currentPageSize": { "type": "number", "example": 20, "description": "Number of items returned in the current page" }, "estimatedTotalRecords": { "type": "number", "example": 1231, "description": "Estimated total records; present when exact total is unknown" } }, "required": [ "hasNextPage", "hasPrevPage", "currentPageSize" ], "title": "V3PaginationMetaDto" } ] }, "metadata": { "description": "Query metadata (filters and sort applied)", "allOf": [ { "type": "object", "properties": { "filterApplied": { "type": "object", "additionalProperties": true, "example": { "companyId": "tDtDnQdgm2LXpyiqYvZ6", "isInstalled": true }, "description": "Filters that were applied to the query" }, "sortApplied": { "type": "object", "additionalProperties": true, "example": { "installedAt": "desc" }, "description": "Sort order that was applied to the query" } }, "title": "V3InstalledLocationsListMetadataDto" } ] }, "installToFutureLocations": { "type": "boolean", "description": "Boolean to control if user wants app to be automatically installed to future locations", "example": true } }, "required": [ "items", "pagination" ], "title": "GetInstalledLocationsV3SuccessfulResponseDto" }, "AipErrorResponseDto": { "type": "object", "properties": { "error": { "description": "AIP-compliant error envelope", "allOf": [ { "type": "object", "properties": { "code": { "type": "string", "example": "RESOURCE_NOT_FOUND", "description": "Machine-readable error code (see AipErrorCode enum in @platform-core/aip-framework)" }, "message": { "type": "string", "example": "The requested App 'abc' was not found.", "description": "Human-readable error message" }, "details": { "type": "object", "additionalProperties": true, "example": { "resource": "App", "identifier": "abc" }, "description": "Additional error context (field name, identifier, etc.)" }, "resolution": { "type": "string", "example": "Verify the App exists and you have permission to access it.", "description": "Suggested resolution for the caller" } }, "required": [ "code", "message" ], "title": "AipErrorBodyDto" } ] } }, "required": [ "error" ], "title": "AipErrorResponseDto" }, "UnauthorizedDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 401 }, "message": { "type": "string", "example": "Invalid token: access token is invalid" }, "error": { "type": "string", "example": "Unauthorized" } }, "title": "UnauthorizedDTO" }, "UnprocessableDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 422 }, "message": { "example": [ "Unprocessable Entity" ], "type": "array", "items": { "type": "string" } }, "error": { "type": "string", "example": "Unprocessable Entity" } }, "title": "UnprocessableDTO" } } } } ``` ## Code Examples **cURL** ```bash curl -L -X GET 'https://services.leadconnectorhq.com/oauth/installed-locations?companyId=&appId=' \ -H 'Authorization: Bearer ' \ -H 'Version: v3' ``` **Node.js** ```javascript const options = { method: 'GET', headers: { Authorization: 'Bearer ', Version: 'v3' } }; try { const response = await fetch('https://services.leadconnectorhq.com/oauth/installed-locations?companyId=&appId=', options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **Python** ```python import requests url = "https://services.leadconnectorhq.com/oauth/installed-locations" headers = { "Authorization": "Bearer ", "Version": "v3" } params = { "companyId": "", "appId": "" } response = requests.get(url, params=params, headers=headers) print(response.json()) ``` **PHP** ```php 'https://services.leadconnectorhq.com/oauth/installed-locations?companyId=&appId=', CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ', 'Version: v3', ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` **Java** ```java HttpResponse response = Unirest .get("https://services.leadconnectorhq.com/oauth/installed-locations?companyId=&appId=") .header("Authorization", "Bearer ") .header("Version", "v3") .asString(); ``` **Go** ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://services.leadconnectorhq.com/oauth/installed-locations?companyId=&appId=" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Version", "v3") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(string(body)) } ``` **Ruby** ```ruby require 'uri' require 'net/http' url = URI("https://services.leadconnectorhq.com/oauth/installed-locations?companyId=&appId=") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = "Bearer " request["Version"] = "v3" response = http.request(request) puts response.read_body ``` **PowerShell** ```powershell $headers = @{ "Authorization" = "Bearer " "Version" = "v3" } $response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/oauth/installed-locations?companyId=&appId=' -Method 'GET' -Headers $headers $response | ConvertTo-Json ```