ZenZap Members API

openapi: 3.2.0
info:
  title: Zenzap External Integration Members API
  description: API for external applications to integrate with Zenzap.
  version: 2.0.0
  contact:
    name: Zenzap Support
    url: https://zenzap.co/support
servers:
- url: https://api.zenzap.co
  description: Production server
security:
- bearerAuth: []
  hmacSignature: []
- oauth2ClientCredentials: []
tags:
- name: Members
  description: Operations for retrieving organization members
paths:
  /v2/members:
    get:
      summary: List members
      description: 'Get a paginated list of all members in your organization. Only returns active members.


        Pagination:

        - `limit`: default `50`, max `100`

        - `cursor`: opaque cursor from the previous response (`nextCursor`)'
      operationId: listMembers
      security:
      - bearerAuth: []
        hmacSignature: []
      - oauth2ClientCredentials:
        - member:read
      tags:
      - Members
      parameters:
      - $ref: '#/components/parameters/XSignature'
      - $ref: '#/components/parameters/XTimestamp'
      - name: limit
        in: query
        description: 'Maximum number of members to return (default: 50, max: 100)'
        required: false
        schema:
          type: integer
          format: int64
          minimum: 1
          maximum: 100
          default: 50
      - name: cursor
        in: query
        description: Opaque cursor from a previous `nextCursor` value.
        required: false
        schema:
          type: string
      - name: emails
        in: query
        description: Comma-separated list of email addresses to filter members (e.g., john@example.com,jane@example.com)
        required: false
        schema:
          type: string
        example: john@example.com,jane@example.com
      responses:
        '200':
          description: Members list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembersListResponse'
              example:
                members:
                - id: 550e8400-e29b-41d4-a716-446655440001
                  name: John Doe
                  email: john@example.com
                  phone: '+1234567890'
                  externalId: emp-001
                  createdAt: 1699564800000
                  updatedAt: 1699564800000
                  status: Active
                - id: 550e8400-e29b-41d4-a716-446655440002
                  name: Jane Smith
                  email: jane@example.com
                  phone: '+1234567891'
                  createdAt: 1699564800000
                  updatedAt: 1699564800000
                  status: Active
                nextCursor: eyJ0IjoxNjk5NTY0ODAwMDAwLCJpZCI6InVANTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAyIn0.abc123
                hasMore: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/members/me:
    get:
      summary: Get current member
      description: Get information about the member associated with the current API key (the bot itself).
      operationId: getCurrentMember
      security:
      - bearerAuth: []
        hmacSignature: []
      - oauth2ClientCredentials:
        - member:read
      tags:
      - Members
      parameters:
      - $ref: '#/components/parameters/XSignature'
      - $ref: '#/components/parameters/XTimestamp'
      responses:
        '200':
          description: Member information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberResponse'
              example:
                id: b@660e8400-e29b-41d4-a716-446655440003
                name: API Bot
                email: bot@example.com
                phone: ''
                createdAt: 1699564800000
                updatedAt: 1699564800000
                status: Active
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    MemberResponse:
      type: object
      properties:
        id:
          type: string
          description: The member ID
          example: 550e8400-e29b-41d4-a716-446655440001
        name:
          type: string
          description: The member's name
          example: John Doe
        email:
          type: string
          format: email
          description: The member's email address
          example: john@example.com
        phone:
          type: string
          description: The member's phone number
          example: '+1234567890'
        externalId:
          type: string
          description: Optional external identifier if set by your integration
          example: emp-001
        createdAt:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds when the member was created
          example: 1699564800000
        updatedAt:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds when the member was last updated
          example: 1699564800000
        status:
          type: string
          description: The member's status
          enum:
          - Pending
          - Active
          - Deleted
          - Archived
          example: Active
    MembersListResponse:
      type: object
      properties:
        members:
          type: array
          items:
            $ref: '#/components/schemas/MemberResponse'
          description: Array of member objects
        nextCursor:
          type: string
          description: Cursor for the next page. Omitted when there are no more results.
        hasMore:
          type: boolean
          description: Whether there are more members available.
  parameters:
    XSignature:
      name: X-Signature
      in: header
      required: false
      description: "HMAC signature of the request for authentication and replay protection.\n\n**Required only when authenticating with a static API key.** If you are using an OAuth access token (issued by `POST /oauth/token`), omit this header — the JWT carries all the authentication and integrity guarantees.\n\n**Replay Protection:** The signature includes a timestamp to prevent replay attacks.\nRequests with timestamps older than 5 minutes are rejected.\n\nThe signature payload differs by HTTP method:\n- **POST/PUT/PATCH/DELETE**: HMAC-SHA256 of `{timestamp}.{body}`\n- **GET**: HMAC-SHA256 of `{timestamp}.{uri}`\n\nThe signature is calculated as:\n1. Get the current Unix timestamp in milliseconds\n2. Determine the payload:\n   - For POST/PUT/PATCH/DELETE: Use `{timestamp}.{body}` where body is the request body\n   - For GET: Use `{timestamp}.{uri}` where uri is the full request URI (e.g., `/v2/members?limit=10`)\n3. Calculate HMAC-SHA256 of the combined payload using your API secret\n4. Hex-encode the output\n5. Include the timestamp in the `X-Timestamp` header\n\nExample for GET request to `/v2/members?limit=10`:\n```\ntimestamp = 1699564800000\npayload = \"1699564800000./v2/members?limit=10\"\nsignature = HMAC-SHA256(secret, payload)\nX-Signature: hex(signature)\nX-Timestamp: 1699564800000\n```\n\nExample for POST request with body `{\"topicId\":\"123\",\"text\":\"Hello\"}`:\n```\ntimestamp = 1699564800000\npayload = '1699564800000.{\"topicId\":\"123\",\"text\":\"Hello\"}'\nsignature = HMAC-SHA256(secret, payload)\nX-Signature: hex(signature)\nX-Timestamp: 1699564800000\n```\n\nFor `multipart/form-data` requests, sign the exact raw request body bytes\n(including boundaries and file bytes) as transmitted.\n"
      schema:
        type: string
        pattern: ^[a-f0-9]{64}$
        example: a3d5f8e7c2b1d4f6a8e9c7b5d3f1a2e4b6c8d0f2e4a6b8c0d2e4f6a8b0c2d4e6
    XTimestamp:
      name: X-Timestamp
      in: header
      required: false
      description: 'Unix timestamp in milliseconds when the request was created.

        Used for replay protection — requests older than 5 minutes are rejected.


        **Required only when authenticating with a static API key.** Omit when using an OAuth access token.

        '
      schema:
        type: integer
        format: int64
        example: 1699564800000
  responses:
    InternalServerError:
      description: Internal server error
      content:
        text/plain:
          schema:
            type: string
          example: internal server error
    Unauthorized:
      description: Unauthorized - invalid or missing API token
      content:
        text/plain:
          schema:
            type: string
          example: unauthorized
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token for the request. Two flavors:


        - **Static API key** — pass your API key (the value returned as `apiKey` when the bot was created). Must be paired with `X-Signature` + `X-Timestamp` (the `hmacSignature` scheme).

        - **OAuth access token** — pass the JWT returned by `POST /oauth/token`. No signature headers are required.

        '
    hmacSignature:
      type: apiKey
      in: header
      name: X-Signature
      description: 'HMAC-SHA256 signature for request verification. Required **only** when authenticating with a static API key. Omit when using an OAuth access token.

        '
    oauth2ClientCredentials:
      type: oauth2
      description: 'OAuth 2.0 `client_credentials` grant for API-key bots. Use the `clientId` and `clientSecret` returned when the bot was created (or rotated) to mint short-lived access tokens. See [Authentication](/api-reference/authentication) for details.


        Access tokens are bearer JWTs and expire after 1 hour. There is no refresh token — re-mint with the client credentials when the token expires.

        '
      flows:
        clientCredentials:
          tokenUrl: https://api.zenzap.co/oauth/token
          scopes:
            channel:list: List topics the bot belongs to
            channel:read: Read topic metadata
            channel:write: Create/update topics and manage members
            message:read: Read messages
            message:send: Send messages
            message:write: Edit / delete / mark-delivered / mark-read messages
            reaction:write: Add and remove reactions on messages
            task:read: Read tasks
            task:write: Create / update / delete tasks
            poll:write: Create polls and cast / retract votes
            member:read: List organization members
            updates:read: Long-poll for outbound events