Skip to main content
GET
/
stats
/
ambassadors
cURL
curl --request GET \
  --url https://api.growi.io/api/public/v1/stats/ambassadors \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "campaign_affiliate_id": 3490313,
      "user_id": 2628998,
      "email": "creator@example.com",
      "first_name": "Natalie",
      "last_name": "Garay",
      "name": "Natalie Garay",
      "joined_at": "2026-01-16T20:15:36Z",
      "social_accounts": [
        {
          "username": "nataliemgaray",
          "platform": "Instagram",
          "profile_share_url": "https://www.instagram.com/nataliemgaray/"
        }
      ],
      "custom_field_answers": [
        {
          "question": "What college do you attend?",
          "answer": "UCLA",
          "field_type": "text"
        }
      ],
      "user_location": "Temecula, CA 92591, US",
      "user_phone_number": "+15551234567"
    }
  ],
  "meta": {
    "total_ambassadors": 150,
    "current_page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}
Retrieves all ambassadors from ambassador program campaigns for the organization. Returns ambassador profile information including their social accounts, custom field answers from their application, and contact details.

​
Request Parameters

ParameterTypeDescriptionRequired
require_applicationStringFilter to only ambassadors who submitted an application. Pass false to include all ambassadors. Default is true.No
pageIntegerPage number for pagination. Default is 1.No
per_pageIntegerNumber of results per page. Default is 20. Maximum is 100.No
emailStringFilter by email (comma-separated for multiple)No
first_nameStringFilter by first name (partial match)No
last_nameStringFilter by last name (partial match)No
searchStringSearch by email or nameNo

​
Request Example

curl -X GET "https://api.growi.io/api/public/v1/stats/ambassadors?page=1&per_page=20" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY"

​
Response Example

{
  "data": [
    {
      "campaign_affiliate_id": 3490313,
      "user_id": 2628998,
      "email": "creator@example.com",
      "first_name": "Natalie",
      "last_name": "Garay",
      "name": "Natalie Garay",
      "joined_at": "2026-01-16T20:15:36Z",
      "social_accounts": [
        {
          "username": "nataliemgaray",
          "platform": "Instagram",
          "profile_share_url": "https://www.instagram.com/nataliemgaray/"
        },
        {
          "username": "dancingnatnat",
          "platform": "Tik Tok",
          "profile_share_url": "https://www.tiktok.com/@dancingnatnat"
        }
      ],
      "custom_field_answers": [
        {
          "question": "What college do you attend?",
          "answer": "UCLA",
          "field_type": "text"
        },
        {
          "question": "Upload your best photo",
          "answer": "https://imagedelivery.net/...",
          "field_type": "image"
        }
      ],
      "user_location": "Temecula, CA 92591, US",
      "user_phone_number": "+15551234567"
    }
  ],
  "meta": {
    "total_ambassadors": 150,
    "current_page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

​
Response Fields

FieldTypeDescription
dataArrayArray of ambassador objects
data[].campaign_affiliate_idIntegerUnique identifier for the campaign affiliate
data[].user_idIntegerUnique identifier for the user
data[].emailStringAmbassador’s email address
data[].first_nameStringAmbassador’s first name
data[].last_nameStringAmbassador’s last name
data[].nameStringAmbassador’s full name
data[].joined_atStringISO 8601 timestamp when the ambassador joined
data[].social_accountsArrayArray of connected social media accounts
data[].social_accounts[].usernameStringUsername on the platform
data[].social_accounts[].platformStringPlatform name (e.g., “Instagram”, “Tik Tok”, “Youtube”)
data[].social_accounts[].profile_share_urlStringDirect URL to the profile
data[].custom_field_answersArrayArray of application custom field responses
data[].custom_field_answers[].questionStringThe custom field question
data[].custom_field_answers[].answerStringThe ambassador’s answer (can be text or image URL)
data[].custom_field_answers[].field_typeStringType of field: “text”, “image”, “number”, etc.
data[].user_locationStringAmbassador’s location
data[].user_phone_numberStringAmbassador’s phone number (may be null)
metaObjectPagination metadata
meta.total_ambassadorsIntegerTotal number of ambassadors matching the query
meta.current_pageIntegerCurrent page number
meta.per_pageIntegerNumber of results per page
meta.total_pagesIntegerTotal number of pages available

​
Use Cases

This endpoint is useful for:
  • Ambassador Directory: Build a roster/directory page of all your ambassadors
  • CRM Integration: Sync ambassador data to external CRM systems
  • Profile Pages: Populate individual ambassador profile pages with their info and social links
  • Application Data: Access custom field answers from applications (including uploaded images)
  • Contact Management: Retrieve ambassador contact details including phone numbers and locations

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
require_application
string
default:true

Filter to only ambassadors who submitted an application. Pass false to include all ambassadors.

​
page
integer
default:1

Page number for pagination. Default is 1.

​
per_page
integer
default:20

Number of results per page. Default is 20. Maximum is 100.

Required range: x <= 100
​
email
string

Filter by email (comma-separated for multiple)

​
first_name
string

Filter by first name (partial match)

​
last_name
string

Filter by last name (partial match)

​
search
string

Search by email or name

Response

Ambassadors retrieved successfully

​
data
object[]
​
meta
object