Users API References

Get All User Profile Questions

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

HTTP Method: GET

Content type: application/json

Tier: Medium

Returns the list of all user profile questions.

Response Example:

[
    {
        "id": "6553ce608b3f645e79d95034",
        "title": "What is your area of expertise?",
        "inUserProfileForm": true
    },
    {
        "id": "6553ce608b3f645e79d95035",
        "title": "Community active score",
        "inUserProfileForm": false
    }
]

Notes:

All user profile questions are returned. Value of inUserProfileForm indicates whether a question is included in users' profile form.
Use the question id with the Get User Profile Question Details endpoint to retrieve full question configuration including type, options, visibility, etc.
Question IDs can also be passed as extra parameters in the Update a User by User ID and Update User Profile by Email endpoints to update a user's answers.

Get User Profile Question Details

URL: https://api.gradual-api.com/public-api/v1/userProfileQuestions/:questionId

HTTP Method: GET

Content type: application/json

Tier: Light

Path Parameters:

questionId, string, required, the question's ID

Response Example (Single Select):

{
    "id": "6553ce608b3f645e79d95034",
    "title": "What is your area of expertise?",
    "subtitle": "Select the option that best describes your role",
    "required": true,
    "visibility": "Public",
    "type": "Single Select",
    "options": ["Engineering", "Product", "Design", "Marketing", "Sales"],
    "withOtherOption": true
    "inUserProfileForm": true,
    "isUserEditable": true
}

Response Example (Multi Select):

{
    "id": "6553ce608b3f645e79d95035",
    "title": "Which topics are you interested in?",
    "subtitle": "",
    "required": false,
    "visibility": "Public",
    "type": "Multi Select",
    "options": ["AI/ML", "Cloud", "Security", "DevOps", "Frontend"],
    "withOtherOption": false,
    "minNumOfSelection": 1,
    "maxNumOfSelection": 3
    "inUserProfileForm": true,
    "isUserEditable": true
}

Response Example (Single Line Text):

{
    "id": "6553ce608b3f645e79d95036",
    "title": "Community active score",
    "subtitle": "",
    "required": false,
    "visibility": "Secret",
    "type": "Single Line Text",
    "maxLength": 255
    "inUserProfileForm": false,
    "isUserEditable": false
}

Response Example (Paragraph):

{
    "id": "6553ce608b3f645e79d95037",
    "title": "Tell us about yourself",
    "subtitle": "",
    "required": false,
    "visibility": "Public",
    "type": "Paragraph",
    "maxLength": 3000,
    "minLength": 10
    "inUserProfileForm": true,
    "isUserEditable": true
}

Response Example (Location):

{
    "id": "6553ce608b3f645e79d95038",
    "title": "Where are you based?",
    "subtitle": "",
    "required": true,
    "visibility": "Public",
    "type": "Location",
    "locationType": "city",
    "inUserProfileForm": true,
    "isUserEditable": false
}

Response Fields:

id, string, the question's unique identifier
title, string, the question text
subtitle, string, optional helper text displayed below the question
required, boolean, whether the question must be answered
~~isPrivate~~, boolean, deprecated, see visibility
visibility, string, visibility level (Public, MembersOnly, Secret)
type, string, question type (Single Line Text, Paragraph, Single Select, Multi Select, Location, URL)
options, array of strings, available choices (Single Select and Multi Select questions only)
withOtherOption, boolean, whether a free-text "Other" option is allowed (Single Select and Multi Select questions only)
minNumOfSelection, integer, minimum selections required (Multi Select questions only, omitted if not configured)
maxNumOfSelection, integer, maximum selections allowed (Multi Select questions only, omitted if not configured)
maxLength, integer, maximum character length (Single Line Text and Paragraph questions only)
minLength, integer, minimum character length (Paragraph questions only, omitted if not configured)
locationType, string, type of location expected (Location questions only)
inUserProfileForm, boolean, whether the question is included in users' profile form
isUserEditable, boolean, whether the question answer can be edited by user.

Notes:

Returns 404 if the question is not found.
The type field returns a human-readable label. Possible values: Single Line Text, Paragraph, Single Select, Multi Select, Location, URL.

Get a User by User ID

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

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:

