openapi: 3.0.3
info:
  title: MemberClicks MC Professional API
  description: >-
    The MemberClicks MC Professional API (formerly branded "Oasis") is a JSON
    REST API for interacting with an organization's association / membership
    management data - profiles, attributes, member types and statuses, groups,
    events, and continuing education credits. MemberClicks is owned by Personify.
    The API is protected by the OAuth 2.0 authorization framework: a client
    obtains an access token from /oauth/v1/token using HTTP Basic client
    credentials (Base64 clientId:clientSecret) with scope "read", "write", or
    "read write", then sends it as an Authorization: Bearer token on each request
    along with an Accept: application/json header.

    The API is hosted per organization at https://{orgId}.memberclicks.net, where
    {orgId} is the organization's MC Professional ID. There is no single global
    host and no open self-serve key issuance - client credentials are provisioned
    inside an MC Professional account under API Management. MemberClicks notes the
    API is intended for developers with technical expertise and that support does
    not assist with custom integrations.

    Endpoints for Countries, Groups, and Events are documented as API resources
    but their exact paths are behind gated (Cloudflare-protected) developer
    documentation; those paths in this document are modeled to the confirmed
    /api/v1/{resource} convention (see x-endpoint-status).
  version: '1.0'
  contact:
    name: MemberClicks by Personify
    url: https://memberclicks.com
servers:
  - url: https://{orgId}.memberclicks.net
    description: Per-organization MC Professional host
    variables:
      orgId:
        default: your-org
        description: The organization's MC Professional ID.
security:
  - oauth2: []
tags:
  - name: Authorization
    description: OAuth 2.0 token issuance.
  - name: Profiles
    description: Member / contact profile records.
  - name: Profile Search
    description: Search over the membership database.
  - name: Attributes
    description: Profile schema - built-in and custom fields.
  - name: Reference Data
    description: Member types and statuses.
  - name: Groups
    description: Group membership (modeled paths).
  - name: Events
    description: Events and registration (modeled paths).
  - name: Continuing Education
    description: Continuing education credits.
