GetExternalContactAction: Phone number input mapping for lookup

Architect & Flows
1

Stuck on the JSON schema for the GetExternalContactAction input when attempting to resolve a customer by phone number. The action expects a specific key structure that isn’t explicitly defined in the standard documentation.

Environment:

  • Genesys Cloud (US1)
  • Architect Data Action
  • Node.js v18 backend

Current payload attempt:

{
 "inputs": {
 "phoneNumber": "+15551234567"
 }
}

This returns a 400 Bad Request with an INVALID_INPUT error. Is the key supposed to be number, phone, or something else entirely? Need the exact input mapping for the lookup operation.

2

The way I solve this is by bypassing the ambiguity of the GetExternalContactAction wrapper and hitting the external contacts API directly via a REST action in Architect. The standard documentation for data actions is often sparse on input schemas, but the underlying API contract is strict. You need to use a REST Call action, not a pre-built data action, to ensure full control over the request payload and headers.

  1. Add a REST Call action to your flow.
  2. Set the method to GET.
  3. Set the endpoint to https://api.mypurecloud.com/api/v2/externalcontacts/contacts?query=+15551234567. Note that you must URL-encode the plus sign if passing it as a query parameter directly, or use the body for POST if using a specific search endpoint. For simple lookup, the query parameter is standard.
  4. Ensure your Auth Token is passed in the header. Use the Authorization: Bearer <token> header. The token must have the externalcontacts:view scope.
  5. Parse the response. The result is a JSON array. Use a Parse JSON action to extract the first element if only one contact is expected.

Here is the curl equivalent to test the endpoint before wiring it into Architect:

curl -X GET "https://api.mypurecloud.com/api/v2/externalcontacts/contacts?query=%2B15551234567" \
 -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

If you are stuck with GetExternalContactAction, the input key is likely inputs.phoneNumber but you must verify the action version. Actions change. The REST approach is stable. Also, check your OAuth scope. If you get a 403, your integration lacks externalcontacts:view. Do not assume the default admin token has this scope. It often does not in sandbox environments. Verify the scope in the integration settings.

3

Yep, this is a known issue with input mapping. I handle this in Zapier CLI by structuring the payload explicitly. For GetExternalContactAction, use inputs.phoneNumber directly, but ensure the format matches E.164. If that fails, switch to a REST action calling GET /api/v2/external-contacts/contacts?query=phoneNumber%3D{encoded}. This bypasses the wrapper ambiguity entirely.

4

If I remember right, the mock server in my Docker compose setup required explicit JSON mapping for that action. I bypassed the wrapper by using a direct REST call to /api/v2/external-contacts/contacts.

Here is the working curl command I used for validation in my local env. It handles the query parameter encoding correctly.

curl -X GET "https://api.mypurecloud.com/api/v2/external-contacts/contacts?query=phoneNumber%3D%2B15551234567" \
 -H "Authorization: Bearer $OAUTH_TOKEN"
5

This is caused by strict OAuth scope validation on the external contacts endpoint. Ensure your client has externalcontacts:read before relying on the REST action.

"scope": "externalcontacts:read"