{
    "userId": "6553ce608b3f645e79d95034",
    "userEmail": "[email protected]",
    "userFirstName": "Jane",
    "userLastName": "Doe",
    "displayName": "Jane Doe",
    "userTitle": "Software Engineer",
    "userCompany": "Test Company",
    "userAvatarUrl": "https://some-source.net/avatar-12345.png",
    "userLinkedIn": "https://www.linkedin.com/in/janedoe",
    "userLocation": "San Francisco, CA, United States",
    "memberType": "Standard",
    "approvalStatus": "approved",
    "spaces": [
        "Space 1",
        "Space 2"
    ],
    "questionnaire": {
        "What is your area of expertise?": "Engineering",
        "Which topics are you interested in?": "AI/ML;Cloud"
    },
    "signUpAt": "2024-06-12T08:21:16.388Z",
    "lastLoginAt": "2024-06-14T16:07:13.786Z",
    "onboardingAt": "2024-06-13T04:57:19.262Z",
    "lifetimePoints": 150,
    "remainingPoints": 75
}

Response Fields:

userId, string, the tenant user's unique identifier
userEmail, string, the user's email address
userFirstName, string, the user's first name
userLastName, string, optional, the user's last name (if available)
displayName, string, the user's full display name (typically First Name + Last Name)
userTitle, string, the user's job title/position
userCompany, string, the user's company name
userAvatarUrl, string, optional, URL of the user's profile picture (if available)
userLinkedIn, string, optional, the user's LinkedIn profile URL (if available)
userLocation, string, optional, the user's location (if available)
memberType, string, the user's membership type: Standard, Guest, or Limited Approval
approvalStatus, string, the user's approval status: approved, pending, or unapproved
spaces, array of strings, space names the user is assigned to (empty array if none)
questionnaire, object, map of profile question titles to the user's answers; multi-select answers are semicolon-delimited (empty object {} if no answers)
signUpAt, string, optional, ISO 8601 timestamp of when the user signed up
lastLoginAt, string, optional, ISO 8601 timestamp of the user's last login
onboardingAt, string, optional, ISO 8601 timestamp of when the user completed onboarding
lifetimePoints, number, optional, the user's total lifetime contribution points
remainingPoints, number, optional, the user's remaining redeemable points balance
externalId, string, optional, the user's external ID (if the user account is linked to an external source)
externalDisplayId, string, optional, the user's external display name (if the user account is linked to an external source)
externalProfileUrl, string, optional, URL to the user's external profile (if the user account is linked to an external source)

List Users

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

HTTP Method: GET

Content type: application/json

Tier: Medium

Returns a paginated list of the users in your tenant. Supports filtering by sign-up date range, approval status, and member type, plus sorting.

Query Parameters:

All parameters are optional.

pageNum, integer (≥ 1), the page number to retrieve (1-based), defaults to 1
pageSize, integer (1–200), number of users per page, defaults to 50
signedUpFromDate, string (YYYY-MM-DD), only return users who signed up on or after this date (UTC, inclusive)
signedUpToDate, string (YYYY-MM-DD), only return users who signed up on or before this date (UTC, inclusive)
approvalStatus, string, filter by approval status, one of Pending, Approved, Unapproved
memberType, string, filter by member type, one of Standard, Guest, Limited Approval
sortBy, string, field to sort by, one of createdAt, signUpAt, defaults to createdAt
sortDirection, string, sort direction, one of asc, desc, defaults to desc
email, string, when provided, switches this endpoint into single-user lookup mode (see Get a User by Email below). Special characters must be URL-encoded — for example [email protected] must be sent as user%[email protected]. Unencoded + is decoded as space by the URL parser and will be rejected with a 400 invalid email error.

Response Example:

{
    "size": 50,
    "pageNumber": 1,
    "pageSize": 50,
    "results": [
        {
            "userId": "5f8d0d55b54764421b7156c3",
            "userEmail": "[email protected]",
            "userFirstName": "Jane",
            "userLastName": "Doe",
            "displayName": "Jane Doe",
            "userTitle": "Product Manager",
            "userCompany": "Acme Inc.",
            "userLinkedIn": "https://www.linkedin.com/in/janedoe",
            "userLocation": "London, UK",
            "userAvatarUrl": "https://cdn.example.com/avatars/jane.png",
            "memberType": "Standard",
            "approvalStatus": "approved",
            "spaces": ["General", "Product"],
            "signUpAt": "2026-01-12T09:31:00.000Z",
            "lastLoginAt": "2026-05-20T14:02:11.000Z",
            "onboardingAt": "2026-01-12T09:45:00.000Z",
            "lifetimePoints": 1200,
            "remainingPoints": 350,
            "questionnaire": {
                "What are your interests?": "Design; Engineering"
            }
        }
    ]
}

