Getting started
All customer endpoints use HTTPS, accept JSON, and return JSON unless a legacy authentication failure returns plain text. Every request is scoped to an account that the authenticated user can access.
Request format
- Method: POST
- Header: Content-Type: application/json
- Account IDs and resource IDs are 24-character MongoDB ObjectIds.
- Dates use ISO 8601 where present.
Pagination
- returnPageNumber starts at 1.
- returnCountPerPage accepts 1 through 500.
- Paged responses include hasNextPage where applicable.
Authentication
Existing email/password integrations remain supported. Scoped bearer tokens are preferred for new and migrated integrations because they can be individually named, limited, monitored, and revoked.
Bearer token
Send the token in the authorization header and include accountId in the JSON body. Do not include the user's password.
Legacy credentials
Include email, password, and accountId in the JSON body. Never place credentials in a URL or query string.
Account and discovery
Read account projects, targeting profiles, and stored location records before building downstream workflows.
POST/api/v1/customer/getMyProjectsList projects visible to the authenticated user.
Request
- Required: accountId.
- Optional: searchByString, returnPageNumber, returnCountPerPage.
Returns
A page of visible projects with project identity and metadata.
POST/api/v1/customer/getMyBrandProfilesRead account targeting profiles used by territory workflows.
Request
- Required: accountId.
- Optional: activeOnly (default true), country.
Returns
Brand profile ID, title, countries, active/default state, ICP targets, avoid rules, territory preferences, automated territory-check settings, and AI notes. Territory-check settings include whether checks are enabled, minimum distance, available and pending tag titles, and maximum search distance. Internal bookkeeping fields are excluded.
POST/api/v1/customer/searchStoresSearch normalized store fields across account or project lists.
Request
Required: accountId and query. Optional: projectId, pagination, and fields containing one or more of name, address, city, or state.
Returns
Normalized, account-scoped store matches with list context and location fields.
Lists and records
Read, create, update, and remove account-owned lists and their records. Write operations require an editor role.
POST/api/v1/customer/getMyListsList all account lists or lists associated with a project.
Request
- Required: accountId.
- Optional: projectName, searchByString, and pagination.
Returns
Lists with IDs, names, descriptions, types, project associations, and aggregated item counts.
POST/api/v1/customer/getMyListRead one list and its records.
Request
Required: accountId and listId.
Returns
List metadata and all records currently stored in that account-owned list.
POST/api/v1/customer/createMyListCreate a list and optionally add its first records.
Request
- Required: accountId, projectName, name, and type.
- Optional: description, naics, items, isNonLocation.
Returns
A success status after the list and supplied records are created.
POST/api/v1/customer/updateMyListChange list metadata without changing its records.
Request
Required: accountId, listId, and at least one of name, description, or type.
Returns
The updated list identity and metadata. Record count and record contents are unchanged.
POST/api/v1/customer/deleteMyListPermanently delete an account-owned list and its records.
Request
Required: accountId and listId.
Returns
A success status. This operation is destructive.
POST/api/v1/customer/createMyRecordCreate a record in an account-owned list.
Request
Required: accountId, listId, and a storeData object.
Returns
A success status after the record is created.
POST/api/v1/customer/updateMyRecordUpdate a record in an account-owned list.
Request
Required: accountId, byListId, byRecordId, and storeData.
Returns
A success status after the record is updated.
POST/api/v1/customer/deleteMyRecordPermanently remove one record while preserving its list.
Request
Required: accountId, listId, and recordId. The aliases byListId and byRecordId are also accepted.
Returns
The deleted record ID, record name, list ID, and deletion timestamp. Records in shared common lists or lists feeding an ICP cannot be deleted through this endpoint.
Territories and geography
Read and manage territories, compare stored metrics, resolve geography, and analyze project coverage.
POST/api/v1/customer/resolvePlaceFind Census geography matching a named place.
Request
Required: accountId and name, for example Denver, CO. Optional: two-character country and geography (zip, county, state, metropolitan, or city).
Returns
A success status and Census geography candidates without an external geocoder. An empty candidates array means no match. Review ambiguous candidates before selecting geography.
POST/api/v1/customer/getMyTerritoriesList territories and optionally include units or boundaries.
Request
- Required: accountId.
- Optional: pagination, projectName, showUnits, byLocation, searchByString, byTag, showSimplePolygon, showDetailedPolygon.
Returns
Territories with identity, project associations, lifecycle state, geography, Census vintage, demographics, centroid, distance when requested, and optional units or GeoJSON boundaries.
POST/api/v1/customer/compareTerritoriesCompare allowlisted metrics stored on account territories.
Request
Required: accountId, projectId, and territoryIds containing 1-50 IDs. Optional metrics may contain population, households, area, or primaryIcpScore.
Returns
A normalized comparison based on stored territory metrics. Geometry is not used for the comparison.
POST/api/v1/customer/getEligibleGeographiesList geography units in a map viewport with assignment state.
Request
- Required: accountId, country, geography, and bounds.
- Optional: year, projectId, includeGeometry, includeDemographics, onlyEligible, and pagination.
Returns
Directional geography availability with assignment state, claiming territory IDs, centroid, area, and optional geometry/demographics. Use getSpatialOverlap when an exact boundary decision is required.
POST/api/v1/customer/getSpatialOverlapFind list records that fall inside an exact territory boundary.
Request
Required: accountId, projectId, territoryId, and listId. Optional includeItems and pagination control the returned records.
Returns
Exact detailed-boundary overlap count and an optional page of normalized records. The request fails rather than approximating when a detailed boundary is unavailable.
POST/api/v1/customer/getProjectAnalyticsReturn project totals grouped by compatible geography and Census vintage.
Request
Required: accountId and projectId.
Returns
Territory, list, and record counts plus demographic totals grouped by country, geography type, and Census vintage. Incomplete or incompatible groups are identified in unsummedGroups rather than blended into misleading totals.
POST/api/v1/customer/getGeographyDemographicsLook up stored Census demographics for one geography.
Request
Required: accountId, country, geography, and exactly one resolver: name, unitCode, or latitude with longitude. Optional: year.
Returns
Population, households, median age, land area, source provider, and Census vintage when a matching geography is found.
POST/api/v1/customer/geocodeAddressResolve an address through Wanderland-managed providers.
Request
Required: accountId and address. Set optional allowApproximate to true only when a city or place centroid is acceptable for area exploration.
Returns
A provider-normalized address, coordinates, and confidence, or a null match when no result satisfies the requested precision. Geocoding usage may count against the account's geocoding allowance.
POST/api/v1/customer/createMyTerritoryCreate a territory from validated geography units.
Request
Required: accountId, projectId, name, country, geography, non-empty units, and lifecycle status. Optional: year, description, tags, allowOverlap, and idempotencyKey.
Returns
The created territory, computed demographics, occupancy outcome, and collision details. Client-supplied demographic totals are ignored and recomputed by Wanderland.
POST/api/v1/customer/updateMyTerritoryStatusChange a territory's lifecycle state.
Request
Supply accountId, territoryId, target lifecycle status, and optional effective dates, reason, and expectedVersion.
Returns
The updated lifecycle state and transition details. Standard progression is available → reserved → assigned → inactive; elevated transitions require account-admin permission.
Decision automation
Automate territory availability checks and identify geography units with the strongest ICP opportunity.
POST/api/v1/customer/checkTerritoryAvailabilityRun the account's territory availability rules for a ZIP or geography code.
Request
- Required: accountId and either zip or unitCode.
- Optional: brandProfileId, projectId, country, year, minimumDistanceMiles, maxSearchMiles, and idempotencyKey.
Returns
A persisted decision of available, pending, unavailable, or no_match, with the requested unit, matching territory, nearest blocking territory, recommendation, rule settings, and decision-credit usage.
POST/api/v1/customer/findIcpOpportunitiesRank geography units by a selected Ideal Customer Profile.
Request
- Required: accountId.
- Optional: country, geography, year, projectId, icpId or icpTitle, bounds, topN (1-100), maxCandidates (1-5000), rankBy, and onlyEligible.
Returns
Ranked opportunities with geography code/name, ICP value, ICP penetration, demographics, centroid, area, eligibility, assignment state, source provider, and Census vintage. Results are directional and intended for opportunity screening.
Token management
Issue and manage scoped API credentials without storing a customer's Wanderland password in an integration.
POST/api/v1/customer/auth/tokenExchange email/password authentication for a scoped API token.
Request
Supply email, password, and accountId. Optional: a recognizable token name and scopes. Omitting scopes creates a read-only token. Requesting customer.write also grants read access.
Returns
The token secret once, plus token ID, prefix, scopes, and expiration. Tokens expire after 30 days and cannot issue other tokens.
POST/api/v1/customer/auth/listTokensList token metadata for an account.
Request
Required: accountId. Pagination is supported.
Returns
Token name, prefix, scopes, state, creation/expiration/revocation dates, and lastUsedAt. Token secrets and hashes are never returned.
POST/api/v1/customer/auth/revokeTokenImmediately revoke one API token.
Request
Required: accountId and tokenId.
Returns
Revocation status and token metadata. A revoked token fails on its next request.
Responses and errors
Newer endpoints return structured failures. Some original FRACT-compatible endpoints retain their existing plain-text authentication failures for backward compatibility.
Common status codes
- 200: request handled; inspect status and any business-level code.
- 400: invalid or incomplete input.
- 401: missing, invalid, expired, or revoked authentication.
- 403: authenticated user or token lacks permission.