GraphQL API
About:
The GraphQL API lets you pull reporting data out of Echo into your own reporting system. It is currently read-only. You can query data but not write updates back.
This guide assumes a basic understanding of coding and GraphQL. For general GraphQL learning resources, see https://graphql.org/learn/.
Schema & Documentation
Interactive docs: https://YOURTENANTNAME.echoglobal.org/graphql-docs (requires login as an admin)
Generating an API Key
1. Log in to your Echo instance with an admin account.
2. Go to Admin > Email > API Tokens.
3. Click "Generate New Token" in the top right.
4. Copy and save the token -- it is only displayed once.
Making Your First Query
Send a POST request to https://YOURTENANTNAME.echoglobal.org/graphql with your API token in the Authorization header.
Example using curl:
API_URL="https://YOURTENANTNAME.echoglobal.org/graphql"
API_TOKEN="your-token-from-admin-api-tokens"
curl -s -X POST "$API_URL" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_TOKEN" \
-d '{
"query": "{ clients(first: 3) { edges { node { id name clientPhones { number } } } } }"
}'
Pagination
Results use cursor-based pagination (Relay-style). Each connection returns up to 250 items per page by default.
Use the "first" argument to control page size, and "after" with the "endCursor" value to fetch the next page.
Example response structure:
{
"data": {
"clients": {
"pageInfo": {
"endCursor": "MjA",
"hasNextPage": true
},
"edges": [
{
"node": { "id": "1", "name": "..." }
}
]
}
}
}
Fetching All Pages
This script pages through all results and writes them to a JSON file:
#!/bin/bash
API_URL="https://YOURTENANTNAME.echoglobal.org/graphql"
API_TOKEN="your-token-from-admin-api-tokens"
END_CURSOR=""
ALL_RESULTS="[]"
while true; do
AFTER_ARG=""
if [ -n "$END_CURSOR" ]; then
AFTER_ARG="after: \"$END_CURSOR\""
fi
RESPONSE=$(curl -s -X POST "$API_URL" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_TOKEN" \
-d "{
\"query\": \"{ conversations(${AFTER_ARG:+$AFTER_ARG}) { pageInfo { endCursor hasNextPage } edges { node { id topic createdAt client { id name email clientPhones { number } } } } } }\"
}")
HAS_NEXT=$(echo "$RESPONSE" | jq '.data.conversations.pageInfo.hasNextPage')
END_CURSOR=$(echo "$RESPONSE" | jq -r '.data.conversations.pageInfo.endCursor')
PAGE=$(echo "$RESPONSE" | jq '.data.conversations.edges')
ALL_RESULTS=$(echo "$ALL_RESULTS" "$PAGE" | jq -s 'add')
if [ "$HAS_NEXT" != "true" ]; then
break
fi
done
echo "$ALL_RESULTS"
Usage:
bash script.sh > result.json
This is a basic example; customize the query fields and filtering to match your needs.
