curl --request POST \
--url https://api.superx.so/v1/contact-lists/{id}/members \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"handle": "founderhandle"
}
'{
"data": {
"id": "m1a2b3c4d5e6f7g8h9i0j",
"x_user_id": "944883311",
"username": "founderhandle",
"name": "Founder Name",
"avatar_url": "https://pbs.twimg.com/profile_images/...",
"added_at": "2026-06-25T11:00:00.000Z"
},
"duplicate": true
}{
"data": {
"id": "m1a2b3c4d5e6f7g8h9i0j",
"x_user_id": "944883311",
"username": "founderhandle",
"name": "Founder Name",
"avatar_url": "https://pbs.twimg.com/profile_images/...",
"added_at": "2026-07-08T10:00:00.000Z"
}
}{
"error": {
"code": "system_list_read_only",
"message": "System lists are managed automatically and can't be edited."
}
}{
"error": {
"code": "invalid_api_key",
"message": "Unknown or revoked API key"
}
}{
"error": {
"code": "insufficient_scope",
"message": "This API key is read-only. Create a key with the write scope to use this endpoint."
}
}{
"error": {
"code": "user_not_found",
"message": "No X account matches that handle."
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded for the Pro plan (30 requests/min). Upgrade for higher limits.",
"retry_after": 42
}
}{
"error": {
"code": "upstream_error",
"message": "Failed to fetch scheduled posts. Try again shortly."
}
}{
"error": {
"code": "upstream_unavailable",
"message": "The scheduling service is temporarily unavailable. Retry with the same Idempotency-Key."
}
}Add a contact list member
Add a person to a list you created, by handle (live profile lookup)
or by x_user_id (numeric X user id already known to SuperX).
Exactly one of the two. Naturally idempotent: adding someone already
in the list returns 200 with the existing member and
duplicate: true, and writes nothing. Works for your main account or any account linked to it
(account_id); accounts shared with you are read-only.
Needs the write scope. No Idempotency-Key support (none is
needed).
Counts against a separate live-contact-enrichment rate limit (varies by plan), in addition to the normal write limits.
curl --request POST \
--url https://api.superx.so/v1/contact-lists/{id}/members \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"handle": "founderhandle"
}
'{
"data": {
"id": "m1a2b3c4d5e6f7g8h9i0j",
"x_user_id": "944883311",
"username": "founderhandle",
"name": "Founder Name",
"avatar_url": "https://pbs.twimg.com/profile_images/...",
"added_at": "2026-06-25T11:00:00.000Z"
},
"duplicate": true
}{
"data": {
"id": "m1a2b3c4d5e6f7g8h9i0j",
"x_user_id": "944883311",
"username": "founderhandle",
"name": "Founder Name",
"avatar_url": "https://pbs.twimg.com/profile_images/...",
"added_at": "2026-07-08T10:00:00.000Z"
}
}{
"error": {
"code": "system_list_read_only",
"message": "System lists are managed automatically and can't be edited."
}
}{
"error": {
"code": "invalid_api_key",
"message": "Unknown or revoked API key"
}
}{
"error": {
"code": "insufficient_scope",
"message": "This API key is read-only. Create a key with the write scope to use this endpoint."
}
}{
"error": {
"code": "user_not_found",
"message": "No X account matches that handle."
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded for the Pro plan (30 requests/min). Upgrade for higher limits.",
"retry_after": 42
}
}{
"error": {
"code": "upstream_error",
"message": "Failed to fetch scheduled posts. Try again shortly."
}
}{
"error": {
"code": "upstream_unavailable",
"message": "The scheduling service is temporarily unavailable. Retry with the same Idempotency-Key."
}
}Authorizations
A SuperX API key ("sxk_..."), created in the SuperX app under Account > API / MCP / CLI. Keys are server-side secrets.
Path Parameters
The list id from GET /v1/contact-lists.
Query Parameters
Account to act on, from GET /v1/accounts. Defaults to your main account. An id outside your accounts returns 404 account_not_found.