{ "openapi" : "3.0.1", "info" : { "title" : "CRM Lists", "description" : "CRUD operations to manage lists and list memberships", "version" : "v3", "x-hubspot-product-tier-requirements" : { "marketing" : "FREE", "sales" : "FREE", "service" : "FREE", "cms" : "FREE", "commerce" : "FREE", "crmHub" : "FREE", "dataHub" : "FREE" }, "x-hubspot-related-documentation" : [ { "name" : "Lists Guide", "url" : "https://developers.hubspot.com/docs/guides/api/crm/lists/overview" } ] }, "servers" : [ { "url" : "https://api.hubapi.com" } ], "tags" : [ { "name" : "Basic" }, { "name" : "Batch" }, { "name" : "Search" } ], "paths" : { "/crm/v3/lists" : { "get" : { "tags" : [ "Basic" ], "operationId" : "get-/crm/v3/lists_/crm/v3/lists", "parameters" : [ { "name" : "includeFilters", "in" : "query", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "boolean", "example" : null, "default" : false } }, { "name" : "listIds", "in" : "query", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListsByIdResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.lists.read" ] } ] }, "post" : { "tags" : [ "Basic" ], "operationId" : "post-/crm/v3/lists_/crm/v3/lists", "parameters" : [ ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListCreateRequest" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListCreateResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.lists.write" ] }, { "oauth2" : [ "cms.membership.access_groups.write" ] } ] } }, "/crm/v3/lists/folders" : { "get" : { "tags" : [ "Basic" ], "summary" : "Retrieves a folder.", "description" : "Retrieves a folder and recursively includes all folders via the childNodes attribute. The child lists field will be empty in all child nodes. Only the folder retrieved will include the child lists in that folder.", "operationId" : "get-/crm/v3/lists/folders_/crm/v3/lists/folders", "parameters" : [ { "name" : "folderId", "in" : "query", "description" : "The Id of the folder to retrieve.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "string", "example" : null, "default" : "0" } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListFolderFetchResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.lists.read" ] } ] }, "post" : { "tags" : [ "Basic" ], "summary" : "Creates a folder", "description" : "Creates a folder with the given information.", "operationId" : "post-/crm/v3/lists/folders_/crm/v3/lists/folders", "parameters" : [ ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListFolderCreateRequest" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListFolderCreateResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] } }, "/crm/v3/lists/folders/move-list" : { "put" : { "tags" : [ "Basic" ], "summary" : "Moves a list to a given folder", "description" : "Given a list and a folder, the list will be moved to that folder.", "operationId" : "put-/crm/v3/lists/folders/move-list_/crm/v3/lists/folders/move-list", "parameters" : [ ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListMoveRequest" }, "example" : null } }, "required" : true }, "responses" : { "204" : { "description" : "No content", "content" : { } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] } }, "/crm/v3/lists/folders/{folderId}" : { "delete" : { "tags" : [ "Basic" ], "summary" : "Deletes a folder", "description" : "Deletes the folder with the given Id.", "operationId" : "delete-/crm/v3/lists/folders/{folderId}_/crm/v3/lists/folders/{folderId}", "parameters" : [ { "name" : "folderId", "in" : "path", "description" : "The ID of the folder to delete", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "204" : { "description" : "No content", "content" : { } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] } }, "/crm/v3/lists/folders/{folderId}/move/{newParentFolderId}" : { "put" : { "tags" : [ "Basic" ], "summary" : "Moves a folder", "description" : "This moves the folder from its current location to a new location. It updates the parent of this folder to the new Id given.", "operationId" : "put-/crm/v3/lists/folders/{folderId}/move/{newParentFolderId}_/crm/v3/lists/folders/{folderId}/move/{newParentFolderId}", "parameters" : [ { "name" : "folderId", "in" : "path", "description" : "The ID of the folder to move", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } }, { "name" : "newParentFolderId", "in" : "path", "description" : "The ID for the target parent folder.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListFolderFetchResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] } }, "/crm/v3/lists/folders/{folderId}/rename" : { "put" : { "tags" : [ "Basic" ], "summary" : "Rename a folder", "description" : "Renames the given folderId with a new name.", "operationId" : "put-/crm/v3/lists/folders/{folderId}/rename_/crm/v3/lists/folders/{folderId}/rename", "parameters" : [ { "name" : "folderId", "in" : "path", "description" : "The ID of the folder to rename", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } }, { "name" : "newFolderName", "in" : "query", "description" : "The new name of the folder.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListFolderFetchResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] } }, "/crm/v3/lists/idmapping" : { "get" : { "tags" : [ "Basic" ], "summary" : "Translate Legacy List Id to Modern List Id", "description" : "This API allows translation of legacy list id to list id. This is a temporary API allowed for mapping old id's to new id's and will expire on May 30th, 2025.", "operationId" : "get-/crm/v3/lists/idmapping_/crm/v3/lists/idmapping", "parameters" : [ { "name" : "legacyListId", "in" : "query", "description" : "The legacy list id from lists v1 API.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PublicMigrationMapping" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.lists.read" ] } ] }, "post" : { "tags" : [ "Basic" ], "summary" : "Translate Legacy List Id to Modern List Id in Batch", "description" : "This API allows translation of a batch of legacy list id's to list id's. This allows for a maximum of 10,000 id's. This is a temporary API allowed for mapping old id's to new id's and will expire on May 30th, 2025.", "operationId" : "post-/crm/v3/lists/idmapping_/crm/v3/lists/idmapping", "parameters" : [ ], "requestBody" : { "content" : { "application/json" : { "schema" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PublicBatchMigrationMapping" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.lists.read" ] } ] } }, "/crm/v3/lists/object-type-id/{objectTypeId}/name/{listName}" : { "get" : { "tags" : [ "Basic" ], "summary" : "Retrieve List by Name", "description" : "Retrieve a specific list by its name and object type ID. This endpoint allows you to fetch details about a list, including its properties and optionally its filters. It is useful for accessing list information based on specific criteria.", "operationId" : "get-/crm/v3/lists/object-type-id/{objectTypeId}/name/{listName}_/crm/v3/lists/object-type-id/{objectTypeId}/name/{listName}", "parameters" : [ { "name" : "listName", "in" : "path", "description" : "The name of the list to fetch. This is **not** case sensitive.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } }, { "name" : "objectTypeId", "in" : "path", "description" : "The object type ID of the object types stored by the list to fetch. For example, `0-1` for a `CONTACT` list.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } }, { "name" : "includeFilters", "in" : "query", "description" : "A flag indicating whether or not the response object list definition should include a filter branch definition. By default, object list definitions will not have their filter branch definitions included in the response.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "boolean", "example" : null, "default" : false } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListFetchResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.lists.read" ] } ] } }, "/crm/v3/lists/records/memberships/batch/read" : { "post" : { "tags" : [ "Batch" ], "operationId" : "post-/crm/v3/lists/records/memberships/batch/read_/crm/v3/lists/records/memberships/batch/read", "parameters" : [ ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BatchInputRecordIdInput" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BatchResponseRecordIdWithMemberships" }, "example" : null } } }, "207" : { "description" : "multiple statuses", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BatchResponseRecordIdWithMembershipsWithErrors" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.lists.read" ] } ] } }, "/crm/v3/lists/records/{objectTypeId}/{recordId}/memberships" : { "get" : { "tags" : [ "Basic" ], "summary" : "Get lists record is member of", "description" : "For given record provide lists this record is member of.", "operationId" : "get-/crm/v3/lists/records/{objectTypeId}/{recordId}/memberships_/crm/v3/lists/records/{objectTypeId}/{recordId}/memberships", "parameters" : [ { "name" : "objectTypeId", "in" : "path", "description" : "Object type id of the record", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } }, { "name" : "recordId", "in" : "path", "description" : "Id of the record", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ApiCollectionResponseRecordListMembership" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.lists.read" ] } ] } }, "/crm/v3/lists/search" : { "post" : { "tags" : [ "Search" ], "summary" : "Search Lists", "description" : "Search lists by list name or page through all lists by providing an empty `query` value.", "operationId" : "post-/crm/v3/lists/search_/crm/v3/lists/search", "parameters" : [ ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListSearchRequest" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListSearchResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.lists.read" ] } ] } }, "/crm/v3/lists/{listId}" : { "get" : { "tags" : [ "Basic" ], "summary" : "Fetch List by ID", "description" : "Fetch a single list by **ILS list ID**.", "operationId" : "get-/crm/v3/lists/{listId}_/crm/v3/lists/{listId}", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "The **ILS ID** of the list to fetch.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } }, { "name" : "includeFilters", "in" : "query", "description" : "A flag indicating whether or not the response object list definition should include a filter branch definition. By default, object list definitions will not have their filter branch definitions included in the response.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "boolean", "example" : null, "default" : false } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListFetchResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.lists.read" ] } ] }, "delete" : { "tags" : [ "Basic" ], "summary" : "Delete a List", "description" : "Delete a list by **ILS list ID**. Lists deleted through this endpoint can be restored up to 90-days following the delete. After 90-days, the list is purged and can no longer be restored.", "operationId" : "delete-/crm/v3/lists/{listId}_/crm/v3/lists/{listId}", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "The **ILS ID** of the list to delete.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "204" : { "description" : "No content", "content" : { } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] } }, "/crm/v3/lists/{listId}/memberships" : { "get" : { "tags" : [ "Basic" ], "summary" : "Fetch List Memberships Ordered by ID", "description" : "Fetch the memberships of a list in order sorted by the `recordId` of the records in the list.\n\nThe `recordId`s are sorted in *ascending* order if an `after` offset or no offset is provided. If only a `before` offset is provided, then the records are sorted in *descending* order.\n\nThe `after` offset parameter will take precedence over the `before` offset in a case where both are provided.", "operationId" : "get-/crm/v3/lists/{listId}/memberships_/crm/v3/lists/{listId}/memberships", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "The **ILS ID** of the list.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } }, { "name" : "after", "in" : "query", "description" : "The paging offset token for the page that comes `after` the previously requested records.\n\nIf provided, then the records in the response will be the records following the offset, sorted in *ascending* order. Takes precedence over the `before` offset.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "string", "example" : null } }, { "name" : "before", "in" : "query", "description" : "The paging offset token for the page that comes `before` the previously requested records.\n\nIf provided, then the records in the response will be the records preceding the offset, sorted in *descending* order.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "string", "example" : null } }, { "name" : "limit", "in" : "query", "description" : "The number of records to return in the response. The maximum `limit` is 250.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "integer", "format" : "int32", "example" : null, "default" : 100 } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ApiCollectionResponseJoinTimeAndRecordId" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.lists.read" ] } ] }, "delete" : { "tags" : [ "Basic" ], "summary" : "Delete All Records from a List", "description" : "Remove **all** of the records from a list. ***Note:*** *The list is not deleted.*\n\nThis endpoint only works for lists that have a `processingType` of `MANUAL` or `SNAPSHOT`.\n\nThis endpoint only supports lists that have less than 100,000 memberships.", "operationId" : "delete-/crm/v3/lists/{listId}/memberships_/crm/v3/lists/{listId}/memberships", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "The **ILS ID** of the `MANUAL` or `SNAPSHOT` list.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "204" : { "description" : "No content", "content" : { } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] } }, "/crm/v3/lists/{listId}/memberships/add" : { "put" : { "tags" : [ "Basic" ], "summary" : "Add Records to a List", "description" : "Add the records provided to the list. Records that do not exist or that are already members of the list are ignored.\n\nThis endpoint only works for lists that have a `processingType` of `MANUAL` or `SNAPSHOT`.", "operationId" : "put-/crm/v3/lists/{listId}/memberships/add_/crm/v3/lists/{listId}/memberships/add", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "The **ILS ID** of the `MANUAL` or `SNAPSHOT` list.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/MembershipsUpdateResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] } }, "/crm/v3/lists/{listId}/memberships/add-and-remove" : { "put" : { "tags" : [ "Basic" ], "summary" : "Add and/or Remove Records from a List", "description" : "Add and/or remove records that have already been created in the system to and/or from a list.\n\nThis endpoint only works for lists that have a `processingType` of `MANUAL` or `SNAPSHOT`.", "operationId" : "put-/crm/v3/lists/{listId}/memberships/add-and-remove_/crm/v3/lists/{listId}/memberships/add-and-remove", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "The **ILS ID** of the `MANUAL` or `SNAPSHOT` list.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/MembershipChangeRequest" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/MembershipsUpdateResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] } }, "/crm/v3/lists/{listId}/memberships/add-from/{sourceListId}" : { "put" : { "tags" : [ "Basic" ], "summary" : "Add All Records from a Source List to a Destination List", "description" : "Add all of the records from a *source list* (specified by the `sourceListId`) to a *destination list* (specified by the `listId`). Records that are already members of the *destination list* will be ignored. The *destination* and *source list* IDs must be different. The *destination* and *source lists* must contain records of the same type (e.g. contacts, companies, etc.).\n\nThis endpoint only works for *destination lists* that have a `processingType` of `MANUAL` or `SNAPSHOT`. The *source list* can have any `processingType`.\n\nThis endpoint only supports a `sourceListId` for lists with less than 100,000 memberships.", "operationId" : "put-/crm/v3/lists/{listId}/memberships/add-from/{sourceListId}_/crm/v3/lists/{listId}/memberships/add-from/{sourceListId}", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "The **ILS ID** of the `MANUAL` or `SNAPSHOT` *destination list*, which the *source list* records are added to.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } }, { "name" : "sourceListId", "in" : "path", "description" : "The **ILS ID** of the *source list* to grab the records from, which are then added to the *destination list*.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "204" : { "description" : "No content", "content" : { } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] } }, "/crm/v3/lists/{listId}/memberships/join-order" : { "get" : { "tags" : [ "Basic" ], "summary" : "Fetch List Memberships Ordered by Added to List Date", "description" : "Fetch the memberships of a list in order sorted by the time the records were added to the list.\n\nThe `recordId`s are sorted in *ascending* order if an `after` offset or no offset is provided. If only a `before` offset is provided, then the records are sorted in *descending* order.\n\nThe `after` offset parameter will take precedence over the `before` offset in a case where both are provided.", "operationId" : "get-/crm/v3/lists/{listId}/memberships/join-order_/crm/v3/lists/{listId}/memberships/join-order", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "The **ILS ID** of the list.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } }, { "name" : "after", "in" : "query", "description" : "The paging offset token for the page that comes `after` the previously requested records.\n\nIf provided, then the records in the response will be the records following the offset, sorted in *ascending* order. Takes precedence over the `before` offset.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "string", "example" : null } }, { "name" : "before", "in" : "query", "description" : "The paging offset token for the page that comes `before` the previously requested records.\n\nIf provided, then the records in the response will be the records preceding the offset, sorted in *descending* order.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "string", "example" : null } }, { "name" : "limit", "in" : "query", "description" : "The number of records to return in the response. The maximum `limit` is 250.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "integer", "format" : "int32", "example" : null, "default" : 100 } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ApiCollectionResponseJoinTimeAndRecordId" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.lists.read" ] } ] } }, "/crm/v3/lists/{listId}/memberships/remove" : { "put" : { "tags" : [ "Basic" ], "summary" : "Remove Records from a List", "description" : "Remove the records provided from the list. Records that do not exist or that are not members of the list are ignored.\n\nThis endpoint only works for lists that have a `processingType` of `MANUAL` or `SNAPSHOT`.", "operationId" : "put-/crm/v3/lists/{listId}/memberships/remove_/crm/v3/lists/{listId}/memberships/remove", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "The **ILS ID** of the `MANUAL` or `SNAPSHOT` list.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/MembershipsUpdateResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] } }, "/crm/v3/lists/{listId}/restore" : { "put" : { "tags" : [ "Basic" ], "summary" : "Restore a List", "description" : "Restore a previously deleted list by **ILS list ID**. Deleted lists are eligible to be restored up-to 90-days after the list has been deleted.", "operationId" : "put-/crm/v3/lists/{listId}/restore_/crm/v3/lists/{listId}/restore", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "The **ILS ID** of the list to restore.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "204" : { "description" : "No content", "content" : { } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] } }, "/crm/v3/lists/{listId}/schedule-conversion" : { "get" : { "tags" : [ "Basic" ], "summary" : "Retrieve the conversion details for a list", "description" : "Retrieve the conversion details for a list. This can be used to check for an upcoming conversion, or to get the details of when a list was already converted.", "operationId" : "get-/crm/v3/lists/{listId}/schedule-conversion_/crm/v3/lists/{listId}/schedule-conversion", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "The ID of the list to schedule the conversion for.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PublicListConversionResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.lists.read" ] } ] }, "put" : { "tags" : [ "Basic" ], "summary" : "Schedule or update the conversion of a list to static", "description" : "Schedule the conversion of an active list into a static list, or update the already scheduled conversion. This can be scheduled for a specific date or based on activity.", "operationId" : "put-/crm/v3/lists/{listId}/schedule-conversion_/crm/v3/lists/{listId}/schedule-conversion", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "The ID of the list to schedule the conversion for.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PublicListConversionTime" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PublicListConversionResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] }, "delete" : { "tags" : [ "Basic" ], "summary" : "Cancel the conversion of a list", "description" : "Delete an existing scheduled conversion for a list.", "operationId" : "delete-/crm/v3/lists/{listId}/schedule-conversion_/crm/v3/lists/{listId}/schedule-conversion", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "The ID of the list that you want to cancel the conversion for.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "204" : { "description" : "No content", "content" : { } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] } }, "/crm/v3/lists/{listId}/size-and-edits-history/between" : { "get" : { "tags" : [ "Basic" ], "operationId" : "get-/crm/v3/lists/{listId}/size-and-edits-history/between_/crm/v3/lists/{listId}/size-and-edits-history/between", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } }, { "name" : "endDate", "in" : "query", "description" : "", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "string", "format" : "date-time", "example" : null } }, { "name" : "startDate", "in" : "query", "description" : "", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "string", "format" : "date-time", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListSizeAndEditHistoryResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.lists.read" ] } ] } }, "/crm/v3/lists/{listId}/update-list-filters" : { "put" : { "tags" : [ "Basic" ], "summary" : "Update List Filter Definition", "description" : "Update the filter branch definition of a `DYNAMIC` list. Once updated, the list memberships will be re-evaluated and updated to match the new definition.", "operationId" : "put-/crm/v3/lists/{listId}/update-list-filters_/crm/v3/lists/{listId}/update-list-filters", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "The **ILS ID** of the list to update.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } }, { "name" : "enrollObjectsInWorkflows", "in" : "query", "description" : "A flag indicating whether or not the memberships added to the list as a result of the filter change should be enrolled in workflows that are relevant to this list.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "boolean", "example" : null, "default" : false } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListFilterUpdateRequest" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListUpdateResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] } }, "/crm/v3/lists/{listId}/update-list-name" : { "put" : { "tags" : [ "Basic" ], "summary" : "Update List Name", "description" : "Update the name of a list. The name must be globally unique relative to all other public lists in the portal.", "operationId" : "put-/crm/v3/lists/{listId}/update-list-name_/crm/v3/lists/{listId}/update-list-name", "parameters" : [ { "name" : "listId", "in" : "path", "description" : "The **ILS ID** of the list to update.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } }, { "name" : "includeFilters", "in" : "query", "description" : "A flag indicating whether or not the response object list definition should include a filter branch definition. By default, object list definitions will not have their filter branch definitions included in the response.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "boolean", "example" : null, "default" : false } }, { "name" : "listName", "in" : "query", "description" : "The name to update the list to.", "required" : false, "style" : "form", "explode" : true, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ListUpdateResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "cms.membership.access_groups.write", "crm.lists.read" ] }, { "oauth2" : [ "crm.lists.read", "crm.lists.write" ] } ] } } }, "components" : { "schemas" : { "ApiCollectionResponseJoinTimeAndRecordId" : { "required" : [ "results" ], "type" : "object", "properties" : { "paging" : { "$ref" : "#/components/schemas/Paging" }, "results" : { "type" : "array", "example" : null, "items" : { "$ref" : "#/components/schemas/JoinTimeAndRecordId" } }, "total" : { "type" : "integer", "description" : "The total number of records that match the query.", "format" : "int64", "example" : null } }, "example" : null }, "ApiCollectionResponseRecordListMembership" : { "required" : [ "results" ], "type" : "object", "properties" : { "paging" : { "$ref" : "#/components/schemas/Paging" }, "results" : { "type" : "array", "example" : null, "items" : { "$ref" : "#/components/schemas/RecordListMembership" } }, "total" : { "type" : "integer", "format" : "int64", "example" : null } }, "example" : null }, "BatchInputRecordIdInput" : { "required" : [ "inputs" ], "type" : "object", "properties" : { "inputs" : { "type" : "array", "example" : null, "items" : { "$ref" : "#/components/schemas/RecordIdInput" } } }, "example" : null }, "BatchResponseRecordIdWithMemberships" : { "required" : [ "completedAt", "results", "startedAt", "status" ], "type" : "object", "properties" : { "completedAt" : { "type" : "string", "format" : "date-time", "example" : null }, "links" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "example" : null }, "requestedAt" : { "type" : "string", "format" : "date-time", "example" : null }, "results" : { "type" : "array", "example" : null, "items" : { "$ref" : "#/components/schemas/RecordIdWithMemberships" } }, "startedAt" : { "type" : "string", "format" : "date-time", "example" : null }, "status" : { "type" : "string", "example" : null, "enum" : [ "CANCELED", "COMPLETE", "PENDING", "PROCESSING" ] } }, "example" : null }, "BatchResponseRecordIdWithMembershipsWithErrors" : { "required" : [ "completedAt", "results", "startedAt", "status" ], "type" : "object", "properties" : { "completedAt" : { "type" : "string", "format" : "date-time", "example" : null }, "errors" : { "type" : "array", "example" : null, "items" : { "$ref" : "#/components/schemas/StandardError" } }, "links" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "example" : null }, "numErrors" : { "type" : "integer", "format" : "int32", "example" : null }, "requestedAt" : { "type" : "string", "format" : "date-time", "example" : null }, "results" : { "type" : "array", "example" : null, "items" : { "$ref" : "#/components/schemas/RecordIdWithMemberships" } }, "startedAt" : { "type" : "string", "format" : "date-time", "example" : null }, "status" : { "type" : "string", "example" : null, "enum" : [ "CANCELED", "COMPLETE", "PENDING", "PROCESSING" ] } }, "example" : null }, "Error" : { "required" : [ "category", "correlationId", "message" ], "type" : "object", "properties" : { "category" : { "type" : "string", "description" : "The error category", "example" : null }, "context" : { "type" : "object", "additionalProperties" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "description" : "Context about the error condition", "example" : "{invalidPropertyName=[propertyValue], missingScopes=[scope1, scope2]}" }, "correlationId" : { "type" : "string", "description" : "A unique identifier for the request. Include this value with any error reports or support tickets", "format" : "uuid", "example" : "aeb5f871-7f07-4993-9211-075dc63e7cbf" }, "errors" : { "type" : "array", "description" : "further information about the error", "example" : null, "items" : { "$ref" : "#/components/schemas/ErrorDetail" } }, "links" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "A map of link names to associated URIs containing documentation about the error or recommended remediation steps", "example" : null }, "message" : { "type" : "string", "description" : "A human readable message describing the error along with remediation steps where appropriate", "example" : "An error occurred" }, "subCategory" : { "type" : "string", "description" : "A specific category that contains more specific detail about the error", "example" : null } }, "example" : { "message" : "Invalid input (details will vary based on the error)", "correlationId" : "aeb5f871-7f07-4993-9211-075dc63e7cbf", "category" : "VALIDATION_ERROR", "links" : { "knowledge-base" : "https://www.hubspot.com/products/service/knowledge-base" } } }, "ErrorDetail" : { "required" : [ "message" ], "type" : "object", "properties" : { "code" : { "type" : "string", "description" : "The status code associated with the error detail", "example" : null }, "context" : { "type" : "object", "additionalProperties" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "description" : "Context about the error condition", "example" : "{missingScopes=[scope1, scope2]}" }, "in" : { "type" : "string", "description" : "The name of the field or parameter in which the error was found.", "example" : null }, "message" : { "type" : "string", "description" : "A human readable message describing the error along with remediation steps where appropriate", "example" : null }, "subCategory" : { "type" : "string", "description" : "A specific category that contains more specific detail about the error", "example" : null } }, "example" : null }, "JoinTimeAndRecordId" : { "required" : [ "membershipTimestamp", "recordId" ], "type" : "object", "properties" : { "membershipTimestamp" : { "type" : "string", "description" : "The date and time when the record was added to the list.", "format" : "date-time", "example" : null }, "recordId" : { "type" : "string", "description" : "The unique identifier of the record.", "example" : null } }, "example" : null }, "ListCreateRequest" : { "required" : [ "name", "objectTypeId", "processingType" ], "type" : "object", "properties" : { "customProperties" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "The list of custom properties to tie to the list. Custom property name is the key, the value is the value.", "example" : null }, "filterBranch" : { "$ref" : "#/components/schemas/PublicFilterBranchIF" }, "listFolderId" : { "type" : "integer", "description" : "The ID of the folder that the list should be created in. If left blank, then the list will be created in the root of the list folder structure.", "format" : "int32", "example" : null }, "listPermissions" : { "$ref" : "#/components/schemas/PublicListPermissions" }, "membershipSettings" : { "$ref" : "#/components/schemas/PublicMembershipSettings" }, "name" : { "type" : "string", "description" : "The name of the list, which must be globally unique across all public lists in the portal.", "example" : null }, "objectTypeId" : { "type" : "string", "description" : "The object type ID of the type of objects that the list will store.", "example" : null }, "processingType" : { "type" : "string", "description" : "The processing type of the list. One of: `SNAPSHOT`, `MANUAL`, or `DYNAMIC`.", "example" : null } }, "description" : "The request object used when creating a new object list.", "example" : { "filterBranch" : { "filterBranchType" : "OR", "filterBranches" : [ { "filterBranchType" : "AND", "filterBranches" : [ { "associationCategory" : "HUBSPOT_DEFINED", "associationTypeId" : 4, "filterBranchType" : "ASSOCIATION", "filters" : [ { "filterType" : "PROPERTY", "operation" : { "operationType" : "BOOL", "operator" : "IS_EQUAL_TO", "value" : true }, "property" : "hs_is_closed_won" } ], "objectTypeId" : "0-3", "operator" : "IN_LIST" } ], "filters" : [ { "filterType" : "PROPERTY", "operation" : { "operationType" : "MULTISTRING", "operator" : "IS_EQUAL_TO", "values" : [ "test", "name" ] }, "property" : "firstname" } ] } ] }, "name" : "Dynamic Association List Example", "objectTypeId" : "0-1", "processingType" : "DYNAMIC" } }, "ListCreateResponse" : { "required" : [ "list" ], "type" : "object", "properties" : { "list" : { "$ref" : "#/components/schemas/PublicObjectList" } }, "description" : "The response for a list create request.", "example" : { "list" : { "createdAt" : "2023-11-15T18:16:52.165Z", "createdById" : "123", "filterBranch" : { "filterBranchOperator" : "OR", "filterBranchType" : "OR", "filterBranches" : [ { "filterBranchOperator" : "AND", "filterBranchType" : "AND", "filterBranches" : [ { "associationCategory" : "HUBSPOT_DEFINED", "associationTypeId" : 4, "filterBranchOperator" : "AND", "filterBranchType" : "ASSOCIATION", "filters" : [ { "filterType" : "PROPERTY", "operation" : { "includeObjectsWithNoValueSet" : false, "operationType" : "BOOL", "operator" : "IS_EQUAL_TO", "value" : true }, "property" : "hs_is_closed_won" } ], "objectTypeId" : "0-3", "operator" : "IN_LIST" } ], "filters" : [ { "filterType" : "PROPERTY", "operation" : { "includeObjectsWithNoValueSet" : false, "operationType" : "MULTISTRING", "operator" : "IS_EQUAL_TO", "values" : [ "test", "name" ] }, "property" : "firstname" } ] } ] }, "filtersUpdatedAt" : "2023-11-15T18:16:52.165Z", "listId" : "1", "listVersion" : 1, "name" : "Dynamic Association List Example", "objectTypeId" : "0-1", "processingStatus" : "PROCESSING", "processingType" : "DYNAMIC", "updatedAt" : "2023-11-15T18:16:52.395Z", "updatedById" : "123" } } }, "ListFetchResponse" : { "required" : [ "list" ], "type" : "object", "properties" : { "list" : { "$ref" : "#/components/schemas/PublicObjectList" } }, "description" : "The response for a list fetch request.", "example" : null }, "ListFilterUpdateRequest" : { "required" : [ "filterBranch" ], "type" : "object", "properties" : { "filterBranch" : { "$ref" : "#/components/schemas/PublicFilterBranchIF" } }, "description" : "The definition of the list filter branch update request.", "example" : { "filterBranch" : { "filterBranchType" : "OR", "filterBranches" : [ { "filterBranchType" : "AND", "filters" : [ { "filterType" : "PROPERTY", "operation" : { "operationType" : "NUMBER", "operator" : "IS_GREATER_THAN_OR_EQUAL_TO", "value" : 12 }, "property" : "hs_predictivecontactscore_v2" }, { "filterType" : "PROPERTY", "operation" : { "operationType" : "ALL_PROPERTY", "operator" : "IS_UNKNOWN" }, "property" : "engagements_last_meeting_booked_source" }, { "acceptedStatuses" : [ "OPT_IN" ], "filterType" : "EMAIL_SUBSCRIPTION", "subscriptionIds" : [ "81537745", "321981152" ] } ] } ] } } }, "ListFolderCreateRequest" : { "required" : [ "name" ], "type" : "object", "properties" : { "name" : { "type" : "string", "description" : "The name of the folder to be created.", "example" : null }, "parentFolderId" : { "type" : "string", "description" : "The folder this should be created in, if not specified will be created in the root folder 0.", "example" : null } }, "example" : null }, "ListFolderCreateResponse" : { "required" : [ "folder" ], "type" : "object", "properties" : { "folder" : { "$ref" : "#/components/schemas/PublicListFolder" } }, "example" : null }, "ListFolderFetchResponse" : { "required" : [ "folder" ], "type" : "object", "properties" : { "folder" : { "$ref" : "#/components/schemas/PublicListFolder" } }, "example" : null }, "ListMoveRequest" : { "required" : [ "listId", "newFolderId" ], "type" : "object", "properties" : { "listId" : { "type" : "string", "description" : "The Id of the list to move.", "example" : null }, "newFolderId" : { "type" : "string", "description" : "The Id of folder to move the list to, the root folder is Id 0.", "example" : null } }, "example" : null }, "ListSearchRequest" : { "required" : [ "additionalProperties", "offset" ], "type" : "object", "properties" : { "additionalProperties" : { "uniqueItems" : true, "type" : "array", "description" : "The property names of any additional list properties to include in the response. Properties that do not exist or that are empty for a particular list are not included in the response.\n\nBy default, all requests will fetch the following properties for each list: `hs_list_size`, `hs_last_record_added_at`, `hs_last_record_removed_at`, `hs_folder_name`, and `hs_list_reference_count`.", "example" : null, "items" : { "type" : "string", "example" : null } }, "count" : { "type" : "integer", "description" : "The number of lists to include in the response. Defaults to `20` if no value is provided. The max `count` is `500`.", "format" : "int32", "example" : null }, "listIds" : { "uniqueItems" : true, "type" : "array", "description" : "ILS list ids to be included in search results. If not specified, all lists matching other criteria will be included", "example" : null, "items" : { "type" : "string", "example" : null } }, "objectTypeId" : { "$ref" : "#/components/schemas/ObjectTypeId" }, "offset" : { "type" : "integer", "description" : "Value used to paginate through lists. The `offset` provided in the response can be used in the next request to fetch the next page of results. Defaults to `0` if no offset is provided.", "format" : "int32", "example" : null }, "processingTypes" : { "uniqueItems" : true, "type" : "array", "description" : "List processing types to be included in search results. If not specified, all lists with all processing types will be included.", "example" : null, "items" : { "type" : "string", "example" : null } }, "query" : { "type" : "string", "description" : "The `query` that will be used to search for lists by list name. If no `query` is provided, then the results will include all lists.", "example" : null }, "sort" : { "$ref" : "#/components/schemas/SortField" } }, "description" : "The request object used for searching through lists.", "example" : { "additionalProperties" : [ "hs_list_size_week_delta" ], "count" : 100, "offset" : 0, "query" : "Test" } }, "ListSearchResponse" : { "required" : [ "hasMore", "lists", "offset", "total" ], "type" : "object", "properties" : { "hasMore" : { "type" : "boolean", "description" : "Whether or not there are more results to page through.", "example" : null }, "lists" : { "type" : "array", "description" : "The lists that matched the search criteria.", "example" : null, "items" : { "$ref" : "#/components/schemas/PublicObjectListSearchResult" } }, "offset" : { "type" : "integer", "description" : "Value to be passed in a future request to paginate through list search results.", "format" : "int32", "example" : null }, "total" : { "type" : "integer", "description" : "The total number of lists that match the search criteria.", "format" : "int32", "example" : null } }, "description" : "The response object with the list search hits and additional information regarding pagination.", "example" : { "hasMore" : false, "lists" : [ { "additionalProperties" : { "hs_last_record_added_at" : "1695938616824", "hs_list_reference_count" : "0", "hs_list_size" : "59", "hs_list_size_week_delta" : "-10" }, "createdAt" : "2023-09-28T22:03:17.998Z", "createdById" : "1", "filtersUpdatedAt" : "2023-09-28T22:03:17.998Z", "listId" : "123", "listVersion" : 1, "name" : "Test list", "objectTypeId" : "0-1", "processingStatus" : "COMPLETE", "processingType" : "SNAPSHOT", "updatedAt" : "2023-09-28T22:03:37.005Z", "updatedById" : "1" } ], "offset" : 1, "total" : 1 } }, "ListSizeAndEditHistoryResponse" : { "required" : [ "editHistory", "sizeHistory" ], "type" : "object", "properties" : { "editHistory" : { "type" : "array", "example" : null, "items" : { "type" : "string", "format" : "date-time", "example" : null } }, "sizeHistory" : { "type" : "array", "example" : null, "items" : { "$ref" : "#/components/schemas/ListSizeDataPoint" } } }, "example" : null }, "ListSizeDataPoint" : { "required" : [ "size", "timestamp" ], "type" : "object", "properties" : { "size" : { "type" : "integer", "format" : "int64", "example" : null }, "timestamp" : { "type" : "string", "format" : "date-time", "example" : null } }, "example" : null }, "ListUpdateResponse" : { "type" : "object", "properties" : { "updatedList" : { "$ref" : "#/components/schemas/PublicObjectList" } }, "description" : "The updated definition of the list in response to a list update request.", "example" : null }, "ListsByIdResponse" : { "required" : [ "lists" ], "type" : "object", "properties" : { "lists" : { "type" : "array", "description" : "The object list definitions.", "example" : null, "items" : { "$ref" : "#/components/schemas/PublicObjectList" } } }, "description" : "The response object containing the lists found for a multi-list fetch.", "example" : null }, "MembershipChangeRequest" : { "required" : [ "recordIdsToAdd", "recordIdsToRemove" ], "type" : "object", "properties" : { "recordIdsToAdd" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "recordIdsToRemove" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } } }, "description" : "The IDs of the records to add and/or remove from a list.", "example" : { "recordIdsToAdd" : [ "123", "456", "789" ], "recordIdsToRemove" : [ "654" ] } }, "MembershipsUpdateResponse" : { "required" : [ "recordIdsMissing", "recordIdsRemoved", "recordsIdsAdded" ], "type" : "object", "properties" : { "recordIdsMissing" : { "type" : "array", "description" : "The IDs of the records that were `missing` (e.g. did not exist in the portal) and so were not `added` or `removed`.", "example" : null, "items" : { "type" : "string", "example" : null } }, "recordIdsRemoved" : { "type" : "array", "description" : "The IDs of the records that were `removed` from the list.", "example" : null, "items" : { "type" : "string", "example" : null } }, "recordsIdsAdded" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } } }, "description" : "The IDs of the records that were `added`, `removed`, and/or found to be `missing` as a result of the \nmembership update request.", "example" : null }, "NextPage" : { "required" : [ "after" ], "type" : "object", "properties" : { "after" : { "type" : "string", "description" : "The offset for the next page of records.", "example" : null }, "link" : { "type" : "string", "description" : "A direct link to the request for the next page of records.", "example" : null } }, "description" : "Specifies the paging information needed to retrieve the next set of results in a paginated API response", "example" : null }, "ObjectTypeId" : { "type" : "object", "example" : null }, "Paging" : { "type" : "object", "properties" : { "next" : { "$ref" : "#/components/schemas/NextPage" }, "prev" : { "$ref" : "#/components/schemas/PreviousPage" } }, "description" : "The cursor to be used for paging through records.", "example" : null }, "PreviousPage" : { "required" : [ "before" ], "type" : "object", "properties" : { "before" : { "type" : "string", "description" : "The offset of the previous page of records.", "example" : null }, "link" : { "type" : "string", "description" : "A direct link to the request for the previous page of records.", "example" : null } }, "description" : "specifies the paging information needed to retrieve the previous set of results in a paginated API response", "example" : null }, "PublicBatchMigrationMapping" : { "required" : [ "legacyListIdsToIdsMapping", "missingLegacyListIds" ], "type" : "object", "properties" : { "legacyListIdsToIdsMapping" : { "type" : "array", "example" : null, "items" : { "$ref" : "#/components/schemas/PublicMigrationMapping" } }, "missingLegacyListIds" : { "type" : "array", "description" : "A list of legacy list ids that were passed in but not found. It will be empty if no id's are missing", "example" : null, "items" : { "type" : "string", "example" : null } } }, "example" : null }, "PublicFilterBranchIF" : { "type" : "object", "properties" : { "filterBranchOperator" : { "type" : "string", "example" : null }, "filterBranchType" : { "type" : "string", "example" : null, "enum" : [ "AND", "ASSOCIATION", "NOT_ALL", "NOT_ANY", "OR", "RESTRICTED", "UNIFIED_EVENTS" ] }, "filterBranches" : { "type" : "array", "example" : null, "items" : { "$ref" : "#/components/schemas/PublicFilterBranchIF" } }, "filters" : { "type" : "array", "example" : null, "items" : { "$ref" : "#/components/schemas/PublicFilterIF" } } }, "example" : null, "discriminator" : { "propertyName" : "filterBranchType" } }, "PublicFilterIF" : { "type" : "object", "properties" : { "filterType" : { "type" : "string", "example" : null, "enum" : [ "ADS_SEARCH", "ADS_TIME", "ASSOCIATION", "COMMUNICATION_SUBSCRIPTION", "CONSTANT", "CTA", "EMAIL_EVENT", "EMAIL_SUBSCRIPTION", "EVENT", "FORM_SUBMISSION", "FORM_SUBMISSION_ON_PAGE", "IN_LIST", "INTEGRATION_EVENT", "PAGE_VIEW", "PRIVACY", "PROPERTY", "SURVEY_MONKEY", "SURVEY_MONKEY_VALUE", "UNIFIED_EVENTS", "WEBINAR" ] } }, "example" : null, "discriminator" : { "propertyName" : "filterType" } }, "PublicListConversionResponse" : { "required" : [ "listId" ], "type" : "object", "properties" : { "convertedAt" : { "type" : "string", "description" : "The date and time when the list was converted.", "format" : "date-time", "example" : null }, "listId" : { "type" : "string", "description" : "The unique identifier of the list for which the conversion details are provided.", "example" : null }, "requestedConversionTime" : { "$ref" : "#/components/schemas/PublicListConversionTime" } }, "example" : null }, "PublicListConversionTime" : { "type" : "object", "properties" : { "conversionType" : { "type" : "string", "example" : null } }, "example" : null, "discriminator" : { "propertyName" : "conversionType" } }, "PublicListFolder" : { "required" : [ "childLists", "childNodes", "id", "parentFolderId" ], "type" : "object", "properties" : { "childLists" : { "type" : "array", "description" : "An array of list Id's contained in this folder.", "example" : null, "items" : { "type" : "integer", "format" : "int32", "example" : null } }, "childNodes" : { "type" : "array", "example" : null, "items" : { "$ref" : "#/components/schemas/PublicListFolder" } }, "createdAt" : { "type" : "string", "description" : "The time the folder was created at.", "format" : "date-time", "example" : null }, "id" : { "type" : "string", "description" : "The Id of the folder.", "example" : null }, "name" : { "type" : "string", "description" : "The name of the folder.", "example" : null }, "parentFolderId" : { "type" : "string", "description" : "The Id of the folder this folder is in, the root folder is represented as 0.", "example" : null }, "updatedAt" : { "type" : "string", "description" : "The time the folder was last updated at.", "format" : "date-time", "example" : null }, "updatedContentsAt" : { "type" : "string", "description" : "The time that the contents of the folder was last updated at.", "format" : "date-time", "example" : null }, "userId" : { "type" : "integer", "description" : "The user Id of the owner of the folder.", "format" : "int32", "example" : null } }, "example" : null }, "PublicListPermissions" : { "required" : [ "teamsWithEditAccess", "usersWithEditAccess" ], "type" : "object", "properties" : { "teamsWithEditAccess" : { "type" : "array", "example" : null, "items" : { "type" : "integer", "format" : "int32", "example" : null } }, "usersWithEditAccess" : { "type" : "array", "example" : null, "items" : { "type" : "integer", "format" : "int32", "example" : null } } }, "example" : null }, "PublicMembershipSettings" : { "type" : "object", "properties" : { "includeUnassigned" : { "type" : "boolean", "description" : "Indicates whether unassigned memberships should be included.", "example" : null }, "membershipTeamId" : { "type" : "integer", "description" : "The ID of the team associated with the membership.", "format" : "int32", "example" : null } }, "example" : null }, "PublicMigrationMapping" : { "required" : [ "legacyListId", "listId" ], "type" : "object", "properties" : { "legacyListId" : { "type" : "string", "description" : "The legacy list id for the list", "example" : null }, "listId" : { "type" : "string", "description" : "The V3 list id for the list", "example" : null } }, "example" : null }, "PublicObjectList" : { "required" : [ "listId", "listVersion", "name", "objectTypeId", "processingStatus", "processingType" ], "type" : "object", "properties" : { "createdAt" : { "type" : "string", "description" : "The time when the list was created.", "format" : "date-time", "example" : null }, "createdById" : { "type" : "string", "description" : "The ID of the user that created the list.", "example" : null }, "deletedAt" : { "type" : "string", "description" : "The time when the list was deleted.", "format" : "date-time", "example" : null }, "filterBranch" : { "$ref" : "#/components/schemas/PublicFilterBranchIF" }, "filtersUpdatedAt" : { "type" : "string", "description" : "The time when the filters for this list were last updated.", "format" : "date-time", "example" : null }, "listId" : { "type" : "string", "description" : "The **ILS ID** of the list.", "example" : null }, "listPermissions" : { "$ref" : "#/components/schemas/PublicListPermissions" }, "listVersion" : { "type" : "integer", "description" : "The version of the list.", "format" : "int32", "example" : null }, "membershipSettings" : { "$ref" : "#/components/schemas/PublicMembershipSettings" }, "name" : { "type" : "string", "description" : "The name of the list.", "example" : null }, "objectTypeId" : { "type" : "string", "description" : "The object type of the list.", "example" : null }, "processingStatus" : { "type" : "string", "description" : "The processing status of the list.", "example" : null }, "processingType" : { "type" : "string", "description" : "The processing type of the list.", "example" : null }, "size" : { "type" : "integer", "description" : "Size of the list", "format" : "int64", "example" : null }, "updatedAt" : { "type" : "string", "description" : "The time the list was last updated.", "format" : "date-time", "example" : null }, "updatedById" : { "type" : "string", "description" : "The ID of the user that last updated the list.", "example" : null } }, "description" : "An object list definition.", "example" : null }, "PublicObjectListSearchResult" : { "required" : [ "additionalProperties", "listId", "listVersion", "name", "objectTypeId", "processingStatus", "processingType" ], "type" : "object", "properties" : { "additionalProperties" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "The name and value of any additional properties that exist for this list and that were included in the search request.", "example" : null }, "createdAt" : { "type" : "string", "description" : "The time when the list was created.", "format" : "date-time", "example" : null }, "createdById" : { "type" : "string", "description" : "The ID of the user that created the list.", "example" : null }, "deletedAt" : { "type" : "string", "description" : "The time when the list was deleted.", "format" : "date-time", "example" : null }, "filtersUpdatedAt" : { "type" : "string", "description" : "The time when the filters for this list were last updated.", "format" : "date-time", "example" : null }, "listId" : { "type" : "string", "description" : "The **ILS ID** of the list.", "example" : null }, "listVersion" : { "type" : "integer", "description" : "The version of the list.", "format" : "int32", "example" : null }, "name" : { "type" : "string", "description" : "The name of the list.", "example" : null }, "objectTypeId" : { "type" : "string", "description" : "The object type of the list.", "example" : null }, "processingStatus" : { "type" : "string", "description" : "The processing status of the list.", "example" : null }, "processingType" : { "type" : "string", "description" : "The processing type of the list.", "example" : null }, "updatedAt" : { "type" : "string", "description" : "The time the list was last updated.", "format" : "date-time", "example" : null }, "updatedById" : { "type" : "string", "description" : "The ID of the user that last updated the list.", "example" : null } }, "example" : { "additionalProperties" : { "hs_last_record_added_at" : 1695938616824, "hs_list_reference_count" : 0, "hs_list_size" : 59, "hs_list_size_week_delta" : -1 }, "createdAt" : "2023-09-28T22:03:17.998Z", "createdById" : "1", "filtersUpdatedAt" : "2023-09-28T22:03:17.998Z", "listId" : "123", "listVersion" : 1, "name" : "Test list", "objectTypeId" : "0-1", "processingStatus" : "COMPLETED", "processingType" : "SNAPSHOT", "updatedById" : "1" } }, "RecordIdInput" : { "required" : [ "objectTypeId", "recordId" ], "type" : "object", "properties" : { "objectTypeId" : { "$ref" : "#/components/schemas/ObjectTypeId" }, "recordId" : { "type" : "string", "example" : null } }, "example" : null }, "RecordListMembership" : { "required" : [ "listId", "listVersion" ], "type" : "object", "properties" : { "firstAddedTimestamp" : { "type" : "string", "description" : "The timestamp when the record was first added to the list.", "format" : "date-time", "example" : null }, "isPublicList" : { "type" : "boolean", "description" : "Indicates whether the list is public.", "example" : null }, "lastAddedTimestamp" : { "type" : "string", "description" : "The timestamp when the record was last added to the list.", "format" : "date-time", "example" : null }, "listId" : { "type" : "string", "description" : "The unique identifier of the list.", "example" : null }, "listVersion" : { "type" : "integer", "description" : "The version number of the list.", "format" : "int32", "example" : null } }, "description" : "Lists record is member of", "example" : { "firstAddedTimestamp" : "2023-06-28T22:00:15.001Z", "lastAddedTimestamp" : "2023-09-28T22:03:17.998Z", "listId" : 13, "listVersion" : 2 } }, "SortField" : { "type" : "object", "example" : null } }, "responses" : { "Error" : { "description" : "An error occurred.", "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/Error" }, "example" : null } } } }, "securitySchemes" : { "developer_hapikey" : { "type" : "apiKey", "name" : "hapikey", "in" : "query" }, "oauth2" : { "type" : "oauth2", "flows" : { "authorizationCode" : { "authorizationUrl" : "https://app.hubspot.com/oauth/authorize", "tokenUrl" : "https://api.hubapi.com/oauth/v1/token", "scopes" : { "cms.membership.access_groups.write" : "", "crm.lists.read" : "", "crm.lists.write" : "" } } } }, "private_apps" : { "type" : "apiKey", "name" : "private-app", "in" : "header" }, "private_apps_legacy" : { "type" : "apiKey", "name" : "private-app-legacy", "in" : "header" } } }, "x-hubspot-available-client-libraries" : [ "Node", "Python", "Ruby", "PHP" ], "x-hubspot-product-tier-requirements" : { "marketing" : "FREE", "sales" : "FREE", "service" : "FREE", "cms" : "FREE", "commerce" : "FREE", "crmHub" : "FREE", "dataHub" : "FREE" } }