{"openapi":"3.0.0","info":{"title":"Account API","description":"Provides utility operations for administering a Dotdigital Personalization account. Use this API to retrieve account and client information, update client settings, and manage admin users — including listing all admin users, retrieving a specific user, creating new users, updating user details, and deleting users. Also exposes endpoints for working with website configurations within the account.","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}/account_info/":{"get":{"tags":["Account info"],"summary":"Get account information","description":"Retrieves the Dotdigital Personalization account information for the website.","operationId":"getAccountInfo","parameters":[{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"}],"responses":{"200":{"description":"The account information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200"}}}},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}},"/{website_id}/client_info/":{"get":{"tags":["Client info"],"summary":"Get client information","description":"Retrieves the Dotdigital Personalization client information for the requesting account and website.","operationId":"getClientInfo","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":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"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":"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}],"responses":{"200":{"description":"The page of people data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_1"},"examples":{"success":{"value":{"links":{},"count":1,"total":1,"page":1,"results":[{"website_id":"abc1234","base_currency":"GBP","website_name":"example_demo","billing":{"sage_reference":"HADHGDHG","trial_start":"2021-03-26T15:08:15.665000","end_date":"2022-03-26T00:00:00","series":"2017b","trial_end":"2021-04-25T15:08:15.665000","plan":"frel_basic_2017b_nosetup","start_date":"2021-03-26T00:00:00","status":"free"}}],"headers":{"website_id":"Website ID","base_currency":"Base Currency","website_name":"Website Name","esp_catchall_address":"Catch-all address","esp_catchall_browse_address":"Catch-all address for Browse Abandon","market_sector_top_level":"Vertical"}}}}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}},"put":{"tags":["Client info"],"summary":"Update client information","description":"Updates the Dotdigital Personalization client information for the requesting account and website.","operationId":"putUpdateClientInfo","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":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/website_id_client_info_body"}}}},"responses":{"200":{"description":"Successfully updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_2"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}},"/{website_id}/admin_users/":{"get":{"tags":["Administrators"],"summary":"Get admin users","description":"Retrieves limited details about Dotdigital Personalization admin users.","operationId":"getAdminUsers","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":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"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":"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}],"responses":{"200":{"description":"The page of admin users details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_3"},"examples":{"success":{"value":{"links":{"next":"https://api.freshrelevance.com/api/abc1234/admin_users/?format=json&limit=2&page=2"},"count":72,"total":72,"page":1,"results":[{"user_id":2344,"first":"Joe","last":"Bloggs","email":"joe.bloggs@emailsim.io","datetime_added":"2015-11-02T10:04:09.802000","weekly_report_opt_out":false,"scheduled_report_frequency":"weekly","scheduled_report_last_sent":"2024-11-29T12:09:28.806000","last_activity_date":"2024-11-12T12:10:16Z","username":"joe.bloggs","is_active":true,"admin_user":true},{"user_id":4362,"first":"Sarah","last":"Bloggs","email":"sarah.bloggs@emailsim.io","datetime_added":"2018-02-08T10:40:28.644000","weekly_report_opt_out":true,"scheduled_report_frequency":"none","last_activity_date":"2024-10-18T00:21:59Z","username":"sara.bloggs","is_active":true,"admin_user":true}]}}}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}},"/{website_id}/admin_users/{user_id}/":{"put":{"tags":["Administrators"],"summary":"Update admin user","description":"Updates an admin users details.","operationId":"putUpdateAdminUser","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":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"user_id","in":"path","description":"The Dotdigital Personalization user id to update.","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/admin_users_user_id_body"}}}},"responses":{"200":{"description":"Successfully updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_2"}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}},"/{website_id}/channels/":{"get":{"tags":["Channels"],"summary":"Get channels","description":"Retrieves the configured channels for the account.","operationId":"getChannels","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":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"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":"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}],"responses":{"200":{"description":"The page of channel data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_4"},"examples":{"success":{"value":{"links":{},"count":5,"total":5,"page":1,"results":[{"website_id":"ibwg7mvo","ftp_field_mapping":"{\"email\":{\"ftp_field_name\":\"email\"},\"eid\":{\"ftp_field_name\":\"id\"}}","channel_id":"EspBlackhole"},{"website_id":"ibwg7mvo","ftp_field_mapping":"{\"email\":{\"ftp_field_name\":\"email\"},\"eid\":{\"ftp_field_name\":\"id\"}}","channel_id":"EspFrQuickstart"},{"website_id":"ibwg7mvo","ftp_field_mapping":"{\"email\":{\"ftp_field_name\":\"email\"},\"eid\":{\"ftp_field_name\":\"id\"}}","channel_id":"ExportS3:system-firehose"},{"website_id":"ibwg7mvo","ftp_field_mapping":"{\"email\":{\"ftp_field_name\":\"email\"},\"eid\":{\"ftp_field_name\":\"id\"}}","channel_id":"FirehoseExportEngine:system-firehose"},{"website_id":"ibwg7mvo","ftp_field_mapping":"{\"email\":{\"ftp_field_name\":\"email\"},\"eid\":{\"ftp_field_name\":\"id\"}}","channel_id":"TriggeredAnalyticsBlackhole"}],"headers":{"website_id":"Website ID","ftp_field_mapping":"FTP Field Mapping","channel_id":"Channel ID"}}}}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}},"/{website_id}/channels/{channel_id}/":{"get":{"tags":["Channels"],"summary":"Get channels","description":"Retrieves the details for a specified channel.","operationId":"getChannel","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":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"name":"channel_id","in":"path","description":"The channel id to retrieve.","required":true,"schema":{"type":"integer"}},{"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":"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}],"responses":{"200":{"description":"The page of channel data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_5"},"examples":{"success":{"value":{"links":{},"count":5,"total":5,"page":1,"results":[{"website_id":"ibwg7mvo","ftp_field_mapping":"{\"email\":{\"ftp_field_name\":\"email\"},\"eid\":{\"ftp_field_name\":\"id\"}}","channel_id":"EspBlackhole"},{"website_id":"ibwg7mvo","ftp_field_mapping":"{\"email\":{\"ftp_field_name\":\"email\"},\"eid\":{\"ftp_field_name\":\"id\"}}","channel_id":"EspFrQuickstart"},{"website_id":"ibwg7mvo","ftp_field_mapping":"{\"email\":{\"ftp_field_name\":\"email\"},\"eid\":{\"ftp_field_name\":\"id\"}}","channel_id":"ExportS3:system-firehose"},{"website_id":"ibwg7mvo","ftp_field_mapping":"{\"email\":{\"ftp_field_name\":\"email\"},\"eid\":{\"ftp_field_name\":\"id\"}}","channel_id":"FirehoseExportEngine:system-firehose"},{"website_id":"ibwg7mvo","ftp_field_mapping":"{\"email\":{\"ftp_field_name\":\"email\"},\"eid\":{\"ftp_field_name\":\"id\"}}","channel_id":"TriggeredAnalyticsBlackhole"}],"headers":{"website_id":"Website ID","ftp_field_mapping":"FTP Field Mapping","channel_id":"Channel ID"}}}}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}},"/{website_id}/categories/":{"get":{"tags":["Categories"],"summary":"Get categories","description":"Retrieves the configured categories for the account.","operationId":"getCategories","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":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},{"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":"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}],"responses":{"200":{"description":"The page of channel data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200_6"},"examples":{"success":{"value":{"links":{"next":"https://api.freshrelevance.com/api/rg55bjkl/categories/?format=json&limit=5&page=2"},"count":386,"total":386,"page":1,"results":[{"_id":"2016","dt":"2024-10-28T18:15:54.299000Z","n":"2016"},{"_id":"accessories","dt":"2024-10-28T18:15:27.176000Z","n":"Accessories"},{"_id":"bags","dt":"2024-10-28T18:18:13.416000Z","n":"Bags"},{"_id":"beanies","dt":"2024-10-28T18:15:54.103000Z","n":"Beanies"},{"_id":"footwear","dt":"2024-10-28T18:17:48.329000Z","n":"Footwear"}],"headers":{"n":"Name","_id":"ID","dt":"Last Updated"}}}}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403Response"}}}}},"components":{"schemas":{"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":{"required":["api_domain","organisation_id","organisation_name","region_id","website_id","website_name"],"type":"object","properties":{"website_id":{"type":"string","description":"The website id.","example":"abc1234"},"website_name":{"type":"string","description":"The website name.","example":"Example demo"},"organisation_id":{"type":"integer","description":"The unique identifier for the organisation.","example":123},"organisation_name":{"type":"string","description":"The name of the organisation.","example":"Acme"},"region_id":{"type":"string","description":"The Dotdigital Personalization region identifier for where the instance for this website is hosted.","example":"r1"},"api_domain":{"type":"string","description":"The domain to use when calling the API for this instance.","example":"r1-api-freshrelevance.dotdigital.com"}}},"inline_response_200_1":{"allOf":[{"$ref":"#/components/schemas/PaginatedData"},{"required":["headers","results"],"type":"object","properties":{"results":{"type":"array","description":"The Dotdigital Personalization client information.","items":{"$ref":"#/components/schemas/inline_response_200_1_results"}},"headers":{"$ref":"#/components/schemas/inline_response_200_1_headers"}},"description":"The accounts details."}]},"website_id_client_info_body":{"type":"object","properties":{"esp_catchall_address":{"type":"string","description":"Your ESPs catch-all email address.","format":"email","nullable":true,"example":"general@emailsim.io"},"esp_catchall_browse_address":{"type":"string","description":"Your ESPs catch-all email address.","format":"uri","nullable":true,"example":"https://all.example.com/"}},"description":"Client info changes."},"inline_response_200_2":{"required":["ok"],"type":"object","properties":{"ok":{"type":"boolean","description":"Indicates whether the call succeeded.","enum":[true]}}},"inline_response_200_3":{"allOf":[{"$ref":"#/components/schemas/PaginatedData"},{"required":["results"],"type":"object","properties":{"results":{"type":"array","description":"The admin user details.","items":{"$ref":"#/components/schemas/inline_response_200_3_results"}}},"description":"The page of data."}]},"admin_users_user_id_body":{"type":"object","properties":{"is_active":{"type":"boolean","description":"Indicates whether a user is active or not (deleted).","example":false}},"description":"Admin user changes."},"inline_response_200_4":{"allOf":[{"$ref":"#/components/schemas/PaginatedData"},{"required":["headers","results"],"type":"object","properties":{"results":{"type":"array","description":"The channel details.","items":{"$ref":"#/components/schemas/inline_response_200_4_results"}},"headers":{"$ref":"#/components/schemas/inline_response_200_4_headers"}},"description":"The channel details."}]},"inline_response_200_5":{"required":["headers","results"],"type":"object","properties":{"results":{"type":"array","description":"The channel details.","items":{"$ref":"#/components/schemas/inline_response_200_4_results"}},"headers":{"$ref":"#/components/schemas/inline_response_200_4_headers"}},"description":"The channel details."},"inline_response_200_6":{"allOf":[{"$ref":"#/components/schemas/PaginatedData"},{"required":["headers","results"],"type":"object","properties":{"results":{"type":"array","description":"The category details.","items":{"$ref":"#/components/schemas/inline_response_200_6_results"}},"headers":{"$ref":"#/components/schemas/inline_response_200_6_headers"}},"description":"The channel details."}]},"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"},"inline_response_200_1_results":{"required":["base_currency","billing","esp_catchall_address","esp_catchall_browse_address","market_sector_top_level","website_id","website_name"],"type":"object","properties":{"website_id":{"type":"string","description":"The Dotdigital Personalization website id / account id.","example":"abc1234"},"base_currency":{"description":"The base currency for the website / account as a ISO 4217 currency code","example":"GBP"},"website_name":{"type":"string","description":"The name of the website / account.","example":"Demo"},"esp_catchall_address":{"type":"string","description":"Your ESPs catch-all email address.","format":"email","nullable":true,"example":"general@emailsim.io"},"esp_catchall_browse_address":{"type":"string","description":"Your ESPs catch-all email address.","format":"uri","nullable":true,"example":"https://all.example.com/"},"market_sector_top_level":{"type":"string","description":"The market sector.","nullable":true,"example":"Entertainment"},"billing":{"type":"object","description":"Accounts billing details."}}},"inline_response_200_1_headers":{"required":["base_currency","esp_catchall_address","esp_catchall_browse_address","website_id","website_name"],"type":"object","properties":{"website_id":{"type":"string","description":"The terminolgy to use for this."},"base_currency":{"type":"string","description":"The terminolgy to use for this."},"website_name":{"type":"string","description":"The terminolgy to use for this."},"esp_catchall_address":{"type":"string","description":"The terminolgy to use for this."},"esp_catchall_browse_address":{"type":"string","description":"The terminolgy to use for this."},"market_sector_top_level":{"type":"string","description":"The terminolgy to use for this."}},"description":"Key terminolgy mappings."},"inline_response_200_3_results":{"required":["admin_user","datetime_added","email","first","is_active","last","last_activity_date","scheduled_report_frequency","scheduled_report_last_sent","telephone_primary","user_id","username","weekly_report_opt_out","your_role"],"type":"object","properties":{"user_id":{"type":"integer","description":"The unique user id.","example":2354},"first":{"type":"string","description":"First name.","nullable":true},"last":{"type":"string","description":"Last name.","nullable":true},"email":{"type":"string","description":"Email address.","format":"email","nullable":true},"datetime_added":{"type":"string","description":"Created date for user in ISO 8601 format.","format":"date-time"},"telephone_primary":{"type":"string","description":"Primary contact telephone number.","nullable":true},"your_role":{"type":"string","description":"The users role.","nullable":true},"weekly_report_opt_out":{"type":"boolean","description":"Indicates opted out of weekly report or not."},"scheduled_report_frequency":{"type":"string","description":"The frequenecy to receive reports.","nullable":true},"scheduled_report_last_sent":{"type":"string","description":"Date and time of when the last report was sent in ISO 8601 format.","format":"date-time"},"last_activity_date":{"type":"string","description":"Date and time of when the user last had activity in ISO 8601 format.","format":"date-time"},"username":{"type":"string","description":"The users username for Dotdigital Personalization."},"is_active":{"type":"boolean","description":"Indicates user is active or not (deleted)."},"admin_user":{"type":"boolean","description":"Indicates if they are an administrator or not."}}},"inline_response_200_4_results":{"required":["channel_id","ftp_field_mapping","website_id"],"type":"object","properties":{"website_id":{"type":"string","description":"The Dotdigital Personalization website id / account id.","example":"abc1234"},"ftp_field_mapping":{"type":"string","description":"FTP field name mapping details as a JSON string.","example":"{\\\"email\\\":{\\\"ftp_field_name\\\":\\\"email\\\"},\\\"eid\\\":{\\\"ftp_field_name\\\":\\\"conactId\\\"}}"},"channel_id":{"type":"string","description":"The unique channel identifier.","example":"EspDotdgitalV2:bo54k3f"}}},"inline_response_200_4_headers":{"required":["channel_id","ftp_field_mapping","website_id"],"type":"object","properties":{"website_id":{"type":"string","description":"The terminolgy to use for this."},"ftp_field_mapping":{"type":"string","description":"The terminolgy to use for this."},"channel_id":{"type":"string","description":"The terminolgy to use for this."}},"description":"Key terminolgy mappings."},"inline_response_200_6_results":{"required":["channel_id","ftp_field_mapping","website_id"],"type":"object","properties":{"_id":{"type":"string","description":"The unique category identifier.","example":"bags"},"dt":{"type":"string","description":"The date time when this category was created in UTC ISO-8601 format.","format":"date-time","example":"2024-10-28T18:15:27.176Z"},"n":{"type":"string","description":"The name of the category.","example":"Bags and accessories"},"g":{"type":"string","description":"The group the category belongs to.","nullable":true}}},"inline_response_200_6_headers":{"required":["channel_id","ftp_field_mapping","website_id"],"type":"object","properties":{"n":{"type":"string","description":"The terminolgy to use for this."},"_id":{"type":"string","description":"The terminolgy to use for this."},"dt":{"type":"string","description":"The terminolgy to use for this."}},"description":"Key terminolgy mappings."}},"responses":{"403Response":{"description":"Forbidden - Usually you are requesting data for a website you don't have access to."},"ErrorResponse":{"description":"An error occurred","content":{"application/json":{"schema":{"required":["error","ok"],"type":"object","properties":{"ok":{"type":"boolean","description":"Indicates the call failed","enum":[false]},"error":{"oneOf":[{"type":"string","description":"The reason the call errored","example":"Validation error. No folder bd8eciompb7y, unable to delete"},{"type":"object","additionalProperties":{"minItems":1,"type":"array","items":{"type":"string","example":"This field may not be null."}},"description":"Fields with issues and their errors"}]}}}}}}},"parameters":{"WebsiteId":{"name":"website_id","in":"path","description":"Website ID for the account you are posting data to.","required":true,"schema":{"type":"string"},"example":"abc123"},"FormatJson":{"name":"format","in":"query","description":"Get data in JSON format.","required":true,"schema":{"type":"string","enum":["json"]},"example":"json"},"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},"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}},"securitySchemes":{"apiTokenAuth":{"type":"apiKey","name":"x-api-key","in":"header"}}},"x-samples-languages":["curl","csharp","java","javascript","node","python","php","ruby"]}