Response Fields:

size, number, the number of users returned in this page (i.e. results.length)
pageNumber, number, the page that was returned (echoes pageNum)
pageSize, number, the page size that was applied
results, array, the list of user objects; each item has the same fields as the Get a User by User ID response

Notes:

The response does not include a total count. To page through every user, keep incrementing pageNum until a page returns fewer than pageSize items (or an empty results array).
Some fields may be masked or omitted depending on your tenant's profile field visibility settings.
Returns 400 if a parameter value is invalid (e.g. pageSize > 200, a bad date format, or an unrecognized approvalStatus, memberType, sortBy, or sortDirection).

Get a User by Email

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

HTTP Method: GET

Content type: application/json

Tier: Medium

This is the same endpoint as List Users. Passing an email query parameter switches it into single-user lookup mode — it returns one user object instead of a paginated list.

Query Parameters:

email, string, required, this is the unique identifier to find a user. Special characters must be URL-encoded — for example [email protected] must be sent as user%[email protected]. Unencoded + is decoded as space by the URL parser and will be rejected with a 400 invalid email error.

Response: same as Get a User by User ID

Notes:

Returns 404 if no user is found matching the provided email.

Add a New User

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

HTTP Method: POST

Content type: application/json

Tier: Medium

Request Body Parameters:

email, string, required, this is the unique identifier to find and update user
firstName, string, required
lastName, string, same requirement as in user sign-up form
position, string, required
company, string, required
linkedInUrl, string, optional
pictureUrl, string, optional
spaces, array of strings, optional, spaces names to add user to

Request Body Example:

{
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "company": "Test Company",
    "position": "Software Engineer",
    "linkedInUrl": "",
    "pictureUrl": ""
}

Response Example:

{
    "userEmail": "[email protected]",
    "userFirstName": "Jane",
    "userLastName": "Doe",
    "userTitle": "Software Engineer",
    "userCompany": "Test Company",
    "userLinkedIn": "",
    "pictureUrl": "",
    "userId": "6553ce608b3f645e79d95034",
    "memberType": "Standard",
    "approvalStatus": "approved",
    "displayName": "Jane Doe",
    "spaces": [
        "Space 1",
        "Space 2"
    ],
    "questionnaire": {}
}

Update User Profile by Email

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

HTTP Method: POST

Content type: application/json

Tier: Medium

Request Body Parameters:

email, string, required, this is the unique identifier to find and update user
firstName, string, optional
lastName, string, optional
position, string, optional
company, string, optional
pictureUrl, string, optional
bio, string, optional
linkedInUrl, string, optional
memberType, string (one of "Standard", "Guest", or "Limited Approval"), optional, case-insensitive
approvalStatus, string (one of "approved", "pending", "unapproved"), optional, case-insensitive
[questionId], string, optional, the value should be the answer to the specific user profile question associated with the ID of questionId
- if answer is an array containing multiple values, pass the answer value as a string separated by ; or , (using semicolon is recommended)
- request may include multiple instances of this parameter in the same API call, each with a different questionId
- to get question ids, use the endpoint Get All User Profile Questions

Request Example:

{
    "email": "[email protected]",
    "approvalStatus": "Approved",
    "bio": "This is a test user.",
    "6073c7a2a0295ca1b4d64c22": "Tech leader",
    "6073c7a7a0295ca1b4d64c6b": "Mentor others; Help organize events"
}

Response Example:

{
    "user": {
        "id": "62978aa2f4cc421cf75f1359",
        "email": "[email protected]",
        "firstName": "Jane",
        "lastName": "Doe",
        "position": "Engineer",
        "company": "Test Co.",
        "pictureUrl": "https://abc.cloudfront.net/avatar/7856e6f6d40f.jpeg",
        "bio": "This is a test user.",
        "memberType": "Standard",
        "approvalStatus": "Approved"
    },
    "updatedQuestionAnswers": {
        "Current Level at your organization": "Tech leader",
        "How do you want to contribute?": "Mentor others;Help organize events"
    }
}

Update a User by User ID

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

