Clubs API References

Get All Clubs

URL: https://api.gradual-api.com/public-api/v1/clubs

HTTP Method: GET

Content type: application/json

Tier: Medium

Response Example:

[
    {
        "clubId": "6553ce608b3f645e79d95034",
        "name": "Engineering",
        "slug": "engineering",
        "accessType": "Open"
    },
    {
        "clubId": "6553ce608b3f645e79d95035",
        "name": "Product Leaders",
        "slug": "product-leaders",
        "accessType": "Private"
    }
]

Get a User's Clubs by User ID

URL: https://api.gradual-api.com/public-api/v1/users/:userId/clubs

HTTP Method: GET

Content type: application/json

Tier: Light

Path Parameters:

userId, string, required, this is the unique identifier to find a user

Response Example:

{
    "userEmail": "[email protected]",
    "userFirstName": "test_first",
    "userLastName": "test_last",
    "userId": "6553ce608b3f645e79d95034",
    "userClubs": [
        {
            "clubId": "6553ce608b3f645e79d95034",
            "name": "Club 1",
            "slug": "club-1"
        }
    ]
}

Add a User to a Club

URL: https://api.gradual-api.com/public-api/v1/clubs/:clubId/users

HTTP Method: POST

Content type: application/json

Tier: Medium

Path Parameters:

clubId, string, required, this is the unique identifier to find a club

Request Body Parameters:

userId, string, optional, this is the unique identifier to find a user (at least one of userId or email is required)
email, string, optional, this is the unique identifier to find a user (at least one of userId or email is required)

Response Example:

{
    "success": true
}

Delete a User from a Club

URL: https://api.gradual-api.com/public-api/v1/clubs/:clubId/users

HTTP Method: DELETE

Content type: application/json

Tier: Medium

Path Parameters:

clubId, string, required, this is the unique identifier to find a club

Request Body Parameters:

userId, string, optional, this is the unique identifier to find a user (at least one of userId or email is required)
email, string, optional, this is the unique identifier to find a user (at least one of userId or email is required)

Response Example:

{
    "success": true
}

Update User Clubs

URL: https://api.gradual-api.com/public-api/v1/updateUserClubs

HTTP Method: POST

Content type: application/json

Tier: Medium

Updates a user's club memberships. Supports two modes: add to add clubs to the user's existing memberships, or override to replace all current memberships with the specified clubs.

Request Body Parameters:

email, string, optional, the user's email address
userId, string, optional, the user's ID
clubIds, array of strings, optional, list of club IDs (up to 10)
clubNames, array of strings, optional, list of club names (up to 10)
mode, string, required, either add or override
- In add mode, the user's existing memberships are preserved and the specified clubs are added
- In override mode, the user will be removed from any clubs not in the provided list
- Use mode = "override" with clubIds/clubNames = [] to remove user from all clubs

Either email or userId must be provided. Either clubIds or clubNames must be provided.

Request Body Example 1:

{
    "email": "[email protected]",
    "clubNames": ["Engineering", "Product"],
    "mode": "add"
}

Request Body Example 2:

{
    "userId": "6553ce608b3f645e79d95034",
    "clubIds": ["6553ce608b3f645e79d95040", "6553ce608b3f645e79d95041"],
    "mode": "override"
}

Response Example:

{
    "userEmail": "[email protected]",
    "userId": "6553ce608b3f645e79d95034",
    "userFirstName": "Jane",
    "userLastName": "Doe",
    "oldClubs": [
        {
            "clubId": "6553ce608b3f645e79d95040",
            "name": "Engineering",
            "slug": "engineering"
        }
    ],
    "newClubs": [
        {
            "clubId": "6553ce608b3f645e79d95040",
            "name": "Engineering",
            "slug": "engineering"
        },
        {
            "clubId": "6553ce608b3f645e79d95041",
            "name": "Product",
            "slug": "product"
        }
    ],
    "results": [
        {
            "clubName": "Engineering",
            "clubId": "6553ce608b3f645e79d95040",
            "status": "already_member"
        },
        {
            "clubName": "Product",
            "clubId": "6553ce608b3f645e79d95041",
            "status": "success"
        }
    ]
}

Per-Club Result Statuses:

success — user was successfully added to the club
already_member — user is already a member of the club (no action taken)
failed — operation failed, see reason field for details

Notes:

Duplicate values within clubIds or clubNames are rejected with a 400 error.
If mode is add and no valid clubs are resolved, the request is rejected with a 400 error.
Returns 400 if the user is not found or has been archived.

Batch Add Club Members

URL: https://api.gradual-api.com/public-api/v1/clubs/:clubId/users/batch

HTTP Method: POST

Content type: application/json

Tier: Heavy

This endpoint adds multiple users to a club in a single request. The operation is processed asynchronously — you receive a job ID immediately and poll for results.

Path Parameters:

clubId, string, required, the club's ID

Request Body Parameters:

users, array, required, array of user objects (1–100 items)
users[].email, string, optional, must be a valid email address
users[].userId, string, optional, the user's ID

Each user object must have at least one of email or userId.

Request Body Example:

{
    "users": [
        {
            "email": "[email protected]"
        },
        {
            "userId": "6553ce608b3f645e79d95034"
        },
        {
            "email": "[email protected]",
            "userId": "6553ce608b3f645e79d95035"
        }
    ]
}

Response Example (202 Accepted):

{
    "jobId": "6553ce608b3f645e79d95034",
    "status": "pending"
}

Notes:

The club must exist, otherwise a 400 error is returned. Individual users are validated during async job processing.
The maximum batch size is 100 users per request.
Poll the Get Batch Club Member Job Status endpoint to check the results after submitting.

Get Batch Club Member Job Status

URL: https://api.gradual-api.com/public-api/v1/clubs/:clubId/users/batch/:jobId

HTTP Method: GET

Content type: application/json

Tier: Light

Path Parameters:

clubId, string, required, the club's ID
jobId, string, required, the job ID returned from the batch add request

Response Example (job completed):

{
    "jobId": "6553ce608b3f645e79d95034",
    "status": "completed",
    "results": [
        {
            "recordPosition": 0,
            "email": "[email protected]",
            "status": "success"
        },
        {
            "recordPosition": 1,
            "userId": "6553ce608b3f645e79d95034",
            "status": "success"
        }
    ]
}

Response Example (job with partial failures):

{
    "jobId": "6553ce608b3f645e79d95034",
    "status": "completed",
    "results": [
        {
            "recordPosition": 0,
            "email": "[email protected]",
            "status": "success"
        },
        {
            "recordPosition": 1,
            "email": "[email protected]",
            "status": "failed",
            "reason": "user not found"
        }
    ]
}

Job Statuses:

pending — job is queued and waiting to be processed
processing — job is currently being processed
completed — all members have been processed (check individual results for per-member status)
failed — job encountered a fatal error

Per-Member Result Statuses:

success — user was successfully added to the club
failed — operation failed, see reason field for details

Notes:

A completed job does not mean all members were added successfully. Always check the individual results entries for per-member status.
The recordPosition field corresponds to the index of the user in the original users array (starting from 0).
Returns 404 if the job is not found or does not belong to the specified club.

Spaces

Content