{"openapi":"3.1.0","info":{"title":"Lists / Address books","version":"2.0.0"},"x-readme":{"headers":[],"explorer-enabled":true,"proxy-enabled":true},"x-readme-fauxas":true,"x-samples-languages":["curl","csharp","java","javascript","node","python","php","ruby"],"externalDocs":{"description":"Learn more about Dotdigital APIs","url":"https://developer.dotdigital.com"},"servers":[{"url":"https://{region}-api.dotdigital.com","variables":{"region":{"default":"r1","enum":["r1","r2","r3"],"description":"The Dotdigital region id your account belongs to"}}}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}}},"paths":{"/v2/address-books/{id}/campaigns":{"parameters":[{"in":"header","name":"x-ddg-integration-token","required":false,"description":"If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.","schema":{"type":"string","pattern":"/^(?:\\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\\}{0,1})$/","example":"5a96bc79-19a7-4544-973b-e2da0c9136f9"}}],"get":{"summary":"Get campaigns sent to address book or segment","deprecated":false,"description":"Gets any campaigns that have been sent to an address book or a segment","operationId":"get-campaigns-sent-to-address-book-or-segment","tags":["Lists / Address books"],"parameters":[{"name":"id","in":"path","description":"The ID of the address book or segment","required":true,"example":0,"schema":{"type":"integer","format":"int32"}},{"name":"select","in":"query","description":"he select parameter requires a number between 1 and 1000 (0 is not a valid number). You may only select a maximum of 1000 results in a single request. This parameter goes within the URL.","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"skip","in":"query","description":"The skip parameter should be used in tandem with the select parameter when wanting to iterate through a whole data set. If you want to select the next 1000 records you should set the select parameter to 1000 and the skip parameter to 1000, which will return records 1001 to 2000. You should continue to do this until 0 records are returned to retrieve the whole data set.","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","default":0,"examples":[1]},"name":{"type":"string","examples":["Monthly newsletter Dec 2015"]},"subject":{"type":"string","examples":["Monthly newsletter"]},"fromName":{"type":"string","examples":["Company name"]},"fromAddress":{"type":"object","properties":{"id":{"type":"integer","default":0,"examples":[1]},"email":{"type":"string","examples":["demo@apiconnector.com"]}}},"htmlContent":{},"plainTextContent":{},"replyAction":{"type":"string","examples":["Unset"]},"replyToAddress":{},"isSplitTest":{"type":"boolean","default":true,"examples":[false]},"status":{"type":"string","examples":["Sent"]}}}},"examples":{"Result":{"summary":"Result","value":[{"id":1,"name":"Monthly newsletter Dec 2015","subject":"Monthly newsletter","fromName":"Company name","fromAddress":{"id":1,"email":"demo@apiconnector.com"},"htmlContent":null,"plainTextContent":null,"replyAction":"Unset","replyToAddress":null,"isSplitTest":false,"status":"Sent"},{"id":4,"name":"New product promotion","subject":"New product!","fromName":"Company name","fromAddress":{"id":1,"email":"demo@apiconnector.com"},"htmlContent":null,"plainTextContent":null,"replyAction":"WebMailForward","replyToAddress":"demo@apiconnector.com","isSplitTest":false,"status":"Sent"}]}}}}}}}},"/v2/address-books":{"parameters":[{"in":"header","name":"x-ddg-integration-token","required":false,"description":"If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.","schema":{"type":"string","pattern":"/^(?:\\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\\}{0,1})$/","example":"5a96bc79-19a7-4544-973b-e2da0c9136f9"}}],"post":{"summary":"Create list","deprecated":false,"description":"Creates an list / address book","operationId":"create-address-book","tags":["Lists / Address books"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The name of the address book. (max 128 characters)","maxLength":128},"visibility":{"type":"string","description":"All address books are created as 'Private' by default but you can set it as 'Public' upon creation should you wish to.","default":"Private","enum":["Private","Public"]}}}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","default":0,"examples":[1]},"name":{"type":"string","examples":["My Address Book"]},"visibility":{"type":"string","examples":["Public"]},"contacts":{"type":"integer","default":0,"examples":[0]}}},"examples":{"Result":{"summary":"Result","value":{"id":1,"name":"My Address Book","visibility":"Public","contacts":0}}}}}}}},"get":{"summary":"Get lists","deprecated":false,"description":"Gets all lists / address books","operationId":"get-address-books","tags":["Lists / Address books"],"parameters":[{"name":"select","in":"query","description":"The number of records to select between 1 and 1000","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"skip","in":"query","description":"The numbers of records to skip in the result set","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","default":0,"examples":[1]},"name":{"type":"string","examples":["Address book 1"]},"visibility":{"type":"string","examples":["Private"]},"contacts":{"type":"integer","default":0,"examples":[5]}}}},"examples":{"Result":{"summary":"Result","value":[{"id":1,"name":"Address book 1","visibility":"Private","contacts":5},{"id":2,"name":"Address book 2","visibility":"Public","contacts":7},{"id":3,"name":"Address book 3","visibility":"Private","contacts":7},{"id":4,"name":"Address book 4","visibility":"Public","contacts":6}]}}}}}}}},"/v2/address-books/{id}":{"parameters":[{"in":"header","name":"x-ddg-integration-token","required":false,"description":"If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.","schema":{"type":"string","pattern":"/^(?:\\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\\}{0,1})$/","example":"5a96bc79-19a7-4544-973b-e2da0c9136f9"}}],"delete":{"summary":"Delete list","deprecated":false,"description":"Deletes an list / address book by id","operationId":"delete-address-book","tags":["Lists / Address books"],"parameters":[{"name":"id","in":"path","description":"The ID of the list / address book","required":true,"example":0,"schema":{"type":"integer","format":"int32"}}],"responses":{"204":{"description":"204","content":{"application/json":{"schema":{"type":"object","properties":{}},"examples":{"Result":{"summary":"Result","value":{}}}}}}}},"put":{"summary":"Update list","deprecated":false,"description":"Updates an list / address book by id","operationId":"update-address-book","tags":["Lists / Address books"],"parameters":[{"name":"id","in":"path","description":"The ID of the address book","required":true,"example":0,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The name of the address book. (max 128 characters)"},"visibility":{"type":"string","description":"All address books are created as 'Private' by default but you can set it as 'Public' upon creation should you wish to.","default":"Private","enum":["Private","Public"]}}}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","default":0,"examples":[1]},"name":{"type":"string","examples":["My Updated Address Book"]},"visibility":{"type":"string","examples":["Private"]},"contacts":{"type":"integer","default":0,"examples":[0]}}},"examples":{"Result":{"summary":"Result","value":{"id":1,"name":"My Updated Address Book","visibility":"Private","contacts":0}}}}}}}},"get":{"summary":"Get list","deprecated":false,"description":"This operation retrieves an list / address book by its id","operationId":"get-address-book","tags":["Lists / Address books"],"parameters":[{"name":"id","in":"path","description":"The ID of the list / address book","required":true,"example":0,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","default":0,"examples":[2]},"name":{"type":"string","examples":["Address book 2"]},"visibility":{"type":"string","examples":["Private"]},"contacts":{"type":"integer","default":0,"examples":[5]}}},"examples":{"Result":{"summary":"Result","value":{"id":2,"name":"Address book 2","visibility":"Private","contacts":5}}}}}}}}},"/v2/address-books/private":{"parameters":[{"in":"header","name":"x-ddg-integration-token","required":false,"description":"If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.","schema":{"type":"string","pattern":"/^(?:\\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\\}{0,1})$/","example":"5a96bc79-19a7-4544-973b-e2da0c9136f9"}}],"get":{"summary":"Get private lists","deprecated":false,"description":"Gets all private lists / address books","operationId":"get-private-address-books","tags":["Lists / Address books"],"parameters":[{"name":"limit","in":"query","description":"The number of records to select between 1 and 1000","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"skip","in":"query","description":"The numbers of records to skip in the result set","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","default":0,"examples":[2]},"name":{"type":"string","examples":["Address book 2"]},"visibility":{"type":"string","examples":["Private"]},"contacts":{"type":"integer","default":0,"examples":[5]}}}},"examples":{"Result":{"summary":"Result","value":[{"id":2,"name":"Address book 2","visibility":"Private","contacts":5},{"id":3,"name":"Address book 3","visibility":"Private","contacts":7}]}}}}}}}},"/v2/address-books/public":{"parameters":[{"in":"header","name":"x-ddg-integration-token","required":false,"description":"If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.","schema":{"type":"string","pattern":"/^(?:\\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\\}{0,1})$/","example":"5a96bc79-19a7-4544-973b-e2da0c9136f9"}}],"get":{"summary":"Get public lists","deprecated":false,"description":"Gets all public lists / address books","operationId":"get-public-address-books","tags":["Lists / Address books"],"parameters":[{"name":"select","in":"query","description":"The number of records to select between 1 and 1000","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"skip","in":"query","description":"The numbers of records to skip in the result set","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","default":0,"examples":[2]},"name":{"type":"string","examples":["Address book 2"]},"visibility":{"type":"string","examples":["Private"]},"contacts":{"type":"integer","default":0,"examples":[5]}}}},"examples":{"Result":{"summary":"Result","value":[{"id":2,"name":"Address book 2","visibility":"Private","contacts":5},{"id":3,"name":"Address book 3","visibility":"Private","contacts":7}]}}}}}}}},"/v2/address-books/{id}/contacts/unsubscribed-since/{date}":{"parameters":[{"in":"header","name":"x-ddg-integration-token","required":false,"description":"If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.","schema":{"type":"string","pattern":"/^(?:\\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\\}{0,1})$/","example":"5a96bc79-19a7-4544-973b-e2da0c9136f9"}}],"get":{"summary":"Get unsubscribed from list since date","deprecated":false,"description":"Gets a list of contacts who have unsubscribed since a given date from a given list / address book","operationId":"get-unsubscribed-contacts-from-address-book-since-date","tags":["Lists / Address books"],"parameters":[{"name":"id","in":"path","description":"The id of the list / address book","required":true,"example":0,"schema":{"type":"integer","format":"int32"}},{"name":"date","in":"path","description":"The date from which any unsubscribed contacts are returned in [ISO 8601 format](https://www.w3.org/TR/xmlschema-2/#dateTime)","required":true,"example":"","schema":{"type":"string","format":"date"}},{"name":"select","in":"query","description":"The number of records to select between 1 and 1000","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"skip","in":"query","description":"The numbers of records to skip in the result set","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{}},"examples":{"Result":{"summary":"Result","value":"[\n{\n\"suppressedContact\": {\n\"id\": 1,\n\"email\": \"nelson.redeker@example.com\",\n\"optInType\": \"Unknown\",\n\"emailType\": \"PlainText\",\n\"dataFields\": null,\n\"status\": \"Unsubscribed\"\n},\n\"dateRemoved\": \"2020-01-01T09:40:18.527Z\",\n\"reason\": \"Unsubscribed\"\n},\n{\n\"suppressedContact\": {\n\"id\": 25,\n\"email\": \"terry.mccarthy@example.com\",\n\"optInType\": \"VerifiedDouble\",\n\"emailType\": \"Html\",\n\"dataFields\": null,\n\"status\": \"Unsubscribed\"\n},\n\"dateRemoved\": \"2020-01-01T09:40:18.527Z\",\n\"reason\": \"Unsubscribed\"\n},\n]"}}}}}}}},"/v2/address-books/{id}/contacts/unsubscribe":{"parameters":[{"in":"header","name":"x-ddg-integration-token","required":false,"description":"If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.","schema":{"type":"string","pattern":"/^(?:\\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\\}{0,1})$/","example":"5a96bc79-19a7-4544-973b-e2da0c9136f9"}}],"post":{"summary":"Unsubscribe contact from list","deprecated":false,"description":"Unsubscribes contact from a given list / address book","operationId":"unsubscribe-contact-from-address-book","tags":["Lists / Address books"],"parameters":[{"name":"id","in":"path","description":"The id of the list / address book","required":true,"example":0,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","description":"The email address of the contact to be unsubscribed"}}}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"suppressedContact":{"type":"object","properties":{"id":{"type":"integer","default":0,"examples":[123456]},"email":{"type":"string","examples":["example@emailsim.io"]},"optInType":{"type":"string","examples":["Unknown"]},"emailType":{"type":"string","examples":["Html"]},"dataFields":{},"status":{"type":"string","examples":["Subscribed"]}}},"dateRemoved":{"type":"string","examples":["2025-07-23T11:01:55.433Z"]},"reason":{"type":"string","examples":["Unsubscribed"]}}},"examples":{"Result":{"summary":"Result","value":{"suppressedContact":{"id":123456,"email":"example@emailsim.io","optInType":"Unknown","emailType":"Html","dataFields":null,"status":"Subscribed"},"dateRemoved":"2025-07-23T11:01:55.433Z","reason":"Unsubscribed"}}}}}}}}},"/v2/address-books/{id}/contacts/resubscribe":{"parameters":[{"in":"header","name":"x-ddg-integration-token","required":false,"description":"If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.","schema":{"type":"string","pattern":"/^(?:\\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\\}{0,1})$/","example":"5a96bc79-19a7-4544-973b-e2da0c9136f9"}}],"post":{"summary":"Resubscribe contact to list","deprecated":false,"description":"Resubscribes a previously unsubscribed contact to a given list / address book","operationId":"resubscribe-contact-to-address-book","tags":["Lists / Address books"],"parameters":[{"name":"id","in":"path","description":"The id of the list / address book","required":true,"example":0,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["unsubscribedContact"],"properties":{"unsubscribedContact":{"type":"object","description":"The details of the contact to be resubscribed","required":["email"],"properties":{"email":{"type":"string","description":"The email address of the contact"},"dataFields":{"type":"array","description":"The data fields for the contact","items":{"properties":{"key":{"type":"string","description":"The key name"},"value":{"type":"string","description":"The value associated with the key"}},"required":["key","value"],"type":"object"}}}},"preferredLocale":{"type":"string","description":"The language code for the language you would like the resubscribe request email to be sent to the contact in","enum":["cs-CS","da-DA","de-DE","el-EL","en-EN","es-ES","es","fi-FI","fr-FR","hu-HU","it-IT","nl-NL","nb-NO","pl-PL","pt-PT","ru-RU","se-SE","sk-SK","tr-TR","zh-CN"]},"returnUrlToUseIfChallenged":{"type":"string","description":"The URL you would like to redirect challenged contacts to after they have completed their resubscription"}}},"examples":{"Request Example":{"value":{"unsubscribedContact":{"email":"john.smith@emailsim.io","dataFields":[{"key":"FIRSTNAME","value":"Nelson"},{"key":"LASTNAME","value":"Redeker"}]},"preferredLocale":"de-DE","returnUrlToUseIfChallenged":"https://www.mywebsite.com/news"},"summary":"Request Example"}}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"contact":{"type":"object","properties":{"id":{"type":"integer","default":0,"examples":[23]},"email":{"type":"string","examples":["john.smith@emailsim.io"]},"optInType":{"type":"string","examples":["Unknown"]},"emailType":{"type":"string","examples":["PlainText"]},"dataFields":{},"status":{"type":"string","examples":["Unsubscribed"]}}},"status":{"type":"string","examples":["ContactChallenged"]}}},"examples":{"Result":{"summary":"Result","value":{"contact":{"id":23,"email":"john.smith@emailsim.io","optInType":"Unknown","emailType":"PlainText","dataFields":null,"status":"Unsubscribed"},"status":"ContactChallenged"}}}}}}}}},"/v2/address-books/{id}/contacts/resubscribe-with-no-challenge":{"parameters":[{"in":"header","name":"x-ddg-integration-token","required":false,"description":"If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.","schema":{"type":"string","pattern":"/^(?:\\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\\}{0,1})$/","example":"5a96bc79-19a7-4544-973b-e2da0c9136f9"}}],"post":{"summary":"Resubscribe contact to list with no challenge","deprecated":false,"description":"Resubscribes a previously unsubscribed contact to a specific list / address book without sending a challenge email","operationId":"resubscribe-contact-to-address-book-with-no-challenge","tags":["Lists / Address books"],"parameters":[{"name":"id","in":"path","description":"The ID of the list / address book, which needs to be included within the URL","required":true,"example":0,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"unsubscribedContact":{"type":"object","description":"The email address of the unsubscribed contact, which needs to be included within the request body","required":["email"],"properties":{"email":{"type":"string","description":"The email address of the contact"},"dataFields":{"type":"array","description":"The data fields for the contact","items":{"properties":{"key":{"type":"string","description":"The key name"},"value":{"type":"string","description":"The value associated with the key"}},"required":["key","value"],"type":"object"}}}}}}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"contact":{"type":"object","properties":{"id":{"type":"integer","default":0,"examples":[24]},"email":{"type":"string","examples":["john.smith@emailsim.io"]},"optInType":{"type":"string","examples":["Unknown"]},"emailType":{"type":"string","examples":["PlainText"]},"dataFields":{},"status":{"type":"string","examples":["Subscribed"]}}},"status":{"type":"string","examples":["ContactAdded"]}}},"examples":{"Result":{"summary":"Result","value":{"contact":{"id":24,"email":"john.smith@emailsim.io","optInType":"Unknown","emailType":"PlainText","dataFields":null,"status":"Subscribed"},"status":"ContactAdded"}}}}}}}}},"/v2/address-books/{addressBookId}/contacts/{contactId}":{"parameters":[{"in":"header","name":"x-ddg-integration-token","required":false,"description":"If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.","schema":{"type":"string","pattern":"/^(?:\\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\\}{0,1})$/","example":"5a96bc79-19a7-4544-973b-e2da0c9136f9"}}],"delete":{"summary":"Delete contact from list","deprecated":false,"description":"Deletes a contact from a given list / address book","operationId":"delete-contact-from-address-book","tags":["Lists / Address books"],"parameters":[{"name":"addressBookId","in":"path","description":"The id of the list / address book","required":true,"example":0,"schema":{"type":"integer","format":"int32"}},{"name":"contactId","in":"path","description":"The id of the contact","required":true,"example":0,"schema":{"type":"integer","format":"int32"}}],"responses":{"204":{"description":"204","content":{"application/json":{"schema":{"type":"object","properties":{}},"examples":{"Result":{"summary":"Result","value":{}}}}}}}}},"/v2/address-books/{addressBookId}/contacts/delete":{"parameters":[{"in":"header","name":"x-ddg-integration-token","required":false,"description":"If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.","schema":{"type":"string","pattern":"/^(?:\\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\\}{0,1})$/","example":"5a96bc79-19a7-4544-973b-e2da0c9136f9"}}],"post":{"summary":"Delete contacts from list","deprecated":false,"description":"Deletes multiple contacts from an list / address book","operationId":"delete-contacts-from-address-book","tags":["Lists / Address books"],"parameters":[{"name":"addressBookId","in":"path","description":"The id of the list / address book","required":true,"example":0,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["RAW_BODY"],"properties":{"RAW_BODY":{"type":"array","description":"The IDs of the contacts that need deleting from the address book","items":{"type":"integer","format":"int32"}}}},"examples":{"Request Example":{"value":[684095989,1182927244],"summary":"Request Example"}}}}},"responses":{"202":{"description":"202","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","examples":["13e7b388-2060-4f58-b3dc-2885badf80ee"]},"status":{"type":"string","examples":["Started"]}}},"examples":{"Result":{"summary":"Result","value":{"id":"13e7b388-2060-4f58-b3dc-2885badf80ee","status":"Started"}}}}}}}}},"/v2/address-books/{addressBookId}/contacts/delete-all":{"parameters":[{"in":"header","name":"x-ddg-integration-token","required":false,"description":"If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.","schema":{"type":"string","pattern":"/^(?:\\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\\}{0,1})$/","example":"5a96bc79-19a7-4544-973b-e2da0c9136f9"}}],"post":{"summary":"Delete all contacts from list","deprecated":false,"description":"Deletes all contacts from a given list / address book","operationId":"delete-all-contacts-from-address-book","tags":["Lists / Address books"],"parameters":[{"name":"addressBookId","in":"path","description":"The id of the list / address book","required":true,"example":0,"schema":{"type":"integer","format":"int32"}}],"responses":{"202":{"description":"202","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","examples":["13e7b388-2060-4f58-b3dc-2885badf80ee"]},"status":{"type":"string","examples":["Started"]}}},"examples":{"Result":{"summary":"Result","value":{"id":"13e7b388-2060-4f58-b3dc-2885badf80ee","status":"Started"}}}}}}}}},"/v2/address-books/{addressBookId}/contacts/with-preference/{preferenceId}":{"parameters":[{"in":"header","name":"x-ddg-integration-token","required":false,"description":"If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.","schema":{"type":"string","pattern":"/^(?:\\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\\}{0,1})$/","example":"5a96bc79-19a7-4544-973b-e2da0c9136f9"}}],"get":{"summary":"Get contacts opted into a preference and an address book","deprecated":false,"description":"Gets contacts who are opted into a given preference and a given address book","operationId":"get-contacts-opted-into-a-preference-and-an-address-book","tags":["Lists / Address books"],"parameters":[{"name":"addressBookId","in":"path","description":"The ID of the address book to which contacts must belong.","required":true,"example":0,"schema":{"type":"integer","format":"int32"}},{"name":"preferenceId","in":"path","description":"The ID of the preference to which contacts must be opted in.","required":true,"example":0,"schema":{"type":"integer","format":"int32"}},{"name":"minContactID","in":"query","description":"The minimum contact ID to query on, starting from 0","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{}},"examples":{"Result":{"summary":"Result","value":"[\n{\n\"id\": 279,\n\"email\": \"joe.bloggs@emailsim.io\"\n},\n{\n\"id\": 99123,\n\"email\": \"joanne.bloggs@emailsim.io\"\n},\n]"}}}}}}}},"/v2/address-books/{addressBookId}/contacts/with-preference/{preferenceId}/opt-ins-since/{date}":{"parameters":[{"in":"header","name":"x-ddg-integration-token","required":false,"description":"If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.","schema":{"type":"string","pattern":"/^(?:\\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\\}{0,1})$/","example":"5a96bc79-19a7-4544-973b-e2da0c9136f9"}}],"get":{"summary":"Get contacts with modified preference opt-in in address book since date","deprecated":false,"description":"Gets the top 1000 contacts who have had a specific preference opt-in status modified since a given date, in a given address book","operationId":"get-contacts-with-modified-preference-opt-in-in-address-book-since-date","tags":["Lists / Address books"],"parameters":[{"name":"addressBookId","in":"path","description":"The ID of the address book to which contacts must belong.","required":true,"example":0,"schema":{"type":"integer","format":"int32"}},{"name":"preferenceId","in":"path","description":"The ID of the preference to which contacts must be opted in.","required":true,"example":0,"schema":{"type":"integer","format":"int32"}},{"name":"date","in":"path","description":"The earliest date that returned contacts must have modified their opt-in status for the preference in [ISO 8601 format](https://www.w3.org/TR/xmlschema-2/#dateTime)","required":true,"example":"","schema":{"type":"string","format":"date"}},{"name":"minContactID","in":"query","description":"The minimum contact ID to query on, starting from 0","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"contact":{"type":"object","properties":{"id":{"type":"integer","default":0,"examples":[5]},"email":{"type":"string","examples":["darryl.netherland@example.com"]},"optInType":{"type":"string","examples":["Single"]},"emailType":{"type":"string","examples":["Html"]},"dataFields":{},"status":{"type":"string","examples":["Subscribed"]}}},"marketingPreferenceOptIns":{"type":"array","items":{"type":"object","properties":{"marketingPreferenceId":{"type":"integer","default":0,"examples":[2]},"addressBookId":{"type":"integer","default":0,"examples":[421]},"isOptedIn":{"type":"boolean","default":true,"examples":[false]},"dateModifed":{"type":"string","examples":["2020-01-01T09:40:18.527Z"]}}}}}}},"examples":{"Result":{"summary":"Result","value":[{"contact":{"id":5,"email":"darryl.netherland@example.com","optInType":"Single","emailType":"Html","dataFields":null,"status":"Subscribed"},"marketingPreferenceOptIns":[{"marketingPreferenceId":2,"addressBookId":421,"isOptedIn":false,"dateModifed":"2020-01-01T09:40:18.527Z"}]},{"contact":{"id":12,"email":"dora.judge@example.com","optInType":"Unknown","emailType":"Html","dataFields":null,"status":"Subscribed"},"marketingPreferenceOptIns":[{"marketingPreferenceId":5,"addressBookId":395,"isOptedIn":true,"dateModifed":"2020-01-01T09:40:18.527Z"}]}]}}}}}}}},"/v2/address-books/{id}/contacts/import/with-merge-option/{mergeOption}":{"parameters":[{"in":"header","name":"x-ddg-integration-token","required":false,"description":"If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.","schema":{"type":"string","pattern":"/^(?:\\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\\}{0,1})$/","example":"5a96bc79-19a7-4544-973b-e2da0c9136f9"}}],"post":{"summary":"Bulk import contacts in address book with merge option","deprecated":false,"description":"Bulk creates, or bulk updates, contacts in an address book with merge option","operationId":"bulk-import-contacts-in-address-book-with-merge-option","tags":["Lists / Address books"],"parameters":[{"name":"id","in":"path","description":"The address book id","required":true,"example":0,"schema":{"type":"integer","format":"int32"}},{"name":"mergeOption","in":"path","description":"For Merge options: you can update all data fields by entering ''0'', avoid updating data fields that contain blank values by entering ''1'', or you can choose not to update data fields that contain values by entering ''2''","required":true,"example":"","schema":{"type":"string","enum":["0","1","2"]}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["filename","data"],"properties":{"filename":{"type":"string","description":"The filename of the file being uploaded"},"data":{"type":"string","description":"The [base64](https://en.wikipedia.org/wiki/Base64) data for the file"}}}}}},"responses":{"202":{"description":"202","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","examples":["af4ac4bc-e1e7-4817-8a66-73fb59e91ce6"]},"status":{"type":"string","examples":["NotFinished"]}}},"examples":{"Result":{"summary":"Result","value":{"id":"af4ac4bc-e1e7-4817-8a66-73fb59e91ce6","status":"NotFinished"}}}}}}},"x-readme":{"code-samples":[{"language":"text","code":"Email,Firstname,Lastname,Postcode,Customfield_1,Customfield_2\nuser1@example.com,Bob,Smith,LXS123,Yes,100\nuser2@example.com,Frank,Smith,LXS121,No,200\nuser3@example.com,Sarah,Smith,LXS124,Yes,300","name":"CSV Example"}],"samples-languages":["text"]}}}}}