Get phone verification contacts
Page through the phone numbers your traders verified by SMS in your community, each with the trader's email.
- Method
- GET
- Path
https://api.returning.ai / v1/ community-analytics/ phone-verification-contacts - Permission
- customerSuccess
- Retries
- Read-only; exact retries are safe
When to use this
- Copy verified phone numbers into your CRM or marketing tool on a schedule.
- Check which traders have completed phone verification in your community.
- Match verified numbers to your own client records by email.
Authentication#
- Header
Authorization: Bearer <API_KEY>- Permission
- customerSuccessShown in the dashboard as “Customer Success”
Use a Community API key with customerSuccess, shown in the dashboard as Customer Success, and keep it on your server. The key decides the community, so you only see contacts from your own community and never send a communityId. A key without the permission gets 401, not 403. Personal API keys are rejected with 401.
Behaviour#
A trader appears here once they verify a phone number by SMS in your community. If they verify again with another number, the new number replaces the old one, so each trader has at most one contact. Contacts are returned in a fixed order, so you can page through all of them; read every page up to totalPages.
Every row is personal data. Responses are sent with Cache-Control: no-store, and you should store them with the same care as the rest of your client records.
Request#
Query parameters#
Headers#
customerSuccess.RuleBearer <API_KEY>
curl --request GET \
--url 'https://api.returning.ai/v1/community-analytics/phone-verification-contacts?page=1&limit=100' \
--header 'Authorization: Bearer <API_KEY>'
Response#
A 200 returns the page in data.data and the totals in data.pagination. A community with no verified numbers returns 200 with an empty data.data and total 0, not 404.
Rulesuccess
null when the account has none.Eg"trader@example.com"
RuleE.164, such as +6581234567
Eg"+6581234567"
limit. 0 when there are no contacts.{
"status": "success",
"message": "Phone verification contacts fetched successfully",
"data": {
"data": [
{
"email": "trader@example.com",
"phoneNumber": "+6581234567"
}
],
"pagination": {
"total": 1,
"page": 1,
"limit": 100,
"totalPages": 1
}
}
}
Errors#
Errors on this endpoint have no machine-readable code; branch on the HTTP status. A validation 400 lists each problem in details, as field and message. A 401 carries only message, or status and message.
Fix the request02
details names a field and says why: page must be a whole number of 1 or more, limit a whole number from 1 to 500, and query means an unknown parameter was sent. Only page and limit are accepted; communityId is rejected.Invalid token), unknown (Invalid API key) or expired, it's a personal key, or it lacks customerSuccess (Your api key does not have permission to access this action). Send Authorization: Bearer <API_KEY> with a Community API key, and add Customer Success in Settings > Integration > API Keys.Retry with backoff02
RateLimit header, then retry.Authentication failed). Retry the same request with exponential backoff.{
"status": "fail",
"message": "Validation error",
"details": [
{
"field": "query",
"message": "Unknown query parameter"
}
]
}