{"openapi":"3.1.0","info":{"title":"Programs","description":"Manage automation programs and enrolments. Use this API to list all programs,\nretrieve a specific program by ID, create enrolments for contacts or address\nbooks into a program, check enrolment status, retrieve enrolments filtered by\nstatus, and download a fault report listing contacts that failed to enrol.","version":"2.0.1"},"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":[]}],"paths":{"/v2/programs/enrolments":{"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 program enrolment","deprecated":false,"description":"Creates a program enrolments for passed contacts and/or lists/address books. \n\n*Note: This happens asynchronously, use the `id` to track progress.*","operationId":"create-program-enrolment","tags":["Programs"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["programId"],"properties":{"programId":{"type":"integer","description":"The ID of the program","format":"int32"},"contacts":{"type":"array","description":"The IDs of the contacts to be enrolled into the program","maxItems":25,"minItems":1,"items":{"type":"integer","format":"int32"}},"addressBooks":{"type":"array","description":"The IDs of the address books to be enrolled into the program","maxItems":10,"items":{"type":"integer","format":"int32"}}}},"examples":{"Request Example":{"value":{"programId":1,"contacts":[3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23],"addressBooks":[3,4]},"summary":"Request Example"}}}}},"responses":{"201":{"description":"Enrolments accepted","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the enrolment."},"programId":{"type":"integer","format":"int32","description":"The ID of the program enrolled onto."},"status":{"type":"string","enum":["NotAvailableInThisVersion","Processing","Finished"],"description":"The processing status of the enrolment."},"dateCreated":{"type":"string","format":"date-time","description":"The UTC date and time the enrolment was created."},"contacts":{"type":"array","items":{"type":"integer","format":"int32"},"description":"The contact IDs included in the enrolment."},"addressBooks":{"type":"array","items":{"type":"integer","format":"int32"},"description":"The address book IDs included in the enrolment."}}},"examples":{"Result":{"summary":"Result","value":{"id":"b0ff06d6-af04-4af8-a299-51bcbad94c1c","programId":1,"status":"Processing","dateCreated":"2020-01-01 09:40:18.527000+00:00","contacts":null,"addressBooks":null}}}}}},"400":{"description":"The request was invalid. Possible reasons include: - No contacts or address books were specified (`ERROR_ENROLMENT_INVALID`) - More than 10 address books were specified (`ERROR_ADDRESSBOOK_TOOMANY`) - One or more address books were not found (`ERROR_ADDRESSBOOK_NOT_FOUND`) - One or more contacts were not found (`ERROR_CONTACT_NOT_FOUND`) - The enrolment allowance has been exceeded (`ERROR_ENROLMENT_ALLOWANCE_EXCEEDED`)\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A description of the error."}}}}}},"401":{"description":"Invalid or missing credentials."},"403":{"description":"The account does not have the Programs permission."},"404":{"description":"The specified program was not found (`ERROR_PROGRAM_NOT_FOUND`).","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A description of the error."}}},"example":{"message":"Error: ERROR_PROGRAM_NOT_FOUND"}}}},"422":{"description":"The program exists but is not active (`ERROR_PROGRAM_NOT_ACTIVE`).","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A description of the error."}}},"example":{"message":"Error: ERROR_PROGRAM_NOT_ACTIVE"}}}}}}},"/v2/programs":{"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 programs","deprecated":false,"description":"Gets a list of all the programs from your account","operationId":"get-programs","tags":["Programs"],"parameters":[{"name":"select","in":"query","description":"The number of records to select between 1 and 1000 to retrieve.","required":false,"schema":{"type":"integer","format":"int32","minimum":1,"maximum":1000,"default":1000}},{"name":"skip","in":"query","description":"The numbers of records to skip in the result set.","required":false,"schema":{"type":"integer","minimum":1,"format":"int32"}}],"responses":{"200":{"description":"The accounts programs.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","name","status","dateCreated"],"properties":{"id":{"description":"The unique ID for the program.","type":"integer","examples":[12345]},"name":{"description":"The name of the program.","type":"string","minLength":1,"maxLength":255,"examples":["Birthday program"]},"status":{"description":"The status of the program.","type":"string","enum":["Draft","Active","Deactivated","ReadOnly"],"examples":["Active"]},"dateCreated":{"description":"The creation date time in UTC ISO-8601 format.","type":"string","format":"date-time","examples":["2020-01-01 09:40:18.527000+00:00"]}}}},"examples":{"Result":{"summary":"Result","value":[{"id":1,"name":"Birthday program","status":"Active","dateCreated":"2020-01-01 09:40:18.527000+00:00"},{"id":2,"name":"Promo","status":"Deactivated","dateCreated":"2020-01-01 09:40:18.527000+00:00"},{"id":3,"name":"Visit","status":"Draft","dateCreated":"2020-01-01 09:40:18.527000+00:00"},{"id":4,"name":"Ads","status":"ReadOnly","dateCreated":"2020-01-01 09:40:18.527000+00:00"}]}}}}},"400":{"description":"Invalid paging parameters (`ERROR_PARAMETER_INVALID`). `select` must be between 1 and 1000. `skip` must not be negative.\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A description of the error."}}}}}},"401":{"description":"Invalid or missing credentials."},"403":{"description":"The account does not have the Programs permission."}}}},"/v2/programs/{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"}}],"get":{"summary":"Get program by ID","deprecated":false,"description":"Gets a program by its ID","operationId":"get-program-by-id","tags":["Programs"],"parameters":[{"name":"id","in":"path","description":"The numeric identifier of the program you want details for.","required":true,"example":0,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"The requested program details.","content":{"application/json":{"schema":{"type":"object","required":["id","name","status","dateCreated"],"properties":{"id":{"description":"The unique ID for the program.","type":"integer","examples":[12345]},"name":{"description":"The name of the program.","type":"string","minLength":1,"maxLength":255,"examples":["Birthday program"]},"status":{"description":"The status of the program.","type":"string","enum":["Draft","Active","Deactivated","ReadOnly"],"examples":["Active"]},"dateCreated":{"description":"The creation date time in UTC ISO-8601 format.","type":"string","format":"date-time","examples":["2020-01-01 09:40:18.527000+00:00"]}}},"examples":{"Result":{"summary":"Result","value":{"id":1,"name":"Birthday program","status":"Active","dateCreated":"2020-01-01 09:40:18.527000+00:00"}}}}}},"401":{"description":"Invalid or missing credentials."},"403":{"description":"The account does not have the Programs permission, or the feature is not active."},"404":{"description":"No program was found with the specified ID.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A description of the error."}}},"example":{"message":"Error: ERROR_PROGRAM_NOT_FOUND"}}}}}}},"/v2/programs/enrolments/{id}/report-faults":{"get":{"summary":"Get program enrolment report faults","deprecated":false,"description":"Gets all contacts that were not successfully enrolled, by enrolment ID.","operationId":"get-program-enrolment-report-faults","tags":["Programs"],"parameters":[{"name":"id","in":"path","description":"The enrolment ID in [GUID](url:http://guid.one/guid) format.","required":true,"example":"13bf8b50-6532-494c-8e2d-02f9bf22f93a","schema":{"type":"string"}}],"responses":{"200":{"description":"A CSV file containing all contacts that failed to enrol.","content":{"text/csv":{"schema":{"type":"string","format":"binary"},"example":"Id,Email,TelephoneNumber,Reason\n12345,contact@example.com,+441234567890,Unsubcribed\n67890,other@example.com,,AlreadyInProgram\n"}}},"400":{"description":"The enrolment is still processing and the report is not yet available.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A description of the error."}}},"example":{"message":"Error: ERROR_ENROLMENT_IS_PROCESSING"}}}},"401":{"description":"Invalid or missing credentials."},"403":{"description":"The account does not have permission to access programs."},"404":{"description":"No enrolment was found with the specified ID.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A description of the error."}}},"example":{"message":"Error: ERROR_ENROLMENT_NOT_FOUND"}}}}}}},"/v2/programs/enrolments/{enrolmentId}":{"get":{"summary":"Gets an enrolment by ID.","operationId":"getProgramEnrolmentById","tags":["Programs"],"parameters":[{"name":"enrolmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique identifier of the enrolment."}],"responses":{"200":{"description":"The enrolment matching the specified ID.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the enrolment."},"programId":{"type":"integer","format":"int32","description":"The ID of the program enrolled onto."},"status":{"type":"string","enum":["NotAvailableInThisVersion","Processing","Finished"],"description":"The processing status of the enrolment."},"dateCreated":{"type":"string","format":"date-time","description":"The UTC date and time the enrolment was created."},"contacts":{"type":"array","items":{"type":"integer","format":"int32"},"description":"The contact IDs included in the enrolment."},"addressBooks":{"type":"array","items":{"type":"integer","format":"int32"},"description":"The address book IDs included in the enrolment."}}}}}},"401":{"description":"Invalid or missing credentials."},"403":{"description":"The account does not have the Programs permission."},"404":{"description":"No enrolment was found with the specified ID (`ERROR_ENROLMENT_NOT_FOUND`).","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A description of the error."}}},"example":{"message":"Error: ERROR_ENROLMENT_NOT_FOUND"}}}}}}},"/v2/programs/enrolments/{status}":{"get":{"summary":"Gets enrolments by status.","operationId":"getProgramEnrolmentsByStatus","tags":["Programs"],"parameters":[{"name":"status","in":"path","required":true,"schema":{"type":"string","enum":["NotAvailableInThisVersion","Processing","Finished"],"description":"The processing status of the enrolment."},"description":"The enrolment status to filter by."},{"name":"select","in":"query","description":"The number of records to select between 1 and 1000 to retrieve.","required":false,"schema":{"type":"integer","format":"int32","minimum":1,"maximum":1000,"default":1000}},{"name":"skip","in":"query","description":"The numbers of records to skip in the result set.","required":false,"schema":{"type":"integer","minimum":1,"format":"int32"}}],"responses":{"200":{"description":"A list of enrolments with the specified status.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the enrolment."},"programId":{"type":"integer","format":"int32","description":"The ID of the program enrolled onto."},"status":{"type":"string","enum":["NotAvailableInThisVersion","Processing","Finished"],"description":"The processing status of the enrolment."},"dateCreated":{"type":"string","format":"date-time","description":"The UTC date and time the enrolment was created."},"contacts":{"type":"array","items":{"type":"integer","format":"int32"},"description":"The contact IDs included in the enrolment."},"addressBooks":{"type":"array","items":{"type":"integer","format":"int32"},"description":"The address book IDs included in the enrolment."}}}}}}},"400":{"description":"Invalid paging parameters (`ERROR_PARAMETER_INVALID`). `select` must be between 1 and 1000. `skip` must not be negative.\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"A description of the error."}}}}}},"401":{"description":"Invalid or missing credentials."},"403":{"description":"The account does not have the Programs permission."}}}}},"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"schemas":{"programDetails":{"type":"object","required":["id","name","status","dateCreated"],"properties":{"id":{"description":"The unique ID for the program.","type":"integer","examples":[12345]},"name":{"description":"The name of the program.","type":"string","minLength":1,"maxLength":255,"examples":["Birthday program"]},"status":{"description":"The status of the program.","type":"string","enum":["Draft","Active","Deactivated","ReadOnly"],"examples":["Active"]},"dateCreated":{"description":"The creation date time in UTC ISO-8601 format.","type":"string","format":"date-time","examples":["2020-01-01 09:40:18.527000+00:00"]}}},"ApiError":{"type":"object","properties":{"message":{"type":"string","description":"A description of the error."}}},"ApiProgramEnrolment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the enrolment."},"programId":{"type":"integer","format":"int32","description":"The ID of the program enrolled onto."},"status":{"type":"string","enum":["NotAvailableInThisVersion","Processing","Finished"],"description":"The processing status of the enrolment."},"dateCreated":{"type":"string","format":"date-time","description":"The UTC date and time the enrolment was created."},"contacts":{"type":"array","items":{"type":"integer","format":"int32"},"description":"The contact IDs included in the enrolment."},"addressBooks":{"type":"array","items":{"type":"integer","format":"int32"},"description":"The address book IDs included in the enrolment."}}},"ApiProgramEnrolmentStatus":{"type":"string","enum":["NotAvailableInThisVersion","Processing","Finished"],"description":"The processing status of the enrolment."}}}}