Constant Contact Account Services API

openapi: 3.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.178
  title: AppConnect V3 Account Services API
  contact:
    name: webservices@constantcontact.com
  license:
    name: Private
    url: https://www.constantcontact.com/legal/terms-of-use
servers:
- url: https://api.cc.email/v3
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
      responses:
        '200':
          description: Request successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      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
        x-example: company_logo
        schema:
          type: string
          format: csv
          enum:
          - physical_address
          - company_logo
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerPut'
        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
  /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
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      responses:
        '201':
          description: Request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountPhysicalAddress'
        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
    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
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountPhysicalAddress'
        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
  /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
      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
        schema:
          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
        schema:
          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
        schema:
          type: string
      responses:
        '200':
          description: Request successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      responses:
        '201':
          description: Request successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountEmailInput'
        description: A JSON request payload containing the new email address you want to add to the Constant Contact account.
        required: true
components:
  schemas:
    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.
    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.
    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.
    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
    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.
    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
    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: '#/components/schemas/CompanyLogo'
  securitySchemes:
    oauth2_implicit:
      type: oauth2
      flows:
        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.
            billing_data: Read or modify billing data.
          authorizationUrl: https://authz.constantcontact.com/oauth2/default/v1/authorize
    oauth2_access_code:
      type: oauth2
      flows:
        authorizationCode:
          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

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/constant-contact/refs/heads/main/openapi/constant-contact-account-services-api-openapi.yml