Customermates Members API

openapi: 3.2.0
info:
  title: Customermates Members API
  description: API for Customermates application
  version: 1.0.0
servers:
- url: /api
  description: API Server
tags:
- name: Members
paths:
  /v1/members/invite:
    post:
      operationId: inviteMembers
      summary: Invite members by email
      description: 'Sends a workspace invitation email with the workspace''s invitation link to each address, 1 to 20 per call; duplicate addresses receive one email. An invited person joins with no role until an administrator assigns one through POST /v1/members/update. Returns how many emails were sent, how many the email service did not accept (failed) and their addresses (failedEmails); share the link from POST /v1/members/invite-link with those people instead. Sending the same invitation to an address again within 24 hours does not email it twice. Requires: Users & Roles Create.'
      tags:
      - Members
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                emails:
                  minItems: 1
                  maxItems: 20
                  type: array
                  items:
                    type: string
                    format: email
                    pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
              required:
              - emails
            examples:
              default:
                value:
                  emails:
                  - new.colleague@example.com
      responses:
        '200':
          description: The invitations were handed to the email service; failed counts the ones it did not accept.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sent:
                    type: number
                  failed:
                    type: number
                  failedEmails:
                    type: array
                    items:
                      type: string
                      format: email
                      pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                required:
                - sent
                - failed
                - failedEmails
                additionalProperties: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '401':
          description: Not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '403':
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '422':
          description: 'Unavailable: the request is valid but cannot be served right now (error.kind unavailable)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '429':
          description: 'Rate limited: retry later (error.kind rate_limit)'
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '500':
          description: Unexpected error. The body is not a structured failure.
  /v1/members/invite-link:
    post:
      operationId: getInvitationLink
      summary: Get the workspace invitation link
      description: 'Returns the workspace invitation link and when it expires, as the Share link tab of the Invite dialog shows it. The link is reused until it expires after 7 days; the first call after that creates a new one. Anyone who opens it can register and joins with status Waiting for approval and no role. Requires: Users & Roles Create.'
      tags:
      - Members
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
              additionalProperties: false
            examples:
              default:
                value: {}
      responses:
        '200':
          description: The current invitation link.
          content:
            application/json:
              schema:
                type: object
                properties:
                  link:
                    type: string
                    description: 'The workspace invitation link: anyone who opens it before expiresAt can request to join.'
                  expiresAt:
                    type: string
                required:
                - link
                - expiresAt
                additionalProperties: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '401':
          description: Not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '403':
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '422':
          description: 'Unavailable: the request is valid but cannot be served right now (error.kind unavailable)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '429':
          description: 'Rate limited: retry later (error.kind rate_limit)'
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '500':
          description: Unexpected error. The body is not a structured failure.
  /v1/members/update:
    post:
      operationId: updateMember
      summary: Change a member's role or status
      description: 'Saves another member''s profile, role and status in one call, as the members settings page and the MCP update_member action do. Name the member by userId or email (both must match when you send both) and send the fields to change; omitted fields keep their current values. status inactive deactivates the member and frees their seat, active reactivates them; a member waiting for approval needs a status, and a member without a role needs a roleId. An unknown member or roleId answers 404. You cannot update your own membership, the only active membership of the last Customermates platform operator cannot be deactivated, and the workspace always keeps an active member with a system role (roleSystemRequired). Requires: Users & Roles Edit.'
      tags:
      - Members
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                firstName:
                  type: string
                  minLength: 1
                lastName:
                  type: string
                  minLength: 1
                status:
                  type: string
                  enum:
                  - active
                  - inactive
                avatarUrl:
                  anyOf:
                  - anyOf:
                    - type: string
                      format: uri
                    - type: string
                      const: ''
                  - type: 'null'
                roleId:
                  type: string
                  format: uuid
                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                userId:
                  type: string
                  format: uuid
                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            examples:
              default:
                value:
                  userId: 00000000-0000-4000-8000-000000000002
                  status: inactive
              byEmail:
                value:
                  email: new.colleague@example.com
                  firstName: Grace
                  lastName: Hopper
                  roleId: 00000000-0000-4000-8000-000000000003
      responses:
        '200':
          description: The saved member.
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    format: email
                    pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  firstName:
                    type: string
                    minLength: 1
                  lastName:
                    type: string
                    minLength: 1
                  status:
                    type: string
                    enum:
                    - active
                    - inactive
                  avatarUrl:
                    anyOf:
                    - anyOf:
                      - type: string
                        format: uri
                      - type: string
                        const: ''
                    - type: 'null'
                  roleId:
                    type: string
                    format: uuid
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                required:
                - email
                - firstName
                - lastName
                - status
                - avatarUrl
                - roleId
                additionalProperties: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '401':
          description: Not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '403':
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '422':
          description: 'Unavailable: the request is valid but cannot be served right now (error.kind unavailable)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '429':
          description: 'Rate limited: retry later (error.kind rate_limit)'
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '500':
          description: Unexpected error. The body is not a structured failure.
  /v1/members/remove:
    post:
      operationId: removeMember
      summary: Remove a member from the workspace
      description: 'Removes another member from this workspace, as Remove from workspace in the members settings and the MCP remove_member action do. Name the member by userId or email (both must match when you send both). Works for active, inactive and waiting-for-approval members; removing a member waiting for approval declines the request. The member''s status becomes inactive and they are shown as left (a declined request is no longer listed), their API keys and MCP connections for this workspace stop working, the mailboxes and LinkedIn accounts they connected here are disconnected, their routines pause, and an active member''s seat is freed. The member gets an email that they were removed; a declined request sends none. Records they own and their history stay. To come back they ask to join again with an invitation link, and an admin has to approve the request. Returns the removed member and the status they had. You cannot remove yourself (leave the workspace in the app instead), the only active membership of the last Customermates platform operator, a member who already left, or the last active member with the Admin role. Requires: Users & Roles Edit.'
      tags:
      - Members
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                  format: uuid
                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                email:
                  type: string
                  format: email
                  pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
            examples:
              default:
                value:
                  userId: 00000000-0000-4000-8000-000000000002
              byEmail:
                value:
                  email: former.colleague@example.com
      responses:
        '200':
          description: The member was removed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: string
                    format: uuid
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  email:
                    type: string
                    format: email
                    pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  previousStatus:
                    type: string
                    enum:
                    - active
                    - inactive
                    - pendingAuthorization
                required:
                - userId
                - email
                - previousStatus
                additionalProperties: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '401':
          description: Not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '403':
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '422':
          description: 'Unavailable: the request is valid but cannot be served right now (error.kind unavailable)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '429':
          description: 'Rate limited: retry later (error.kind rate_limit)'
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponseSchema'
        '500':
          description: Unexpected error. The body is not a structured failure.
