GET/v1/profiles

List profiles

Returns a paginated list of every profile in your developer account, ordered by creation time with the oldest first. Use the optional externalId, limit, and offset parameters to narrow the results down or page through them.

curl https://api.synposter.com/v1/profiles?limit=50 \
  -H "x-api-key: YOUR_API_KEY"

Query parameters

Field	Type	Required	Description
externalId	string	No	Narrows the results down to the single profile that has this externalId, useful when you only know the user's ID in your own database.
limit	integer	No	How many profiles to return per page. Must be between 1 and 100; defaults to 50 when omitted.
offset	integer	No	How many profiles to skip before returning results, used to page through the list. Defaults to 0.

Response (200)

json

{
  "data": [
    {
      "id": "9b3a...",
      "name": "Alice's Brand",
      "externalId": "user-42",
      "metadata": { "tier": "pro"},
      "createdAt": "...",
      "updatedAt": "..."
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "hasMore": false
  }
}

Field	Type	Required	Description
data	object[]	Yes	An array of profile objects, ordered by creation time with the oldest first. Empty if you have no profiles or the filter didn't match.
data[].id	string	Yes	Synposter's UUID for the profile.
data[].name	string	Yes	The human-readable label that was set when the profile was created.
data[].externalId	string \| null	Yes	Your own identifier for this profile, or null if one was never set.
data[].metadata	object \| null	Yes	The arbitrary JSON metadata stored on the profile. Null if none was set.
data[].createdAt	string	Yes	ISO 8601 timestamp of when the profile was created.
data[].updatedAt	string	Yes	ISO 8601 timestamp of the last time the profile was updated.
pagination.limit	integer	Yes	The page size that was applied. Echoes the limit query parameter, or the default of 50.
pagination.offset	integer	Yes	The offset that was applied to this page. Echoes the offset query parameter, or 0.
pagination.total	integer	Yes	Total number of profiles in your account that match the filter, across every page.
pagination.hasMore	boolean	Yes	True when more profiles exist beyond this page. Increment offset by limit to fetch the next one.

Status codes

200	The list was returned successfully. The data array may be empty if you have no profiles, or if the filter didn't match any.
400	The limit or offset query parameter was out of range or not an integer.
401	The API key was missing or invalid.
500	Something failed on Synposter's side. Safe to retry.