HTTP Method: PATCH

Content type: application/json

Tier: Medium

Updates a user's profile, addressed by userId instead of email. Use this endpoint when email is not a reliable unique identifier for your users — for example when a user's email address can change in your system.

It accepts the same fields as Update User Profile by Email and returns the same response. Only the fields you include in the request body are changed; anything you omit is left as-is.

Path Parameters:

userId, string, required, the user's unique identifier — the same userId returned by Get a User by User ID

Request Body Parameters:

firstName, string, optional
lastName, string, optional
position, string, optional
company, string, optional
pictureUrl, string, optional
bio, string, optional
linkedInUrl, string, optional
memberType, string (one of "Standard", "Guest", or "Limited Approval"), optional, case-insensitive
approvalStatus, string (one of "approved", "pending", "unapproved"), optional, case-insensitive
[questionId], string, optional, the value should be the answer to the specific user profile question associated with the ID of questionId
- if answer is an array containing multiple values, pass the answer value as a string separated by ; or , (using semicolon is recommended)
- request may include multiple instances of this parameter in the same API call, each with a different questionId
- to get question ids, use the endpoint Get All User Profile Questions

Request Example:

PATCH https://api.gradual-api.com/public-api/v1/users/6553ce608b3f645e79d95034

{
    "approvalStatus": "Approved",
    "bio": "This is a test user.",
    "6073c7a2a0295ca1b4d64c22": "Tech leader",
    "6073c7a7a0295ca1b4d64c6b": "Mentor others; Help organize events"
}

Response Example:

{
    "user": {
        "id": "62978aa2f4cc421cf75f1359",
        "email": "[email protected]",
        "firstName": "Jane",
        "lastName": "Doe",
        "position": "Engineer",
        "company": "Test Co.",
        "pictureUrl": "https://abc.cloudfront.net/avatar/7856e6f6d40f.jpeg",
        "bio": "This is a test user.",
        "memberType": "Standard",
        "approvalStatus": "Approved"
    },
    "updatedQuestionAnswers": {
        "Current Level at your organization": "Tech leader",
        "How do you want to contribute?": "Mentor others;Help organize events"
    }
}

Notes:

Only the fields present in the request body are updated. Omitted fields keep their current values.
Returns 400 with invalid userId if userId is not a valid ID.
Returns 404 with User not found if no user matches userId within your community, including when the user is archived.
Returns 400 if the body is empty, or if it contains a key that is neither a profile field listed above nor a valid profile question id. Note that userId belongs in the URL, not the body — sending it in the body is rejected as an unrecognized parameter.
Updating a Location-type profile question is not supported through this endpoint.
This is the recommended endpoint for profile updates. Update User Profile by Email remains supported for existing integrations.

Delete a User

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

HTTP Method: DELETE

Content type: application/json

Tier: Medium

This endpoint queues a user for deletion. The operation is processed asynchronously — the user will be removed after the request is accepted.

Request Body Parameters:

email, string, optional, must be a valid email address
userId, string, optional, the user's ID

Either email or userId must be provided. If both are provided, email takes priority.

Request Body Example (by email):

{
    "email": "[email protected]"
}

Request Body Example (by userId):

{
    "userId": "6553ce608b3f645e79d95034"
}

Response Example:

{
    "success": true,
    "message": "User deletion request has been queued for processing"
}

Notes:

The deletion is processed asynchronously. A successful response (code 202) means the request has been accepted and queued, not that the user has been deleted yet.
Returns 404 if no user is found matching the provided email or userId.
Returns 400 if neither email nor userId is provided.
Archived users cannot be deleted through this endpoint.

Batch Create Users

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

HTTP Method: POST

Content type: application/json

Tier: Heavy

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

Request Body Parameters:

users, array, required, array of user objects (1–100 items)
users[].email, string, required, must be a valid email address
users[].firstName, string, required
users[].lastName, string, same requirement as in user sign-up form
users[].position, string, required
users[].company, string, required, minimum 2 characters
users[].pictureUrl, string, optional, must be a valid URL
users[].linkedInUrl, string, optional, must be a valid URL

Request Body Example:

{
    "users": [
        {
            "email": "[email protected]",
            "firstName": "Jane",
            "lastName": "Doe",
            "position": "Software Engineer",
            "company": "Test Company",
            "linkedInUrl": "",
            "pictureUrl": ""
        },
        {
            "email": "[email protected]",
            "firstName": "John",
            "lastName": "Smith",
            "position": "Product Manager",
            "company": "Test Company"
        }
    ]
}

