Functions/Get-Contacts.ps1
|
function Get-Contacts { <# .SYNOPSIS Retrieves all contacts or a specific contact via the Gorelo API. .DESCRIPTION - If nothing is specified, retrieves all Contacts from /Contacts - If -ID is specified, retrieves a single Contact from /Contacts/{ID} - Otherwise, retrieves all Contacts and optionally filters by ClientId, PrimaryEmail, FirstName, or LastName (client-side). - Only one filter is allowed at a time (ClientId, PrimaryEmail, FirstName, or LastName). .PARAMETER BaseUrl Base API URL (default: https://api.usw.gorelo.io) .PARAMETER ApiVersion API version (default: v1) .PARAMETER ApiKey API key for authentication. .PARAMETER ID Retrieve a specific contact by ID. .PARAMETER ClientId Filter contacts by associated client ID (client-side). .PARAMETER PrimaryEmail Filter contacts by primary email address (client-side). .PARAMETER FirstName Filter contacts by first name (client-side). .PARAMETER LastName Filter contacts by last name (client-side). .EXAMPLE Get-Contacts -ApiKey "12345" .EXAMPLE Get-Contacts -ApiKey "12345" -ID "abc123" .EXAMPLE Get-Contacts -ApiKey "12345" -ClientId "7890" .EXAMPLE Get-Contacts -ApiKey "12345" -PrimaryEmail "*@example.com*" .EXAMPLE Get-Contacts -ApiKey "12345" -FirstName "*John*" .EXAMPLE Get-Contacts -ApiKey "12345" -LastName "*Smith*" #> [CmdletBinding()] param( [string]$BaseUrl = "https://api.usw.gorelo.io", [string]$ApiVersion = "v1", [Parameter(Mandatory = $true)] [string]$ApiKey, [string]$ID, [string]$ClientId, [string]$PrimaryEmail, [string]$FirstName, [string]$LastName ) # Count how many filters were supplied $filterCount = 0 foreach ($f in @($ID, $ClientId, $PrimaryEmail, $FirstName, $LastName)) { if ($f) { $filterCount++ } } Write-Verbose "Active filters: $filterCount" if ($filterCount -gt 1) { throw "Please specify only one search filter at a time (ID, ClientId, PrimaryEmail, FirstName, or LastName)." } if (-not $ApiKey) { throw "API key not provided. Use -ApiKey" } # Build API endpoint if ($ID) { $uri = "$($BaseUrl.TrimEnd('/'))/$($ApiVersion.Trim('/'))/contacts/$ID" } else { $uri = "$($BaseUrl.TrimEnd('/'))/$($ApiVersion.Trim('/'))/contacts" } $headers = @{ "X-API-Key" = $ApiKey "Accept" = "application/json" "Content-Type" = "application/json" } try { Write-Verbose "Sending GET request to $uri" $response = Invoke-RestMethod -Uri $uri -Method GET -Headers $headers -ErrorAction Stop } catch { $err = $_ $response = $err.Exception.Response if ($response) { $statusCode = $response.StatusCode.value__ $statusDesc = $response.StatusDescription Write-Warning "API call failed: $statusCode ($statusDesc)" } else { Write-Warning "API call failed: $($err.Exception.Message)" } throw } # Confirm no ID and response received before filtering if (-not $ID -and $response) { switch ($true) { { $ClientId } { $response = $response | Where-Object { $_.ClientId -like $ClientId }; break } { $PrimaryEmail } { $response = $response | Where-Object { $_.PrimaryEmail -like $PrimaryEmail }; break } { $FirstName } { $response = $response | Where-Object { $_.FirstName -like $FirstName }; break } { $LastName } { $response = $response | Where-Object { $_.LastName -like $LastName }; break } } } return $response } <# $APIKey = 'xxx' Get-Contacts -ApiKey $APIKey # Gets all Contacts Get-Contacts -ApiKey $APIKey -ID 'xxx' #Gets Contacts by ID Get-Contacts -ApiKey $APIKey -ClientId 'xxx' #Gets Contacts by ClientId Get-Contacts -ApiKey $APIKey -PrimaryEmail 'xxx' #Gets Contacts by PrimaryEmail Get-Contacts -ApiKey $APIKey -FirstName 'xxx' #Gets Contacts by FirstName Get-Contacts -ApiKey $APIKey -LastName 'xxx' #Gets Contacts by LastName #> |