paths:
  /oauth/v1/token:
    post:
      operationId: createAccessToken
      tags:
        - Authorization
      summary: Obtain an OAuth 2.0 access token
      description: >-
        Exchanges client credentials for an access token. The client ID and
        secret are Base64-encoded as clientId:clientSecret in an HTTP Basic
        Authorization header. Request scope "read", "write", or "read write".
      security: []
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: 'Basic <Base64(clientId:clientSecret)>'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  example: client_credentials
                scope:
                  type: string
                  example: read write
      responses:
        '200':
          description: An access token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  token_type:
                    type: string
                    example: bearer
                  expires_in:
                    type: integer
                  scope:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/profile:
    get:
      operationId: listProfiles
      tags:
        - Profiles
      summary: List profiles
      description: Returns a paged list of all profiles in the organization.
      parameters:
        - $ref: '#/components/parameters/pageNumber'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: A paged list of profiles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProfile
      tags:
        - Profiles
      summary: Create a profile
      description: Creates a new profile. Requires the "write" scope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Profile'
      responses:
        '201':
          description: The created profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/profile/{profileId}:
    parameters:
      - $ref: '#/components/parameters/profileId'
    get:
      operationId: getProfile
      tags:
        - Profiles
      summary: Retrieve a profile
      description: Returns a single profile by its profileId.
      responses:
        '200':
          description: The requested profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateProfile
      tags:
        - Profiles
      summary: Update a profile
      description: Updates an existing profile's attributes. Requires the "write" scope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Profile'
      responses:
        '200':
          description: The updated profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/profile/search:
    post:
      operationId: createProfileSearch
      tags:
        - Profile Search
      summary: Create a profile search
      description: >-
        Creates a search over the membership database using attribute criteria
        and returns matching profiles (paged).
      parameters:
        - $ref: '#/components/parameters/pageNumber'
        - $ref: '#/components/parameters/pageSize'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Search criteria keyed by attribute.
              additionalProperties: true
      responses:
        '200':
          description: The matching profiles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/attribute:
    get:
      operationId: listAttributes
      tags:
        - Attributes
      summary: List attributes
      description: Lists the profile attributes (built-in and custom fields).
      responses:
        '200':
          description: A list of attributes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Attribute'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/attribute/{attributeId}/selection:
    parameters:
      - name: attributeId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the attribute.
    get:
      operationId: listAttributeSelectionOptions
      tags:
        - Attributes
      summary: List attribute selection-set options
      description: Returns the selection-set options available for a custom attribute.
      responses:
        '200':
          description: A list of selection options.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    value:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/member-type:
    get:
      operationId: listMemberTypes
      tags:
        - Reference Data
      summary: List member types
      description: Returns the organization's member types.
      responses:
        '200':
          description: A list of member types.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NamedRef'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/member-status:
    get:
      operationId: listMemberStatuses
      tags:
        - Reference Data
      summary: List member statuses
      description: Returns the organization's member statuses.
      responses:
        '200':
          description: A list of member statuses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NamedRef'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/continuing-education/credit:
    get:
      operationId: listContinuingEducationCredits
      tags:
        - Continuing Education
      summary: List continuing education credits
      description: >-
        Returns continuing education credits, optionally filtered by profileId.
        Paged with pageNumber (default 1) and pageSize (default 10, max 100).
      parameters:
        - name: profileId
          in: query
          required: false
          schema:
            type: string
          description: Filter credits to a single profile.
        - $ref: '#/components/parameters/pageNumber'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: A paged list of continuing education credits.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ContinuingEducationCredit'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/continuing-education/credit/{creditId}:
    parameters:
      - name: creditId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the continuing education credit.
    get:
      operationId: getContinuingEducationCredit
      tags:
        - Continuing Education
      summary: Retrieve a continuing education credit
      description: Returns a single continuing education credit by its ID.
      responses:
        '200':
          description: The requested credit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContinuingEducationCredit'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/country:
    get:
      operationId: listCountries
      tags:
        - Reference Data
      summary: List countries
      description: >-
        Reference lookup of countries. MODELED - the Countries resource is
        documented but the exact path is behind gated documentation.
      x-endpoint-status: modeled
      responses:
        '200':
          description: A list of countries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NamedRef'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/group:
    get:
      operationId: listGroups
      tags:
        - Groups
      summary: List groups
      description: >-
        Returns the organization's groups. MODELED - the Groups resource is
        documented (group membership is reached via a groupsUrl reference on a
        profile's group built-in attribute), but the exact path is behind gated
        documentation.
      x-endpoint-status: modeled
      responses:
        '200':
          description: A list of groups.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NamedRef'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/group/{groupId}:
    parameters:
      - name: groupId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the group.
    get:
      operationId: getGroup
      tags:
        - Groups
      summary: Retrieve a group
      description: 'Returns a single group by ID. MODELED path.'
      x-endpoint-status: modeled
      responses:
        '200':
          description: The requested group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamedRef'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/event:
    get:
      operationId: listEvents
      tags:
        - Events
      summary: List events
      description: >-
        Returns the organization's events. MODELED - an Events API resource is
        documented but its exact path is behind gated documentation.
      x-endpoint-status: modeled
      responses:
        '200':
          description: A list of events.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/event/{eventId}:
    parameters:
      - name: eventId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the event.
    get:
      operationId: getEvent
      tags:
        - Events
      summary: Retrieve an event
      description: 'Returns a single event by ID. MODELED path.'
      x-endpoint-status: modeled
      responses:
        '200':
          description: The requested event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: >-
        OAuth 2.0. Obtain a bearer token from /oauth/v1/token using HTTP Basic
        client credentials (Base64 clientId:clientSecret) with scope read, write,
        or read write.
      flows:
        clientCredentials:
          tokenUrl: https://{orgId}.memberclicks.net/oauth/v1/token
          scopes:
            read: Read access to resources.
            write: Write access to resources.
  parameters:
    profileId:
      name: profileId
      in: path
      required: true
      schema:
        type: string
      description: The ID of the profile.
    pageNumber:
      name: pageNumber
      in: query
      required: false
      schema:
        type: integer
        default: 1
      description: The 1-based page number to return.
    pageSize:
      name: pageSize
      in: query
      required: false
      schema:
        type: integer
        default: 10
        maximum: 100
      description: The number of records per page (max 100).
  responses:
    Unauthorized:
      description: Missing or invalid access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Profile:
      type: object
      description: >-
        A member / contact profile. Fields are largely attribute-driven and vary
        by organization; commonly present fields are shown here.
      properties:
        profileId:
          type: string
        memberType:
          type: string
        memberStatus:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        groupsUrl:
          type: string
          description: Reference URL to the profile's group memberships.
      additionalProperties: true
    ProfileList:
      type: object
      properties:
        totalCount:
          type: integer
        pageNumber:
          type: integer
        pageSize:
          type: integer
        profiles:
          type: array
          items:
            $ref: '#/components/schemas/Profile'
    Attribute:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        selectionUrl:
          type: string
    NamedRef:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    Event:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
      additionalProperties: true
    ContinuingEducationCredit:
      type: object
      properties:
        creditId:
          type: string
        profileId:
          type: string
        amount:
          type: number
        earnedDate:
          type: string
          format: date
      additionalProperties: true
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string