Skip to main content
A connection binds your organization’s credentials to one platform service — for example, your Five9 Configuration Service login. Tasks never carry credentials themselves; they reference a connection by ID, and the platform resolves the credentials at runtime. Connections belong to your organization and are never visible to other accounts. 
{
  "task_id": "add_contact",
  "task_name": "Add to dialing list",
  "platform_id": "five9",
  "service_id": "five9__configuration_service",
  "action_id": "five9__configuration_service__add_to_list",
  "connection_id": "conn_e5f6g7h8",
  "parameters": { "list_name": "Outbound Q3" }
}
Create the connection first, then reference its connection_id from any task that calls that service. Built-in utility actions (like getdialed__utils__echo) need no connection.

​
The connection object

FieldTypeDescription
idstringConnection identifier (e.g. conn_e5f6g7h8).
namestringHuman-readable name (e.g. “Five9 Production”).
platform_idstringPlatform from the catalog (e.g. five9).
service_idstringService from the catalog. Must start with platform_id + "__" (e.g. five9__configuration_service).
auth_methodstringOne of basic_auth, oauth2, client_credentials, jwt, api_key, soap_wss.
credentials_refstringReference to where the secrets are stored. Secrets are resolved from secure storage at runtime and never returned by the API.
statusstringactive, expired, or revoked.
last_verifieddatetime | nullWhen the credentials last passed a verification test.

​
Managing connections

All management endpoints require authentication and operate only on your organization’s connections.
MethodEndpointPurpose
GET/connectionsList connections. Filter with status, paginate with limit and skip.
POST/connectionsCreate a connection. Returns 201 with the created object.
GET/connections/{connection_id}Fetch one connection.
PUT/connections/{connection_id}Update a connection — a full replacement; supply all fields.
DELETE/connections/{connection_id}Delete a connection. Returns 204.
Creating one: 
curl -X POST "$BASE_URL/connections" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Five9 Production",
    "platform_id": "five9",
    "service_id": "five9__configuration_service",
    "auth_method": "basic_auth",
    "credentials_ref": "vault://five9/prod"
  }'
A connection’s status is under your control — it is never flipped automatically, even when a verification test fails. Transition it explicitly with PUT /connections/{connection_id} when credentials expire or are revoked.

​
Testing credentials

Two endpoints verify that credentials actually work against the live platform, so you can catch a bad password before a flow fails at 2 a.m. Both require an admin-role caller and complete within a 15-second budget.
1

Test before saving

POST /connections/test takes platform_id, service_id, auth_method, and a platform-specific credentials object (e.g. {"username": ..., "password": ...} for Five9 basic auth). It returns a pass/fail verdict and persists nothing — ideal for a “test before save” flow.
2

Test a saved connection

POST /connections/{connection_id}/test (no request body) resolves the saved connection’s stored credentials and runs the same verification. On success, the connection’s last_verified timestamp is updated.
Both endpoints return 200 with a TestResult body for every verification outcome — success, bad credentials, even a timeout. 4xx statuses are reserved for problems with your request itself (malformed body, missing auth, unknown connection ID).

​
The TestResult body

{
  "success": false,
  "error": "AUTH_FAILED",
  "details": "Five9 rejected the supplied credentials (HTTP 401/403).",
  "latency_ms": 312,
  "tested_at": "2026-05-18T10:30:00Z"
}
FieldTypeDescription
successbooleantrue if the platform accepted the credentials.
errorstring | nullAn error code (below) when success is false; null on success.
detailsstringHuman-readable diagnostic. Never contains credentials.
latency_msintegerRound-trip time of the verification call, in milliseconds.
tested_atdatetimeUTC timestamp of when the test started.

​
Error codes

CodeMeaning
AUTH_FAILEDThe platform rejected the credentials.
NETWORKThe platform couldn’t be reached (DNS, TCP, TLS), or the stored secret couldn’t be found.
TIMEOUTThe test exceeded the 15-second budget.
RATE_LIMITEDThe platform throttled the request.
PERMISSION_DENIEDAuthenticated, but not authorized for the verification call.
INVALID_CREDENTIALS_SHAPEThe credentials object is missing keys the platform requires (e.g. Five9 basic auth needs username and password) — caught before any network call.
UNKNOWNAnything else, including platforms without a test handler.
422 and INVALID_CREDENTIALS_SHAPE look similar but differ: 422 means the request body itself is malformed (wrong types, missing schema fields, service_id not prefixed with the platform ID), while 200 + INVALID_CREDENTIALS_SHAPE means the body parsed fine but the credentials object lacks what the target platform needs.

​
Next steps

Integration catalog

Browse the platforms and services a connection can target.

Build your first flow

Put a connection to work in a multi-step flow.