Response Example (202 Accepted):

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

Notes:

Duplicate emails within a single batch are rejected with a 400 error.
The maximum batch size is 100 users per request. For larger imports, submit multiple batches sequentially.
Each user in the batch goes through the same validation as the Add a New User endpoint. If any user fails validation, the entire batch is rejected before processing begins.
Poll the Get Batch Job Status endpoint to check the results after submitting.

Get Batch User Creation Job Status

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

HTTP Method: GET

Content type: application/json

Tier: Light

Path Parameters:

jobId, string, required, the job ID returned from the batch creation request

Response Example (job completed):

{
    "jobId": "6553ce608b3f645e79d95034",
    "status": "completed",
    "results": [
        {
            "recordPosition": 0,
            "email": "[email protected]",
            "tenantUserId": "6553ce608b3f645e79d95035",
            "status": "created"
        },
        {
            "recordPosition": 1,
            "email": "[email protected]",
            "tenantUserId": "6553ce608b3f645e79d95036",
            "status": "created"
        }
    ]
}

Response Example (job with partial failures):

{
    "jobId": "6553ce608b3f645e79d95034",
    "status": "completed",
    "results": [
        {
            "recordPosition": 0,
            "email": "[email protected]",
            "tenantUserId": "6553ce608b3f645e79d95035",
            "status": "created"
        },
        {
            "recordPosition": 1,
            "email": "[email protected]",
            "status": "failed",
            "reason": "user already exists"
        }
    ]
}

Job Statuses:

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

Per-User Result Statuses:

created — user was successfully created
failed — user creation failed, see reason field for details

Notes:

Recommended polling interval is every 2–5 seconds.
A completed job does not mean all users were created successfully. Always check the individual results entries for per-user status.
The recordPosition field corresponds to the index of the user in the original users array (starting from 0).

Batch Update Users

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

HTTP Method: POST

Content type: application/json

Tier: Heavy

Bulk variant of Update User Profile by Email. Accepts up to 100 user rows identified by email and applies the same profile/state/answer updates the single-record endpoint supports. The operation is processed asynchronously — you receive a job ID immediately and poll for results.

Request Body Parameters:

users, array, required, array of user rows (1–100 items)
users[].email, string, required, must be a valid email address — the unique identifier used to find each user within your tenant
users[].firstName, string, optional
users[].lastName, string, optional
users[].position, string, optional
users[].company, string, optional
users[].pictureUrl, string, optional, must be a valid URL
users[].linkedInUrl, string, optional, must be a valid URL
users[].bio, string, optional
users[].memberType, string (one of "Standard", "Guest", or "Limited Approval"), optional, case-insensitive
users[].approvalStatus, string (one of "approved", "pending", "unapproved"), optional, case-insensitive
users[].questionAnswers, object, optional, map of profile-question ID → answer text. Every value must be a string. For multi-value answers, separate values with ; (recommended) or ,. Use the Get All User Profile Questions endpoint to discover question IDs.
reason, string, optional, free-form audit note for the batch (e.g. "bot wave 2026-05-27"); stored verbatim on the job record
operatorEmail, string, optional, email of a tenant admin to attribute the batch to in the audit trail; resolved to a user ID server-side. Falls back silently when missing/unresolvable.

Request Body Example:

{
    "users": [
        {
            "email": "[email protected]",
            "approvalStatus": "Unapproved"
        },
        {
            "email": "[email protected]",
            "memberType": "Limited Approval",
            "bio": "Restricted access pending review"
        },
        {
            "email": "[email protected]",
            "firstName": "Kim",
            "lastName": "Lee",
            "questionAnswers": {
                "6073c7a2a0295ca1b4d64c22": "Tech leader",
                "6073c7a7a0295ca1b4d64c6b": "Mentor others;Help organize events"
            }
        }
    ],
    "reason": "bot wave 2026-05-27",
    "operatorEmail": "[email protected]"
}

Response Example (202 Accepted):

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

Notes:

