Architect GetExternalContactAction returning 404 for valid phone lookup

Architect & Flows
1

Ran into a weird issue today with the GetExternalContactAction in architect. i am trying to implement a simple customer lookup flow where we pass the phone_number from the inbound call to an external api via the action. the endpoint is https://api.internal.example.com/v1/customers/lookup. when i test this in the architect simulation mode, it works perfectly fine. the json payload returned contains the customer_id and name fields as expected. however, when i run this against a live call in the production environment, the action consistently fails with a 404 not found error.

here is the configuration for the action:

{
 "actionType": "GetExternalContactAction",
 "settings": {
 "uri": "https://api.internal.example.com/v1/customers/lookup?phone={{call.from.number}}",
 "method": "GET",
 "contentType": "application/json"
 }
}

i have verified that the call.from.number variable contains the correct e.164 formatted string (e.g., +6591234567). i also added a trace step before the action to log the actual uri being constructed, and it looks correct. the external api is returning a valid 200 ok response when i hit it directly from postman with the same query parameters.

i am suspecting that the architect runtime might be modifying the request headers or the way the query string is encoded. i tried adding an authorization header in the action settings, but the error persists. is there a known issue with GetExternalContactAction handling query parameters in the uri field versus the body? or am i missing a specific configuration for external integrations in the current architect version? any insights on debugging this 404 discrepancy between simulation and live execution would be greatly appreciated. i have checked the architect logs but they only show the generic failed to retrieve external contact message without the actual http response body from the backend.

2

The simplest way to resolve this is to verify the allowInboundFromUntrusted flag on the external contact definition in the administration console.

simulation mode bypasses the platform’s security checks for untrusted origins, so the 404 occurs in production because the request is blocked before hitting your endpoint. ensure the url pattern matches exactly and the contact is marked as trusted or allows inbound traffic from unknown sources.

3

This is caused by simulation mode bypassing the strict untrusted origin validation. Enable allowInboundFromUntrusted on the external contact definition or verify the URL pattern matches exactly, otherwise production requests will fail with 404. See docs: https://developer.genesys.cloud/architect/external-contacts

4

I normally fix this by isolating the external contact configuration in a Terraform module and validating the HTTP response codes before the Architect flow executes. The 404 error in production, despite success in simulation, often stems from how the platform handles DNS resolution or TLS certificate validation for untrusted origins, which simulation mode ignores.

To ensure the external contact is correctly provisioned and reachable, I recommend the following steps:

  • Define the external contact explicitly in Terraform using the genesyscloud_externalcontact resource. This ensures the allowInboundFromUntrusted flag is set to true and the URL pattern is strictly defined.
  • Verify the endpoint accessibility using a curl command from a server within your Genesys Cloud VPC or public network to rule out firewall issues.
  • Add a logging step in Architect immediately before the GetExternalContactAction to capture the exact phone number format being passed.
  • Check the Genesys Cloud logs for any underlying HTTP errors that might be masked by the 404 response.

Here is an example of how I define the external contact in Terraform:

resource "genesyscloud_externalcontact" "customer_lookup" {
 name = "Customer Lookup Service"
 url_pattern = "https://api.internal.example.com/v1/customers/lookup?phone=${phone}"
 allow_inbound_from_untrusted = true
 
 request {
 method = "GET"
 headers = {
 "Content-Type" = "application/json"
 "Authorization" = "Bearer ${var.api_token}"
 }
 }
 
 response {
 success_code = 200
 timeout = 5000
 }
}

This configuration ensures that the platform explicitly allows requests to the untrusted domain. If the issue persists, check if the phone number format includes country codes, as mismatched formats can cause the lookup to fail silently or return a 404 if the backend API expects a specific format.