Update Membership
POST https://amplitude.com/api/3/cohorts/membership
Perform incremental update (add / remove) to existing cohort membership.
Request Body
| Parameter | Description |
|---|
cohort_id | Required. String. The ID of an existing cohort. This will update the membership for the specified cohort with the IDs being uploaded in this request. |
count_group | Optional. String. The count group of the given IDs. This must be the same as the cohort’s existing count group. Count_group defaults to User. |
memberships | Required. List of membership json An array of JSON objects identifying IDs to add or remove. |
skip_invalid_ids | Optional. Boolean. Setting this parameter to false ends the request without updating cohort membership if the request contains invalid IDs. Setting skip_invalid_ids to true skips invalid IDs while applying the remaining valid ids. Default is true. |
Request Membership JSON
| Parameter | Description |
|---|
ids | Required. String[]. List of IDs to add or remove. |
id_type | Required. String. The type of ID being sent in the ids field. Valid options are: - BY_ID - BY_NAME For User countgroup, BYID is amplitude ID and BYNAME is user ID. For any other countgroup, BYID is group ID and BYNAME is group name. |
operation | Required. String. The operation to apply on ids field. Valid options are: ADD and REMOVE |
Success Response Fields
| Parameter | Description |
|---|
cohort_id | String. The ID of an existing cohort that the membership information was updated for. |
memberships_result | List of memberships_result json. An array of JSON objects identifying result of membership update (add or remove) operation. |
Response memberships_result JSON
| Parameter | Description |
|---|
skipped_ids | List of strings. List of IDs that were skipped (fail, invalid, etc.) in this membership operation entry. |
id_type | String. The type of ID that was sent for the ids field in this membership operation entry. |
operation | String. The operation that was applied on ids field in this membership operation entry |
Error Response Body
Response body (for non 200 response):
| Parameter | Type | Description |
|---|
error | error json | The detail information of the error |
Response error json:
| Parameter | Description |
|---|
message | String. Describes the error. |
code | Integer. Internal error code. |
metadata | JSON object. For bad request error (400) with invalid id while skip_invalid_ids=false, this field contains the cohort_id and memberships_result (list of membership JSON). The memberships_result’s skipped_ids can help identify which IDs were invalid in which operation. For other errors, this field is not present. |
| Key | Datatype | Required | Description |
|---|
Content-Type | string | | |
RESPONSES
status: OK
"{\n \"cohort_id\": \"COHORT_ID\"\n \"memberships_result\": [\n {\n \"skipped_ids\" : [”222”],\n \"id_type\" : \"BY_ID\",\n \"operation\" : \"ADD\"\n },\n {\n \"skipped_ids\" : [],\n \"id_type\" : \"BY_ID\",\n \"operation\" : \"REMOVE\"\n },\n {\n \"skipped_ids\" : [\"asd\",”qwe”],\n \"id_type\" : \"BY_NAME\",\n \"operation\" : \"ADD\"\n }\n ]\n}"