Constant Contact Account Services API

swagger: '2.0'
info:
  description: The Constant Contact, Inc. V3 public API, for building integrations with Constant Contact, the leading small-business email marketing platform.
  version: 3.0.149
  title: AppConnect V3 Account Services API
  contact:
    name: webservices@constantcontact.com
  license:
    name: Private
    url: https://www.constantcontact.com/legal/terms-of-use
host: api.cc.email
basePath: /v3
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Account Services
  description: Use the account endpoints and methods to get account information.
paths:
  /account/user/privileges:
    get:
      tags:
      - Account Services
      summary: GET User Privileges
      description: Use this method to return the user privileges associated with your access token as an array of objects. This method returns all user privileges, including privileges the V3 API does not currently use. Constant Contact requires specific user privileges to make requests using the V3 API. For more information, see the [User Privileges and Roles Overview](/api_guide/user_privileges.html).
      operationId: getUserPrivileges
      produces:
      - application/json
      parameters: []
      responses:
        '200':
          description: Request successful.
          schema:
            $ref: '#/definitions/UserPrivilegesResource'
        '401':
          description: The Access Token used is invalid.
        '403':
          description: Forbidden request. Your application is deactivated.
        '500':
          description: There was a problem with our internal service.
        '503':
          description: Our internal service is temporarily unavailable.
      security:
      - oauth2_implicit: []
      - oauth2_access_code: []
  /account/summary:
    get:
      tags:
      - Account Services
      summary: GET a Summary of Account Details
      description: Get account related details for a Constant Contact user account. Use the `extra_fields` query parameter to include the `company_logo` and/or `physical_address` details in the response body. For more details, see [Get Account Summary Details](/api_guide/account_details_get.html).
      operationId: getAccountById
      produces:
      - application/json
      parameters:
      - name: extra_fields
        in: query
        description: Use the `extra_fields` query parameter to include the `physical_address` and/or `company_logo` details in the response body. Use a comma separated list to include both (physical_address, company logo).
        required: false
        type: string
        format: csv
        enum:
        - physical_address
        - company_logo
        x-example: company_logo
      responses:
        '200':
          description: Request successful
          schema:
            $ref: '#/definitions/Customer'
        '400':
          description: Bad request. Either the JSON was malformed or there was a data validation error.
        '401':
          description: The Access Token used is invalid.
        '403':
          description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
        '500':
          description: There was a problem with our internal service.
        '503':
          description: Our internal service is temporarily unavailable.
      security:
      - oauth2_implicit:
        - account_read
      - oauth2_access_code:
        - account_read
      x-authorization-privileges:
      - account:read
      x-sdk-methodName: getAccountDetails
    put:
      tags:
      - Account Services
      summary: PUT (update) Account Details
      description: Use this method to update account details for a Constant Contact account, such as the email address or phone number. This PUT method provides a partial update where only valid properties that you include in the request body are updated and excluded properties are not overwritten. For more details, see [Put (update) Account Summary Details](/api_guide/account_details_put.html).
      operationId: putCustomerById
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: In the request body, specify changes to account details by including and modifying all or select `CustomerPut` properties. Changes to read-only fields (`encoded_account_id`) are ignored.
        required: true
        schema:
          $ref: '#/definitions/CustomerPut'
      responses:
        '200':
          description: Request successful
          schema:
            $ref: '#/definitions/CustomerPut'
        '400':
          description: Bad request. Either the JSON was malformed or there was a data validation error.
        '401':
          description: The Access Token used is invalid.
        '403':
          description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
        '500':
          description: There was a problem with our internal service.
        '503':
          description: Our internal service is temporarily unavailable.
      security:
      - oauth2_implicit:
        - account_update
      - oauth2_access_code:
        - account_update
      x-authorization-privileges:
      - account:update
      x-sdk-methodName: updateAccount
  /account/summary/physical_address:
    get:
      tags:
      - Account Services
      summary: GET the Physical Address for the Account
      description: Use this method to get the address where the account's organization physically resides. The physical address is required to send emails and displays on the footer of every email that is sent from the account.
      operationId: getPhysicalAddress
      produces:
      - application/json
      parameters: []
      responses:
        '200':
          description: Request successful
          schema:
            $ref: '#/definitions/AccountPhysicalAddress'
        '400':
          description: Bad request. Either the JSON was malformed or there was a data validation error.
        '401':
          description: The Access Token used is invalid.
        '403':
          description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
        '415':
          description: Unsupported Media Type.
        '500':
          description: There was a problem with our internal service.
        '503':
          description: Our internal service is temporarily unavailable.
      security:
      - oauth2_implicit:
        - account_read
      - oauth2_access_code:
        - account_read
      x-authorization-privileges:
      - account:read
      x-ctctmcp-allow: true
      x-sdk-methodName: getAccountPhysicalAddress
    post:
      tags:
      - Account Services
      summary: POST the Physical Address for the Account
      description: Use this method to add the address where the account's organization physically resides. The physical address is required to send emails and displays on the footer of every email that is sent from the account. The country (<code>country_code</code>) where the account organization resides determines whether you use the <code>state_code</code> to specify United States (<code>US</code>) and Canada (<code>CA</code>) addresses, or use the <code>state_name</code> to specify all other countries.
      operationId: addPhysicalAddress
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: Include all `AccountPhysicalAddress` properties required for the specified `country_code`. If a required property is not included or incorrectly formatted, a 400 error message is returned. If the address already exists, a 409 error message is returned.
        required: true
        schema:
          $ref: '#/definitions/AccountPhysicalAddress'
      responses:
        '201':
          description: Request successful
          schema:
            $ref: '#/definitions/AccountPhysicalAddress'
        '400':
          description: Bad request. Either the JSON was malformed or there was a data validation error.
        '401':
          description: The Access Token used is invalid.
        '403':
          description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
        '409':
          description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
        '415':
          description: Unsupported Media Type.
        '500':
          description: There was a problem with our internal service.
        '503':
          description: Our internal service is temporarily unavailable.
      security:
      - oauth2_implicit:
        - account_update
      - oauth2_access_code:
        - account_update
      x-authorization-privileges:
      - account:update
      x-ctctmcp-allow: true
    put:
      tags:
      - Account Services
      summary: PUT (update) the Physical Address for an Account
      description: 'Use this method to update the organization''s physical address for the Constant Contact user account. The physical address is required to send emails and displays on the footer of every email that is sent from the account. To get the current physical address, make a GET call to `/account/summary/physical_address`. The country (<code>country_code</code>) where the account organization resides determines whether you use the <code>state_code</code> to specify United States (<code>US</code>) and Canada (<code>CA</code>) addresses, or use the <code>state_name</code> to specify all other countries. For more details, see [Put (update) the Physical Address for the Account](/api_guide/account_address_put.html). You must have the role of Account Owner assigned to update account level details. '
      operationId: putPhysicalAddress
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: Include all `AccountPhysicalAddress` properties required for the specified `country_code` and then update only those properties that you want to change. Excluding a non-read only field from the request body removes it from the physical address.
        required: true
        schema:
          $ref: '#/definitions/AccountPhysicalAddress'
      responses:
        '200':
          description: Request successful
          schema:
            $ref: '#/definitions/AccountPhysicalAddress'
        '400':
          description: Bad request. Either the JSON was malformed or there was a data validation error.
        '401':
          description: The Access Token used is invalid.
        '403':
          description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
        '415':
          description: Unsupported Media Type.
        '500':
          description: There was a problem with our internal service.
        '503':
          description: Our internal service is temporarily unavailable.
      security:
      - oauth2_implicit:
        - account_update
      - oauth2_access_code:
        - account_update
      x-authorization-privileges:
      - account:update
      x-ctctmcp-allow: true
      x-sdk-methodName: updateAccountPhysicalAddress
  /account/emails:
    get:
      tags:
      - Account Services
      summary: GET a Collection of Account Email Addresses
      description: "Use this method to return a collection of email addresses for the account associated with your access token. When you <a href=\"https://v3.developer.constantcontact.com/api_reference/index.html#!/Email_Campaigns/createEmailCampaignUsingPOST\" target=\"_blank\">Create an Email Campaign<a/>, you must use an account email address with a `CONFIRMED` status in the email campaign `from_email` and `reply_to_email` headers.\n      \n\nUse the query parameters to filter results. You can filter using `confirm_status`, `role_code`, or `email_address`. For example, searching with `confirm_status=CONFIRMED` returns all confirmed email addresses in the account. This method only supports one query parameter at a time.\n"
      operationId: retrieveEmailAddresses
      produces:
      - application/json
      parameters:
      - name: confirm_status
        in: query
        description: 'Use the `confirm_status` query parameter to search for account emails using the email status. Possible values are `CONFIRMED` or `UNCONFIRMED`. You can also abbreviate the values of this query parameter and use `C` or `U`.

          '
        required: false
        type: string
        enum:
        - CONFIRMED
        - C
        - UNCONFIRMED
        - U
      - name: role_code
        in: query
        description: Use the `role_code` query parameter to search for account emails that have a specific role. Each each email address in an account can have multiple roles or no role. Possible values are `CONTACT`, `BILLING`, `REPLY_TO`, `JOURNALING`, or `OTHER`. You can also abbreviate the value of this query parameter and use `C`,`B`,`R`,`J`, or `O`.
        required: false
        type: string
        enum:
        - CONTACT
        - C
        - BILLING
        - B
        - JOURNALING
        - J
        - REPLY_TO
        - R
        - OTHER
        - O
      - name: email_address
        in: query
        description: Use the `email_address` query parameter to search for a specific account email address.
        required: false
        type: string
      responses:
        '200':
          description: Request successful.
          schema:
            $ref: '#/definitions/AccountEmails'
        '400':
          description: Bad request. Either the JSON was malformed or there was a data validation error.
        '401':
          description: The Access Token used is invalid.
        '403':
          description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
        '415':
          description: Unsupported Media Type.
        '500':
          description: There was a problem with our internal service.
        '503':
          description: Our internal service is temporarily unavailable.
      security:
      - oauth2_implicit:
        - account_read
      - oauth2_access_code:
        - account_read
      x-authorization-privileges:
      - account:read
      x-sdk-methodName: getAllAccountEmailAddresses
      x-ctctmcp-allow: true
    post:
      tags:
      - Account Services
      summary: POST Add an Account Email Address
      description: "Use this method to add a new email address to a Constant Contact account. If the email address you are adding already exists in the account the API will return a 409 conflict error. \n\nWhen you add a new email address to an account, Constant Contact automatically sends an email to that address with a link to confirm it. After a user clicks that link, the account email status changes from `UNCONFIRMED` to `CONFIRMED`. You can use confirmed account email addresses in the email campaign `from_email` and `reply_to_email` headers. For more use case information, see [Add an Account Email Address](/api_guide/account_post_emails.html) in the API guide. \n"
      operationId: addAccountEmailAddress
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: A JSON request payload containing the new email address you want to add to the Constant Contact account.
        required: true
        schema:
          $ref: '#/definitions/AccountEmailInput'
      responses:
        '201':
          description: Request successful.
          schema:
            $ref: '#/definitions/AccountEmailCreateResponse'
        '400':
          description: Bad request. Either the JSON was malformed or there was a data validation error.
        '401':
          description: The Access Token used is invalid.
        '403':
          description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
        '409':
          description: Conflict. The resource you are creating or updating conflicts with an existing resource.
        '415':
          description: Unsupported Media Type.
        '500':
          description: There was a problem with our internal service.
        '503':
          description: Our internal service is temporarily unavailable.
      security:
      - oauth2_implicit:
        - account_update
      - oauth2_access_code:
        - account_update
      x-authorization-privileges:
      - account:update
      x-ctctmcp-allow: true