components:
  schemas:
    StructuredErrorResponseSchema:
      type: object
      properties:
        error:
          type: object
          properties:
            kind:
              type: string
              enum:
              - validation
              - authentication
              - authorization
              - not_found
              - conflict
              - rate_limit
              - unavailable
            issues:
              minItems: 1
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  path:
                    type: array
                    items:
                      anyOf:
                      - type: string
                      - type: number
                  message:
                    type: string
                  customCode:
                    type: string
                    enum:
                    - recordNotFound
                    - recordTypeNotFound
                    - recordConfigurationInvalid
                    - recordSavedViewIncompatible
                    - chatThreadRequired
                    - webhookTriggerRequired
                    - recordValueInvalid
                    - recordQueryFieldUnknown
                    - recordMarkedTextChanged
                    - recordSublistNested
                    - serviceBusy
                    - recordValueRequired
                    - recordValueTypeMismatch
                    - recordNumberInvalid
                    - recordDateInvalid
                    - recordDateRangeInvalid
                    - recordOptionInvalid
                    - recordMemberInactive
                    - recordSchemaChanged
                    - recordVersionChanged
                    - recordWritePaused
                    - recordReadOnlyField
                    - recordIdempotencyConflict
                    - recordIdUnavailable
                    - recordRelationConflict
                    - recordDependencies
                    - recordCalculationBudget
                    - recordOperationFailed
                    - recordOperationNotFound
                    - recordOperationSettled
                    - recordTransactionEnded
                    - recordProtected
                    - recordMeasureDateIntervalInvalid
                    - addressLookupUnavailable
                    - addressLookupRateLimited
                    - recordAddressCandidateInvalid
                    - recordAddressCountryInvalid
                    - recordAddressPostalCodeInvalid
                    - recordAddressRegionInvalid
                    - recordFileUnavailable
                    - recordFileContentInvalid
                    - recordFileLinkInvalid
                    - recordFileNameInvalid
                    - recordFileNotFound
                    - recordFileTooLarge
                    - recordFileUploadIncomplete
                    - storageQuotaExceeded
                    - trashItemNotFound
                    - trashChanged
                    - agentApprovalUnavailable
                    - agentConversationNotFound
                    - agentLimitReached
                    - agentServiceUnavailable
                    - routineAiWorkPaused
                    - agentModelUnavailable
                    - agentTurnAlreadyRunning
                    - notAuthenticated
                    - userInactive
                    - emailVerificationRequired
                    - permissionDenied
                    - insufficientPermissions
                    - demoMode
                    - apiKeyMinExpiration
                    - apiKeyMaxExpiration
                    - apiKeyNameLength
                    - apiKeyNotFound
                    - emailMismatch
                    - enterpriseCheckoutUnavailable
                    - billingPortalUnavailable
                    - passwordMismatch
                    - passwordInvalid
                    - dataViewNotFound
                    - dataViewNameMismatch
                    - dataViewAllNameImmutable
                    - dataViewUpdateEmpty
                    - emailNotVerified
                    - invalidCredentials
                    - invalidCallbackUrl
                    - emailAlreadyExists
                    - invalidEmail
                    - invalidJsonBody
                    - salesNavigatorRequiresLinkedin
                    - linkedinInboxUnavailable
                    - socialActionRequiresSocialAccount
                    - salesNavigatorNotAvailable
                    - invalidUrl
                    - emailLinkColourInvalid
                    - legalNoticeNotDelivered
                    - termsNotAgreed
                    - privacyAcknowledgementRequired
                    - invalidChannelValue
                    - channelAlreadyLinked
                    - customFieldInvalidDate
                    - widgetKindImmutable
                    - widgetDisplayTypeUnsupported
                    - widgetLayoutChanged
                    - widgetLayoutOverlap
                    - widgetLayoutTooSmall
                    - userNotFound
                    - userSelfAdminUpdateForbidden
                    - userRoleRequired
                    - userStatusRequired
                    - memberReferenceRequired
                    - roleSystemRequired
                    - userPlatformOperatorStatusForbidden
                    - workspaceNotFound
                    - workspaceLastAdmin
                    - workspaceCreationUnavailable
                    - workspaceChanged
                    - workspaceDeleteAdminRequired
                    - workspaceDeleteBillingActive
                    - workspaceDeleteBillingUnverified
                    - workspaceDeleteChannelsFailed
                    - workspaceDeleteCheckoutPending
                    - workspaceDeleteInvoiced
                    - workspaceDeleteNotCreator
                    - workspaceDeletePlatformOperator
                    - workspaceInvitationInvalid
                    - workspaceLimitReached
                    - workspacePlanRequired
                    - workspaceMemberLeft
                    - workspaceMemberLastAdmin
                    - workspaceMemberPlatformOperator
                    - workspaceMemberRemoveSelf
                    - widgetNotFound
                    - webhookNotFound
                    - webhookDeliveryNotFound
                    - webhookDeliveryInProgress
                    - webhookDisabled
                    - wikiPageNotFound
                    - wikiPageConflict
                    - wikiNotEmpty
                    - wikiPagePinned
                    - wikiGuideExists
                    - wikiWhenToUseRequired
                    - wikiPageUpdateEmpty
                    - wikiProcedureNeedsSteps
                    - wikiProposalNotFound
                    - wikiProposalReviewed
                    - wikiProposalStale
                    - workspaceSetupAnswerInvalid
                    - workspaceSetupConflict
                    - workspaceSetupNotFound
                    - workspaceSetupUnavailable
                    - workspaceSlugTaken
                    - threadNotFound
                    - messageNotFound
                    - emailFolderNotFound
                    - emailFolderNotMovable
                    - emailFolderMoveUnsupported
                    - calendarEventNotFound
                    - calendarNotFound
                    - calendarExportIncomplete
                    - calendarSubscriptionLimitReached
                    - calendarSubscriptionNotFound
                    - connectedAccountNotFound
                    - connectedAccountEmailChangeRequired
                    - roleNotFound
                    - routineNotFound
                    - roleAssignedCannotDelete
                    - roleNameTaken
                    - roleSelfEditForbidden
                    - roleSystemImmutable
                    - roleAccessPresetInUse
                    - routineAdminRequired
                    - routineDeleteHasRunningRun
                    - routineEditNotOwner
                    - routineOwnerIneligible
                    - routineRunCursorInvalid
                    - routineRunNotOwner
                    - routineRunNowRequiresSchedule
                    - routineTestRequiresEnabled
                    - routineScheduleInvalid
                    - routineScheduleRequired
                    - routineScheduleTooFrequent
                    - routineTimeZoneInvalid
                    - routineLimitReached
                    - routinesRequireCloud
                    - routineTriggerEventsRequired
                    - invalidFilterField
                    - invalidGroupingField
                    - invalidFilterOperator
                    - invalidFilterValue
                    - invalidSortField
                    - filterBetweenInvalidArrayLength
                    - notesInvalidFormat
                    - notesExceedsMaxLength
                    - mustNotBeBlank
                    - mustNotContainNullChars
                    - duplicateWebhookEvents
                    - webhookEventsRequired
                    - duplicateWebhookHeaders
                    - webhookHeaderNameInvalid
                    - webhookHeaderNameReserved
                    - webhookHeaderValueInvalid
                    - webhookHeadersTooMany
                    - webhookHeadersTooLarge
                    - webhookBodyTemplateInvalid
                    - webhookHeadersRequireHttps
                    - webhookEndpointInvalid
                    - webhookUrlTooLong
                    - messageContentRequired
                    - sendEmailTargetRequired
                    - emailRecipientsRequired
                    - draftToRecipientsLocked
                    - draftMessageNotFound
                    - draftChanged
                    - draftRecipientsChanged
                    - draftTargetMismatch
                    - draftSendInProgress
                    - draftSendOutcomeUnknown
                    - draftAlreadySent
                    - draftThreadNotSent
                    - subjectRequired
                    - duplicateOutboundSuppressed
                    - inmailSubjectRequired
                    - inmailSignatureRequired
                    - linkedinProductRequiresLinkedin
                    - linkedinProductUnavailable
                    - socialPostsRequireSocialAccount
                    - unipileResourceNotFound
                    - unipileProviderError
                    - unipileInvalidRequest
                    - unipileRateLimit
                    - unipileServiceUnavailable
                    - unipileFeatureUnavailable
                    - unipileRequestTimeout
                    - unipileDisconnectedAccount
                    - unipileUnknown
                    - unipileProviderRejected
                    - unipileAccountRestricted
                    - unipileSendUnconfirmed
                    - unipileSendOutcomeUnknown
                    - operatorConflict
                    - operatorCreditPrecision
                    - operatorCreditNonzero
                    - operatorCreditPeriodInvalid
                    - operatorUnavailable
                    - operatorAllowanceMissing
                    - operatorConnectedAccountsActive
                    - operatorTrialEndRequired
                    - generic
                  entitlement:
                    type: string
                required:
                - code
                - path
                - message
                additionalProperties: false
            retryable:
              type: boolean
          required:
          - kind
          - issues
          additionalProperties: false
      required:
      - error
      additionalProperties: false
      description: Structured failure. error.kind classifies the HTTP status. Each issue carries its JSON path and, when one applies, a stable customCode such as recordVersionChanged or recordSchemaChanged. Messages are localized prose for people.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key authentication. Create an API key in your user profile and include it in the x-api-key header.
    fileLinkToken:
      type: apiKey
      in: query
      name: token
      description: Signed token of one file, part of an upload URL or a downloadUrl. It acts for the person who requested it for 15 minutes.