{"openapi":"3.0.3","info":{"title":"Data Tables API","description":"Provides full lifecycle management of custom data tables within Dotdigital Personalization. Custom data tables let you store and query structured data — such as product catalogues, recommendation feeds, or lookup tables — for use in personalisation rules. Operations cover listing, creating, reading, updating, and deleting tables, as well as validating table identifiers and managing table rows.","version":"1.0.1"},"servers":[{"url":"https://{region}-api-freshrelevance.dotdigital.com/api","variables":{"region":{"description":"The region id your account belongs to","enum":["r1","r2","r3"],"default":"r1"}}}],"security":[{"apiTokenAuth":[]}],"paths":{"/{website_id}/custom_data_tables/list":{"get":{"tags":["Manage tables"],"summary":"List Custom Data Tables","description":"Lists all the Custom Data Tables in the current account.","operationId":"getListTables","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"page","in":"query","description":"Which page of results you wish to return; First page is indexed as 1.","schema":{"type":"integer","default":1},"example":1},{"name":"limit","in":"query","description":"Get this number of records to return in results array (pagination).","schema":{"minimum":1,"type":"integer","default":25},"example":50},{"name":"include_deleted","in":"query","description":"If this is set to `true` then all Custom Data Tables will be returned. If set to `false` then archived Custom Data Tables will not be returned.\n","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Lists all information about a Custom Data Table other than its fields. This is paginated and the information is under the `results` key.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200"}}}},"400":{"$ref":"#/components/responses/PaginationParameterError"},"403":{"$ref":"#/components/responses/ForbiddenResponse"}}}},"/{website_id}/custom_data_tables/check-id":{"post":{"tags":["Utilities"],"summary":"Validate table identifier","description":"Ensures that the provided `tableId` is valid.","operationId":"postValidateIdentifier","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/custom_data_tables_checkid_body"}}}},"responses":{"200":{"description":"Describes if the `tableId` is free for use.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_1"}}}},"403":{"$ref":"#/components/responses/ForbiddenResponse"}}}},"/{website_id}/custom_data_tables/create":{"post":{"tags":["Manage tables"],"summary":"Creates Custom Data Table","description":"Creates a new, empty Custom Data Table.","operationId":"postCreateTable","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/custom_data_tables_create_body"}}}},"responses":{"201":{"description":"Table created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDataTable"}}}},"400":{"description":"Issue with Table identifier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_400"}}}},"403":{"$ref":"#/components/responses/ForbiddenResponse"}}}},"/{website_id}/custom_data_tables/table/{tableId}":{"get":{"tags":["Edit table"],"summary":"Gets a Custom Data Table.","description":"Gets the complete information for a single Custom Data Table.","operationId":"getGetTable","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"tableId","in":"path","description":"The ID of the table you want to access or modify.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns all available information about the Custom Data Table.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDataTable"}}}},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/TableNotFound"}}},"put":{"tags":["Edit table"],"summary":"Updates Custom Data Table","description":"Updates basic information and the fields associated with a specific Custom Data Table. When updating fields, this is a complete state transfer, so you must include all fields in this request. Any new fields included will be created. Any existing fields not included will be deleted. Fields will be matched on `fieldId`. If you do not include any of `name`, `archived`, or `fields` in the request then they won't be updated.\n","operationId":"putUpdateTable","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"tableId","in":"path","description":"The ID of the table you want to access or modify.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/table_tableId_body"}}}},"responses":{"200":{"description":"Table information with updated values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDataTable"}}}},"400":{"description":"Field updates could not be made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_400_1"}}}},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/TableNotFound"}}}},"/{website_id}/custom_data_tables/table/{tableId}/data":{"get":{"tags":["Data access"],"summary":"Get data from a table","operationId":"getGetTableData","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"tableId","in":"path","description":"The ID of the table you want to access or modify.","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Which page of results you wish to return; First page is indexed as 1.","schema":{"type":"integer","default":1},"example":1},{"name":"limit","in":"query","description":"Get this number of records to return in results array (pagination).","schema":{"minimum":1,"type":"integer","default":25},"example":50}],"responses":{"200":{"description":"Returns data from the Custom Data Table. Use the pagination parameters `page` and `limit` to control how much data is returned.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_2"}}}},"400":{"$ref":"#/components/responses/PaginationParameterError"},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/TableNotFound"}}}},"/{website_id}/custom_data_tables/table/{tableId}/schema":{"get":{"tags":["Edit table"],"summary":"Gets JSON schema for table","operationId":"getGetTableSchema","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"tableId","in":"path","description":"The ID of the table you want to access or modify.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns the JSON schema for a given table.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_3"}}}},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/TableNotFound"}}}},"/{website_id}/custom_data_tables/table/{tableId}/channels":{"get":{"tags":["Table channels"],"summary":"Gets channels for table","description":"Lists all the channels for this specific Custom Data Table.","operationId":"getGetTableChannels","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"tableId","in":"path","description":"The ID of the table you want to access or modify.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lists all information about the channels that are linked to this Custom Data Table.\n","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}}}}},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/TableNotFound"}}},"put":{"tags":["Table channels"],"summary":"Update or delete a channel for a table","description":"Modifies a channel for the specified Custom Data Table. If you wish to delete a channel, set `active` to `false`.\n","operationId":"putUpdateTableChannel","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"tableId","in":"path","description":"The ID of the table you want to access or modify.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channel"}}}},"responses":{"200":{"description":"Returns the new modified channel details.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channel"}}}},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/TableOrChannelNotFound"}}},"post":{"tags":["Table channels"],"summary":"Creates a channel for table","description":"Creates a channel for this specific Custom Data Table.","operationId":"postCreateTableChannel","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"tableId","in":"path","description":"The ID of the table you want to access or modify.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns the newly created channel object. `esp_channel_name` will be returned as empty. This endpoint creates a blank channel, then you use the PUT endpoint to update it.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channel"}}}},"404":{"$ref":"#/components/responses/TableNotFound"}}}},"/{website_id}/custom_data_tables/table/{tableId}/channels/{channelId}":{"get":{"tags":["Table channels"],"summary":"Get channel for table","description":"Gets a specific channel for the specified Custom Data Table.\n","operationId":"getGetTableChannel","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"tableId","in":"path","description":"The ID of the table you want to access or modify.","required":true,"schema":{"type":"string"}},{"name":"channelId","in":"path","description":"The channel ID with it's unique hash.","required":true,"schema":{"type":"string"},"example":"CustomDataTableImport:2qk7xzb"}],"responses":{"200":{"description":"Returns the channel details.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channel"}}}},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/TableOrChannelNotFound"}}}},"/{website_id}/custom_data_tables/table/{tableId}/channels/logs":{"get":{"tags":["Utilities"],"summary":"Get logs for table","description":"Returns all the logs from channels to do with the specified Custom Data Table.\n","operationId":"getGetTableLogs","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"tableId","in":"path","description":"The ID of the table you want to access or modify.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns the logs in a list format. *** Not sure on datetime format. ***","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/inline_response_200_4"}}}}},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/TableNotFound"}}}},"/{website_id}/custom_data_tables/table/{tableId}/export":{"post":{"tags":["Data access"],"summary":"Export the data from table","description":"Triggers the generation of a downloadable file containing the entire contents of the Custom Data Table.\n","operationId":"postExportTableData","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},{"name":"tableId","in":"path","description":"The ID of the table you want to access or modify.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"This will return a `job_id` so the download can be sent to the downloads panel.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_5"}}}},"403":{"$ref":"#/components/responses/ForbiddenResponse"},"404":{"$ref":"#/components/responses/TableNotFound"}}}}},"components":{"schemas":{"ChannelNotFoundResponse":{"type":"object","properties":{"reason":{"type":"string","enum":["channel not found"]}}},"TableNotFoundResponse":{"type":"object","properties":{"reason":{"type":"string","enum":["table not found"]}}},"Field":{"required":["dataType","fieldId","isLookup","name"],"type":"object","properties":{"name":{"type":"string","description":"User reference for this field","example":"Team ID"},"fieldId":{"allOf":[{"$ref":"#/components/schemas/ScriptSafeReference"},{"description":"Identifier for this field that must be unique for the table it belongs to. Used through the system.","example":"team_id"}]},"isLookup":{"type":"boolean","description":"True if this field is used to lookup data rows with in the table. Commonly this field will store identifiers."},"dataType":{"type":"string","description":"The type of data that is stored in this field. This will be used to validate imported data and provides guarantees around what the data will look like.","enum":["string","url","color","integer","number","datetime","object","array"]}}},"ScriptSafeReference":{"pattern":"[\\w_]+","type":"string"},"TableName":{"type":"string","description":"A user reference for the table.","example":"Staff teams"},"TableId":{"allOf":[{"$ref":"#/components/schemas/ScriptSafeReference"},{"description":"Unique identifier for the table used throughout the system.","example":"staff_teams"}]},"Type":{"type":"string","description":"The type of a Custom Data Table. Either a well-defined, known structure or custom for user-defined tables.","enum":["custom","brands","categories"]},"Archived":{"type":"boolean","description":"True if the table has been archived by a user and is no longer intended to be used."},"Channel":{"required":["channelId"],"type":"object","properties":{"_id":{"type":"string","description":"MongoDB identifier assigned when added to the database.","example":"64243eee0b036d4b5cd092d5"},"channelId":{"type":"string","description":"The channel ID with it's unique hash.","example":"CustomDataTableImport:2qk7xzb"},"active":{"type":"boolean","description":"Flag that describes if the channel is active or not.  If this is `false` you should not display the channel.\n","example":true},"channel_name":{"type":"string","description":"User assigned name for the channel.","example":"Custom Data Table Import Channel Main"}}},"FieldView":{"type":"object","allOf":[{"$ref":"#/components/schemas/Field"},{"properties":{"dateAdded":{"type":"string","description":"The date & time the field was first added to the table.","example":"2023-11-15T09:56:10.687000"},"lastEdited":{"type":"string","description":"The date & time the field was last edited.","example":"2023-11-16T09:56:10.687000"},"lastEditedBy":{"type":"string","description":"The username of the user who last edited this field."},"rowsWithValue":{"minimum":0,"type":"integer","description":"The number of rows in the table that this field has data for (i.e. not blank)."}}}]},"CustomDataTable":{"type":"object","description":"The full information about a Custom Data Table.","allOf":[{"$ref":"#/components/schemas/CustomDataTableView"},{"properties":{"fieldsCanBeEdited":{"type":"boolean","description":"Can fields for this table be added/removed?"},"fields":{"type":"array","description":"The field available in this table. Ordered by look up field first, then the rest sorted on field name.","items":{"$ref":"#/components/schemas/FieldView"}}}}]},"CustomDataTableView":{"type":"object","properties":{"tableId":{"$ref":"#/components/schemas/TableId"},"name":{"$ref":"#/components/schemas/TableName"},"type":{"$ref":"#/components/schemas/Type"},"isDraft":{"type":"boolean","description":"True if the table is in a draft state where it is not fully configured, therefore cannot be used."},"active":{"type":"boolean","description":"True if the table is active and can be used."},"archived":{"$ref":"#/components/schemas/Archived"},"lastUpdated":{"type":"number","description":"The Epoch date & time this table was last changed.","example":1728319212.722},"lastImported":{"type":"number","description":"The Epoch date & time this table last had data imported.","example":1728319212.722},"lastUpdatedBy":{"type":"string","description":"The username of the person who last made a change to this table."},"dataRows":{"minimum":0,"type":"integer","description":"The number of rows of data this table contains."},"numberOfFields":{"minimum":0,"type":"integer","description":"The number of fields that have been defined against this table."},"usedInSmartBlocks":{"type":"array","description":"A list of the slugs of the smartblocks this table is used in.","items":{"$ref":"#/components/schemas/CustomDataTableView_usedInSmartBlocks"}}},"description":"A read-only view of a Custom Data Table."},"PaginatedData":{"required":["count","links","page","total"],"type":"object","properties":{"page":{"minimum":1,"type":"integer","description":"The index for the page of data returned.","example":1},"count":{"minimum":0,"type":"integer","description":"Number of records in the page.","example":12},"total":{"minimum":0,"type":"integer","description":"Total number of records in the set.","example":12},"links":{"$ref":"#/components/schemas/PaginatedData_links"}},"description":"Data page and pagination links"},"inline_response_200":{"allOf":[{"$ref":"#/components/schemas/PaginatedData"},{"required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/CustomDataTableView"}}},"description":"The data table details."}]},"custom_data_tables_checkid_body":{"required":["tableId"],"type":"object","properties":{"tableId":{"$ref":"#/components/schemas/TableId"}}},"inline_response_200_1":{"type":"object","properties":{"ok":{"type":"boolean","description":"`true` if both `available` and `valid` are also `true`."},"available":{"type":"boolean","description":"`true` if this `tableId` is free for use. `false` if otherwise."},"valid":{"type":"boolean","description":"`true` if this `tableId` is of a valid format. `false` if otherwise."}}},"custom_data_tables_create_body":{"required":["name","tableId","type"],"type":"object","properties":{"name":{"$ref":"#/components/schemas/TableName"},"tableId":{"$ref":"#/components/schemas/TableId"},"type":{"$ref":"#/components/schemas/Type"}}},"inline_response_400":{"type":"object","properties":{"reason":{"type":"string","enum":["tableId already exists","tableId is invalid"]}}},"table_tableId_body":{"required":["archived","name"],"type":"object","properties":{"name":{"$ref":"#/components/schemas/TableName"},"archived":{"$ref":"#/components/schemas/Archived"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/Field"}}}},"inline_response_400_1":{"example":{"team_id":{"reason":"field cannot be deleted"},"team_name":{"reason":"cannot change field's datatype"}},"oneOf":[{"type":"object","additionalProperties":{"required":["reason"],"type":"object","properties":{"reason":{"type":"string","enum":["field cannot be deleted","cannot change field's datatype","duplicate lookup field"]}}},"description":"An error description for each field with errors, indexed by the field ID."},{"type":"object","properties":{"reason":{"type":"string","enum":["this table's fields cannot be edited"]}},"description":"This table's fields cannot be edited"}]},"inline_response_200_2":{"allOf":[{"$ref":"#/components/schemas/PaginatedData"},{"required":["results"],"properties":{"results":{"type":"array","example":[{"team_name":"New England Patriots","team_colour":"Nautical Blue","team_slogan":"Do Your Job / Go Pats"},{"team_name":"Miami Dolphins","team_colour":"Aqua","team_slogan":"Go Fins"}],"items":{"type":"object"}}},"description":"The data records."}]},"inline_response_200_3":{"type":"object","properties":{"field1":{"type":"string","example":"String"}}},"inline_response_200_4":{"type":"object","properties":{"channelId":{"type":"string","example":"CustomDataTableImport:2qk7xzb"},"message":{"type":"string","example":"Import Channel abc123def ran successfully and imported 149 rows."},"level":{"type":"string","example":"INFO"},"datetime":{"type":"string","example":"2023-11-05T12:39:02+00:00"}}},"inline_response_200_5":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"errors":{"type":"array","example":[],"items":{"type":"string"}},"task_id":{"type":"string","example":"654a1d061ae0da0c3e7a4534"},"job_id":{"type":"string","example":"654a1d061ae0da0c3e7a4533"}}},"CustomDataTableView_usedInSmartBlocks":{"type":"object","properties":{"id":{"type":"string","description":"SmartBlock ID","example":"tbu20b5"},"name":{"type":"string","description":"SmartBlock Name","example":"Recommend SmartBlock Main"}}},"PaginatedData_links":{"type":"object","properties":{"next":{"type":"string","description":"URL of the next page.","format":"url","nullable":true},"previous":{"type":"string","description":"URL of the previous page.","format":"url","nullable":true}},"description":"Page navigation links"}},"responses":{"TableNotFound":{"description":"`tableId` not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TableNotFoundResponse"}}}},"ChannelNotFound":{"description":"`channelId` not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelNotFoundResponse"}}}},"TableOrChannelNotFound":{"description":"`tableId` or `channelId` not found.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TableNotFoundResponse"},{"$ref":"#/components/schemas/ChannelNotFoundResponse"}]},"example":{"reason":"tableId and/or channelId not found"}}}},"PaginationParameterError":{"description":"There was an issue with the pagination parameters: `page` and/or `limit`.","content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","enum":["page was not a valid integer","limit was not a valid integer"]}}}}}},"ForbiddenResponse":{"description":"Unauthorized / forbidden","content":{"application/json":{"schema":{"required":["detail"],"type":"object","properties":{"detail":{"type":"string","description":"Indicates why the call failed","example":"Authentication credentials were not provided."}}}}}}},"parameters":{"ChannelId":{"name":"channelId","in":"path","description":"The channel ID with it's unique hash.","required":true,"schema":{"type":"string"},"example":"CustomDataTableImport:2qk7xzb"},"TableIdParameter":{"name":"tableId","in":"path","description":"The ID of the table you want to access or modify.","required":true,"schema":{"type":"string"}},"WebsiteId":{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},"Page":{"name":"page","in":"query","description":"Which page of results you wish to return; First page is indexed as 1.","schema":{"type":"integer","default":1},"example":1},"Limit":{"name":"limit","in":"query","description":"Get this number of records to return in results array (pagination).","schema":{"minimum":1,"type":"integer","default":25},"example":50}},"securitySchemes":{"apiTokenAuth":{"type":"apiKey","name":"x-api-key","in":"header"}}},"x-samples-languages":["curl","csharp","java","javascript","node","python","php","ruby"]}