Duplicate emails within a single batch are rejected with a 400 error.
The maximum batch size is 100 users per request. For larger imports, submit multiple batches sequentially.
Each row's keys are validated against the allowed-key set above. Unknown keys (e.g. a typo like firstname) are rejected with a 400 listing every offending row index and its extra keys, so malformed payloads are surfaced immediately instead of being silently dropped.
Each row is processed independently — a single bad row never aborts the rest of the batch. Per-row outcomes appear in the job results (see Get Batch User Update Job Status below).
Poll the Get Batch User Update Job Status endpoint to check the results after submitting.

Get Batch User Update Job Status

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

HTTP Method: GET

Content type: application/json

Tier: Light

Path Parameters:

jobId, string, required, the job ID returned from the batch update request

Response Example (job completed):

{
    "jobId": "6553ce608b3f645e79d95034",
    "status": "completed",
    "results": [
        {
            "recordPosition": 0,
            "email": "[email protected]",
            "tenantUserId": "6553ce608b3f645e79d95040",
            "status": "updated"
        },
        {
            "recordPosition": 1,
            "email": "[email protected]",
            "tenantUserId": "6553ce608b3f645e79d95041",
            "status": "noop"
        },
        {
            "recordPosition": 2,
            "email": "[email protected]",
            "tenantUserId": "6553ce608b3f645e79d95042",
            "status": "updated"
        }
    ]
}

Response Example (job with partial failures):

{
    "jobId": "6553ce608b3f645e79d95034",
    "status": "completed",
    "results": [
        {
            "recordPosition": 0,
            "email": "[email protected]",
            "tenantUserId": "6553ce608b3f645e79d95040",
            "status": "updated"
        },
        {
            "recordPosition": 1,
            "email": "[email protected]",
            "status": "not_found"
        },
        {
            "recordPosition": 2,
            "email": "[email protected]",
            "tenantUserId": "6553ce608b3f645e79d95041",
            "status": "failed",
            "reason": "invalid memberType: not-a-real-type"
        }
    ]
}

Job Statuses:

pending — job is queued and waiting to be processed
processing — job is currently being processed
completed — all rows have been processed (check individual results for per-row status)
failed — job encountered a fatal error before per-row processing (e.g. worker failed to start); see the job's top-level error field

Per-Row Result Statuses:

updated — at least one field was changed on the user
noop — every requested field was already at the target value, no change was written
not_found — no user with that email exists in your tenant
failed — processing this row threw an error, see reason field for details

Notes:

Recommended polling interval is every 2–5 seconds.
A completed job does not mean every row succeeded. Always check the individual results entries for per-row status.
The recordPosition field corresponds to the index of the user in the original users array (starting from 0). Rows are returned in input order regardless of internal processing order.
tenantUserId is present for every row whose user was found in your tenant (i.e. status updated, noop, or failed); it is absent for not_found rows.

Create a Contribution Log

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

HTTP Method: POST

Content type: application/json

Tier: Medium

Request Body Parameters:

contributionName, string, required, name of the contribution (1–300 characters), must match an existing contribution
userEmail, string, required, email of the user to log the contribution for
contributedAt, string, required, ISO 8601 timestamp of when the contribution occurred
count, integer, optional, number of contributions to log (minimum 1, defaults to 1)
externalContributionId, string, optional, an external identifier for deduplication or tracking
notes, string, optional, additional notes (max 100 characters)

Request Body Example:

{
    "contributionName": "Event Organizer",
    "userEmail": "[email protected]",
    "contributedAt": "2024-11-14T10:30:00.000Z",
    "count": 1,
    "externalContributionId": "ext-12345",
    "notes": "Organized the Q4 Town Hall"
}

Response Example:

{
    "contributionLogId": "6553ce608b3f645e79d95034",
    "loggedAt": "2024-11-14T10:30:00.000Z",
    "type": "manual",
    "contribution": "Event Organizer",
    "count": 1,
    "occurredAt": "2024-11-14T10:30:00.000Z",
    "loggedBy": "publicApi",
    "notes": "Organized the Q4 Town Hall",
    "contributorId": "6553ce608b3f645e79d95035",
    "contributorName": "Jane Doe",
    "contributorEmail": "[email protected]"
}

Notes:

The contributionName must exactly match an existing contribution configured in your community. If no matching contribution is found, the request will be rejected with a 400 error.
The user identified by userEmail must exist, otherwise the request will be rejected with a 400 error.
The contributedAt field must be a valid ISO 8601 date string.

Auth

Events