@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api CRM Lists
@base https://api.hubapi.com
@version v3
@auth OAuth2 | ApiKey private-app in header
@endpoints 30
@hint download_for_search
@toc crm(30)

@endpoint GET /crm/lists/v3
@optional {includeFilters: bool=false, listIds: [str]}
@returns(200) {lists: [map]} # successful operation

@endpoint POST /crm/lists/v3
@required {name: str # The name of the list, which must be globally unique across all public lists in the portal., objectTypeId: str # The object type ID of the type of objects that the list will store., processingType: str # The processing type of the list. One of: `SNAPSHOT`, `MANUAL`, or `DYNAMIC`.}
@optional {customProperties: map # The list of custom properties to tie to the list. Custom property name is the key, the value is the value., filterBranch: any # Filter branch object containing filtering criteria for the list, listFolderId: int(int32) # 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., listPermissions: map{teamsWithEditAccess!: [int(int32)], usersWithEditAccess!: [int(int32)]}, membershipSettings: map{includeUnassigned: bool, membershipTeamId: int(int32)}}
@returns(200) {list: map{createdAt: str(date-time), createdById: str, deletedAt: str(date-time), filterBranch: any, filtersUpdatedAt: str(date-time), listId: str, listPermissions: map{teamsWithEditAccess: [int(int32)], usersWithEditAccess: [int(int32)]}, listVersion: int(int32), membershipSettings: map{includeUnassigned: bool, membershipTeamId: int(int32)}, name: str, objectTypeId: str, processingStatus: str, processingType: str, size: int(int64), updatedAt: str(date-time), updatedById: str}} # successful operation

@endpoint GET /crm/lists/v3/folders
@optional {folderId: str=0}
@returns(200) {folder: map{childLists: [int(int32)], childNodes: [map], createdAt: str(date-time), id: str, name: str, parentFolderId: str, updatedAt: str(date-time), updatedContentsAt: str(date-time), userId: int(int32)}} # successful operation

@endpoint POST /crm/lists/v3/folders
@required {name: str # The name of the folder to be created.}
@optional {parentFolderId: str # The folder this should be created in, if not specified will be created in the root folder 0.}
@returns(200) {folder: map{childLists: [int(int32)], childNodes: [map], createdAt: str(date-time), id: str, name: str, parentFolderId: str, updatedAt: str(date-time), updatedContentsAt: str(date-time), userId: int(int32)}} # successful operation

@endpoint PUT /crm/lists/v3/folders/move-list
@required {listId: str # The Id of the list to move., newFolderId: str # The Id of folder to move the list to, the root folder is Id 0.}
@returns(204) No content

@endpoint DELETE /crm/lists/v3/folders/{folderId}
@required {folderId: str}
@returns(204) No content

@endpoint PUT /crm/lists/v3/folders/{folderId}/move/{newParentFolderId}
@required {folderId: str, newParentFolderId: str}
@returns(200) {folder: map{childLists: [int(int32)], childNodes: [map], createdAt: str(date-time), id: str, name: str, parentFolderId: str, updatedAt: str(date-time), updatedContentsAt: str(date-time), userId: int(int32)}} # successful operation

@endpoint PUT /crm/lists/v3/folders/{folderId}/rename
@required {folderId: str}
@optional {newFolderName: str}
@returns(200) {folder: map{childLists: [int(int32)], childNodes: [map], createdAt: str(date-time), id: str, name: str, parentFolderId: str, updatedAt: str(date-time), updatedContentsAt: str(date-time), userId: int(int32)}} # successful operation

@endpoint GET /crm/lists/v3/idmapping
@optional {legacyListId: str}
@returns(200) {legacyListId: str, listId: str} # successful operation

@endpoint POST /crm/lists/v3/idmapping
@returns(200) {legacyListIdsToIdsMapping: [map], missingLegacyListIds: [str]} # successful operation

@endpoint GET /crm/lists/v3/object-type-id/{objectTypeId}/name/{listName}
@desc Retrieve List by Name
@required {listName: str # The name of the list to retrieve., objectTypeId: str # The object type ID of the list to retrieve.}
@optional {includeFilters: bool=false # A boolean indicating whether to include filter details in the response. Defaults to false.}
@returns(200) {list: map{createdAt: str(date-time), createdById: str, deletedAt: str(date-time), filterBranch: any, filtersUpdatedAt: str(date-time), listId: str, listPermissions: map{teamsWithEditAccess: [int(int32)], usersWithEditAccess: [int(int32)]}, listVersion: int(int32), membershipSettings: map{includeUnassigned: bool, membershipTeamId: int(int32)}, name: str, objectTypeId: str, processingStatus: str, processingType: str, size: int(int64), updatedAt: str(date-time), updatedById: str}} # successful operation

@endpoint POST /crm/lists/v3/records/memberships/batch/read
@required {inputs: [map{objectTypeId!: str, recordId!: str}]}
@returns(200) {completedAt: str(date-time), links: map, requestedAt: str(date-time), results: [map], startedAt: str(date-time), status: str} # successful operation
@returns(207) {completedAt: str(date-time), errors: [map], links: map, numErrors: int(int32), requestedAt: str(date-time), results: [map], startedAt: str(date-time), status: str} # multiple statuses

@endpoint GET /crm/lists/v3/records/{objectTypeId}/{recordId}/memberships
@required {objectTypeId: str, recordId: str}
@returns(200) {paging: map{next: map{after: str, link: str}, prev: map{before: str, link: str}}, results: [map], total: int(int64)} # successful operation

@endpoint POST /crm/lists/v3/search
@required {additionalProperties: [str] # 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.  By 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`., offset: int(int32) # 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.}
@optional {count: int(int32) # The number of lists to include in the response. Defaults to `20` if no value is provided. The max `count` is `500`., listIds: [str] # ILS list ids to be included in search results. If not specified, all lists matching other criteria will be included, objectTypeId: str, processingTypes: [str] # List processing types to be included in search results. If not specified, all lists with all processing types will be included., query: str # 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., sort: str # Sort field and order}
@returns(200) {hasMore: bool, lists: [map], offset: int(int32), total: int(int32)} # successful operation

@endpoint GET /crm/lists/v3/{listId}
@required {listId: str}
@optional {includeFilters: bool=false}
@returns(200) {list: map{createdAt: str(date-time), createdById: str, deletedAt: str(date-time), filterBranch: any, filtersUpdatedAt: str(date-time), listId: str, listPermissions: map{teamsWithEditAccess: [int(int32)], usersWithEditAccess: [int(int32)]}, listVersion: int(int32), membershipSettings: map{includeUnassigned: bool, membershipTeamId: int(int32)}, name: str, objectTypeId: str, processingStatus: str, processingType: str, size: int(int64), updatedAt: str(date-time), updatedById: str}} # successful operation

@endpoint DELETE /crm/lists/v3/{listId}
@required {listId: str}
@returns(204) No content

@endpoint GET /crm/lists/v3/{listId}/memberships
@required {listId: str}
@optional {after: str # The paging cursor token of the last successfully read resource will be returned as the `paging.next.after` JSON property of a paged response containing more results., before: str, limit: int(int32)=100 # The maximum number of results to display per page.}
@returns(200) {paging: map{next: map{after: str, link: str}, prev: map{before: str, link: str}}, results: [map], total: int(int64)} # successful operation

@endpoint DELETE /crm/lists/v3/{listId}/memberships
@required {listId: str}
@returns(204) No content

@endpoint PUT /crm/lists/v3/{listId}/memberships/add
@required {listId: str}
@returns(200) {recordIdsMissing: [str], recordIdsRemoved: [str], recordsIdsAdded: [str]} # successful operation

@endpoint PUT /crm/lists/v3/{listId}/memberships/add-and-remove
@required {listId: str, recordIdsToAdd: [str], recordIdsToRemove: [str]}
@returns(200) {recordIdsMissing: [str], recordIdsRemoved: [str], recordsIdsAdded: [str]} # successful operation

@endpoint PUT /crm/lists/v3/{listId}/memberships/add-from/{sourceListId}
@required {listId: str, sourceListId: str}
@returns(204) No content

@endpoint GET /crm/lists/v3/{listId}/memberships/join-order
@required {listId: str}
@optional {after: str # The paging cursor token of the last successfully read resource will be returned as the `paging.next.after` JSON property of a paged response containing more results., before: str, limit: int(int32)=100 # The maximum number of results to display per page.}
@returns(200) {paging: map{next: map{after: str, link: str}, prev: map{before: str, link: str}}, results: [map], total: int(int64)} # successful operation

@endpoint PUT /crm/lists/v3/{listId}/memberships/remove
@required {listId: str}
@returns(200) {recordIdsMissing: [str], recordIdsRemoved: [str], recordsIdsAdded: [str]} # successful operation

@endpoint PUT /crm/lists/v3/{listId}/restore
@required {listId: str}
@returns(204) No content

@endpoint GET /crm/lists/v3/{listId}/schedule-conversion
@required {listId: str}
@returns(200) {convertedAt: str(date-time), listId: str, requestedConversionTime: any} # successful operation

@endpoint PUT /crm/lists/v3/{listId}/schedule-conversion
@required {listId: str}
@returns(200) {convertedAt: str(date-time), listId: str, requestedConversionTime: any} # successful operation

@endpoint DELETE /crm/lists/v3/{listId}/schedule-conversion
@required {listId: str}
@returns(204) No content

@endpoint GET /crm/lists/v3/{listId}/size-and-edits-history/between
@required {listId: str}
@optional {endDate: str, startDate: str}
@returns(200) {editHistory: [str(date-time)], sizeHistory: [map]} # successful operation

@endpoint PUT /crm/lists/v3/{listId}/update-list-filters
@required {listId: str, filterBranch: any # Updated filtering criteria for the list}
@optional {enrollObjectsInWorkflows: bool=false}
@returns(200) {updatedList: map{createdAt: str(date-time), createdById: str, deletedAt: str(date-time), filterBranch: any, filtersUpdatedAt: str(date-time), listId: str, listPermissions: map{teamsWithEditAccess: [int(int32)], usersWithEditAccess: [int(int32)]}, listVersion: int(int32), membershipSettings: map{includeUnassigned: bool, membershipTeamId: int(int32)}, name: str, objectTypeId: str, processingStatus: str, processingType: str, size: int(int64), updatedAt: str(date-time), updatedById: str}} # successful operation

@endpoint PUT /crm/lists/v3/{listId}/update-list-name
@required {listId: str}
@optional {includeFilters: bool=false, listName: str}
@returns(200) {updatedList: map{createdAt: str(date-time), createdById: str, deletedAt: str(date-time), filterBranch: any, filtersUpdatedAt: str(date-time), listId: str, listPermissions: map{teamsWithEditAccess: [int(int32)], usersWithEditAccess: [int(int32)]}, listVersion: int(int32), membershipSettings: map{includeUnassigned: bool, membershipTeamId: int(int32)}, name: str, objectTypeId: str, processingStatus: str, processingType: str, size: int(int64), updatedAt: str(date-time), updatedById: str}} # successful operation

@end