definitions:
  AccountPhysicalAddress:
    type: object
    required:
    - address_line1
    - city
    - country_code
    properties:
      address_line1:
        type: string
        example: 123 Maple Street
        description: Line 1 of the organization's street address.
        minLength: 1
        maxLength: 80
      address_line2:
        type: string
        example: Unit 1
        description: Line 2 of the organization's street address.
        minLength: 1
        maxLength: 80
      address_line3:
        type: string
        example: Apartment 234
        description: Line 3 of the organization's street address.
        minLength: 1
        maxLength: 80
      city:
        type: string
        example: Boston
        description: The city where the organization is located.
      state_code:
        type: string
        example: MA
        description: The two letter ISO 3166-1 code for the organization's state and only used if the <code>country_code</code> is <code>US</code> or <code>CA</code>. If not, exclude this property from the request body.
        maxLength: 2
      state_name:
        type: string
        example: EXCLUDE if country_code is US.
        description: Use if the state where the organization is physically located is not in the United States or Canada. If  <code>country_code</code> is  <code>US</code> or <code>CA</code>, exclude this property from the request body.
      postal_code:
        type: string
        example: '02451'
        description: The postal code address (ZIP code) of the organization. This property is required if the <code>state_code</code> is <code>US</code> or <code>CA</code>, otherwise exclude this property from the request body.
      country_code:
        type: string
        example: US
        description: The two letter <a href='https://en.wikipedia.org/wiki/ISO_3166-1' target='_blank'>ISO 3166-1 code</a> for the organization's country.
  Customer:
    type: object
    properties:
      contact_email:
        type: string
        example: InstaPrinz@gmail.com
        description: Email addresses that are associated with the Constant Contact account owner.
      contact_phone:
        type: string
        example: '5081111212'
        description: The account owner's contact phone number (up to 25 characters in length).
        maxLength: 25
      country_code:
        type: string
        example: US
        description: The uppercase two-letter <a href='https://en.wikipedia.org/wiki/ISO_3166-1' target='_blank'>ISO 3166-1 code</a> representing the organization's country.
      encoded_account_id:
        type: string
        example: p07e1l8cdif9dl
        description: The readOnly encoded account ID that uniquely identifies the account.
        readOnly: true
      encoded_partner_id:
        type: string
        example: a37cranviy95el
        description: The encoded partner id that identifies which Constant Contact partner provisioned the account.
        readOnly: true
      first_name:
        type: string
        example: Lola
        description: The account owner's first name.
      last_name:
        type: string
        example: Zang
        description: The account owner's last name.
      organization_name:
        type: string
        example: InstaPrinz
        description: The name of the organization that is associated with this account.
      organization_phone:
        type: string
        example: 333-333-3335
        description: The phone number of the organization that is associated with this account.
      state_code:
        type: string
        example: MA
        description: The uppercase two letter <a href='https://en.wikipedia.org/wiki/ISO_3166-1' target='_blank'>ISO 3166-1 code</a> for the organization's state. This property is required if the <code>country_code</code> is US (United States).
      time_zone_id:
        type: string
        example: US/Eastern
        description: The time zone that is automatically set based on the <code>state_code</code> setting; as defined in the IANA time-zone database (see http://www.iana.org/time-zones).
      website:
        type: string
        example: http://InstaPriz4me.com
        description: The organization's website URL.
      physical_address:
        type: object
        properties:
          address_line1:
            type: string
            example: 123 Maple Street
            description: Line 1 of the organization's street address.
            minLength: 1
            maxLength: 80
          address_line2:
            type: string
            example: Unit 1
            description: Line 2 of the organization's street address.
            minLength: 1
            maxLength: 80
          address_line3:
            type: string
            example: Apartment 234
            description: Line 3 of the organization's street address.
            minLength: 1
            maxLength: 80
          city:
            type: string
            example: Boston
            description: The city where the organization is located.
          state_code:
            type: string
            example: MA
            description: The two letter ISO 3166-1 code for the organization's state and only used if the <code>country_code</code> is <code>US</code> or <code>CA</code>. If not, exclude this property from the request body.
            maxLength: 2
          state_name:
            type: string
            example: EXCLUDE if country_code is US.
            description: Use if the state where the organization is physically located is not in the United States or Canada. If  <code>country_code</code> is  <code>US</code> or <code>CA</code>, exclude this property from the request body.
          postal_code:
            type: string
            example: '02451'
            description: The postal code address (ZIP code) of the organization. This property is required if the <code>state_code</code> is <code>US</code> or <code>CA</code>, otherwise exclude this property from the request body.
          country_code:
            type: string
            example: US
            description: The two letter <a href='https://en.wikipedia.org/wiki/ISO_3166-1' target='_blank'>ISO 3166-1 code</a> for the organization's country.
        required:
        - address_line1
        - city
        - country_code
      company_logo:
        description: Used to include an existing company logo in the response body. If a company logo does not exist, nothing is returned in the response body. This property is optional.
        $ref: '#/definitions/CompanyLogo'
  AccountEmailInput:
    type: object
    properties:
      email_address:
        type: string
        example: dlang@example.com
        description: The new email address you want to add to a Constant Contact account.
        maxLength: 80
  CompanyLogo:
    type: object
    properties:
      url:
        type: string
        example: https://files.constantcontact.com/3a20c2f5701/780c1ff3-7fc6-4712-a862-ad5b6af57d38.jpg.
        description: The internal URL used to get the company logo image file hosted locally in your account's MyLibrary.
      external_url:
        type: string
        example: https://www.google.com/images/logos/google_logo_41.png.
        description: The external URL used to get the company logo image file that is hosted on an external website.
      internal_id:
        type: string
        example: ACCOUNT.IMAGE.5
        description: The internal ID used to identify the image hosted in your account's MyLibrary.
  AccountEmails:
    type: array
    items:
      type: object
      properties:
        email_address:
          type: string
          description: An email address associated with a Constant Contact account owner.
          maxLength: 80
        email_id:
          type: integer
          format: int64
          description: The unique ID for an email address in a Constant Contact account.
          minimum: 1
        confirm_status:
          type: string
          description: 'The confirmation status of the account email address. When you add a new email address to an account, Constant Contact automatically sends an email to that address with a link to confirm it. You can use any account email address with a <code>CONFIRMED</code> status to create an email campaign.

            '
        confirm_time:
          type: string
          format: date-time
          description: The date that the email address changed to <code>CONFIRMED</code> status in ISO-8601 format.
        confirm_source_type:
          type: string
          description: "Describes who confirmed the email address. Valid values are:\n  <ul>\n  <li>SITE_OWNER — The Constant Contact account owner confirmed the email address.</li>\n  <li>SUPPORT — Constant Contact support staff confirmed the email address.</li>\n  <li>FORCEVERIFY — Constant Contact confirmed the email address without sending a confirmation email.</li>\n  <li>PARTNER — A Constant Contact partner confirmed the email address.</li>\n  </ul>\n"
        roles:
          type: array
          description: 'Specifies the current role of a confirmed email address in an account. Each email address can have multiple roles or no role. Possible role values are: <ul> <li>CONTACT — The contact email for the Constant Contact account owner. Each account can only have one <code>CONTACT</code> role email.</li> <li>BILLING — The billing address for the Constant Contact account. Each account can only have one <code>BILLING</code> role email.</li> <li>JOURNALING — An email address that Constant Contact forwards all sent email campaigns to as part of the partner journaling compliance feature.</li> <li>REPLY_TO — The contact email used in the email campaign signature. Each account can only have one <code>REPLY_TO</code> role email.</li> <li>OTHER — An email address that does not fit into the other categories.</li> </ul> You can use any confirmed email address in the email campaign <code>from_email</code> and <code>reply_to_email</code> headers.

            '
          items:
            type: string
        pending_roles:
          type: array
          description: 'The planned role for an unconfirmed email address. Possible role values are: <ul> <li>CONTACT — The contact email for the Constant Contact account owner. Each account can only have one <code>CONTACT</code> role email.</li> <li>BILLING — The billing address for the Constant Contact account. Each account can only have one <code>BILLING</code> role email.</li> <li>JOURNALING — The email address that Constant Contact forwards all sent email campaigns to as part of the partner journaling compliance feature.</li> <li>REPLY_TO — The contact email used in the email campaign signature. Each account can only have one <code>REPLY_TO</code> role email. </li> <li>OTHER — An email address that does not fit into the other categories.</li> </ul>

            '
          items:
            type: string
  AccountEmailCreateResponse:
    type: object
    properties:
      email_address:
        type: string
        example: dlang@example.com
        description: An email address associated with a Constant Contact account owner.
        maxLength: 80
      email_id:
        type: integer
        format: int64
        example: 2
        description: The unique ID for an email address in a Constant Contact account.
        minimum: 1
      confirm_status:
        type: string
        example: UNCONFIRMED
        description: 'The confirmation status of the account email address. When you add a new email address to an account, Constant Contact automatically sends an email to that address with a link to confirm it. You can use any account email address with a <code>CONFIRMED</code> status to create an email campaign.

          '
  CustomerPut:
    type: object
    properties:
      contact_email:
        type: string
        example: InstaPrinz@gmail.com
        description: The confirmed email address that is associated with the account owner.
      contact_phone:
        type: string
        example: '5081111212'
        description: The account owner's contact phone number (up to 25 characters in length).
        maxLength: 25
      country_code:
        type: string
        example: US
        description: The two-letter <a href='https://en.wikipedia.org/wiki/ISO_3166-1' target='_blank'>ISO 3166-1 code</a> representing the organization's country.
      encoded_account_id:
        type: string
        example: p07e1l8cdif9dl
        description: The read only encoded account ID that uniquely identifies the account.
        readOnly: true
      first_name:
        type: string
        example: Lola
        description: The account owner's first name.
      last_name:
        type: string
        example: Zang
        description: The account owner's last name.
      organization_name:
        type: string
        example: InstaPrinz
        description: The name of the organization that is associated with this account.
      organization_phone:
        type: string
        example: 333-333-3335
        description: The phone number of the organization that is associated with this account.
      state_code:
        type: string
        example: MA
        description: The two letter <a href='https://en.wikipedia.org/wiki/ISO_3166-1' target='_blank'>ISO 3166-1 code</a> used to specify the state to associate with the account. This property is required if the <code>country_code</code> is US (United States).
      time_zone_id:
        type: string
        example: US/Eastern
        description: The time zone to use for the account; as defined in the IANA time-zone database (see http://www.iana.org/time-zones).
      website:
        type: string
        example: http://InstaPriz4me.com
        description: The organization's website URL.
  UserPrivilegesResource:
    type: array
    items:
      type: object
      properties:
        privilege_id:
          type: integer
          example: 30
          description: Identifies a user privilege in Constant Contact.
        privilege_name:
          type: string
          example: campaign:create
          description: The name of the Constant Contact user privilege.
securityDefinitions:
  oauth2_implicit:
    type: oauth2
    authorizationUrl: https://authz.constantcontact.com/oauth2/default/v1/authorize
    flow: implicit
    scopes:
      contact_data: Read or modify contact data.
      campaign_data: Read or modify email campaign data.
      account_read: Read account data.
      account_update: Modify account data.
  oauth2_access_code:
    type: oauth2
    authorizationUrl: https://authz.constantcontact.com/oauth2/default/v1/authorize
    tokenUrl: https://authz.constantcontact.com/oauth2/default/v1/token
    flow: accessCode
    scopes:
      contact_data: Read or modify contact data.
      campaign_data: Read or modify email campaign data.
      account_read: Read account data.
      account_update: Modify account data.
  ctctPartnerAuthorizer:
    description: Partner Authentication
    type: oauth2
    authorizationUrl: https://v3api-partner.auth.us-east-1.amazoncognito.com/oauth2/token
    flow: implicit
    scopes:
      v3api/general.partner: Access to general partner API methods
  api_key:
    type: apiKey
    name: x-api-key
    in: header