Convo Contacts API

openapi: 3.2.0
info:
  title: Convo Contacts API
  version: 1.0.0
  description: 'The Convo API gives your code the sales calls Convo records: transcripts, key points, coaching feedback, follow-up emails, contact briefings and webhooks. Build integrations with Zapier, Make or your own applications.


    ## Authentication

    Send `Authorization: Bearer convo_...` with a key created in the Convo desktop app under **Settings → Convo API**. Keys work on Starter, Professional and Enterprise plans.


    ## Plans

    | | Starter | Professional | Enterprise |

    |---|---|---|---|

    | API keys | 1 | 3 | 10 |

    | Requests per hour | 100 | 500 | 2,000 |

    | AI credits per month | 1,500 | 15,000 | 30,000 |

    | Webhooks | No | 3 | 999 |

    | Contacts (Convo Memory) | No | With Memory | With Memory |


    The desktop app''s AI features use the same credits. See https://docs.itsconvo.com/tiers.


    ## Rate limits

    Successful responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. Over the hourly limit you get `429 rate_limited` with `Retry-After`.'
  contact:
    email: ivan@itsconvo.com
  termsOfService: https://www.itsconvo.com/terms/api
servers:
- url: https://www.itsconvo.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Contacts
  description: 'Convo Memory: the people you meet, their briefings and open action items (Professional and Enterprise, with Memory enabled)'
paths:
  /api/v1/contacts:
    get:
      tags:
      - Contacts
      summary: List contacts
      description: The people Convo Memory has met in your calendar meetings, most meetings first, then most recently seen. Requires a Professional or Enterprise plan with Convo Memory enabled. Without Memory, the list is empty and `reason` is `no-brain`.
      operationId: listContacts
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 200
        description: Max results to return
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
        description: Number of results to skip
      - name: search
        in: query
        schema:
          type: string
        description: Matches email or display name, case-insensitive
      responses:
        '200':
          description: List of contacts
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  reason:
                    type: string
                    enum:
                    - no-brain
                    description: Present when Convo Memory is not enabled on the account
              example:
                data:
                - id: contact_3f2b8c1e-7d4a-4c1b-9a6e-2b5d8f0c4e71
                  email: sarah@northwind.com
                  displayName: Sarah Lee
                  companyDomain: northwind.com
                  meetingCount: 4
                  firstSeenAt: '2026-08-12T15:00:00Z'
                  lastSeenAt: '2026-09-29T14:00:00Z'
                pagination:
                  total: 37
                  limit: 50
                  offset: 0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v1/contacts/unresolved-threads:
    get:
      tags:
      - Contacts
      summary: List unresolved threads
      description: Open action items from meetings with your contacts, oldest meeting first, so the ones waiting longest come first. Items you marked resolved or dismissed are left out, and so are meetings not matched to a contact. Requires a Professional or Enterprise plan with Convo Memory enabled. Without Memory, the list is empty and `reason` is `no-brain`.
      operationId: listUnresolvedThreads
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 25
          minimum: 1
          maximum: 100
        description: Max results to return
      responses:
        '200':
          description: Open action items
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UnresolvedThread'
                  total:
                    type: integer
                    description: The number of items returned
                  reason:
                    type: string
                    enum:
                    - no-brain
                    description: Present when Convo Memory is not enabled on the account
              example:
                data:
                - sessionId: session_1773842400000
                  actionItem: Send the pilot pricing to Sarah
                  hash: 9b2f6c0d4e8a1f3b5c7d9e0a2b4c6d8e
                  meetingTitle: Northwind pilot review
                  createdAt: '2026-09-26T14:00:00Z'
                  stalenessDays: 9
                  contactId: contact_3f2b8c1e-7d4a-4c1b-9a6e-2b5d8f0c4e71
                  contactName: Sarah Lee
                  contactCompany: northwind.com
                total: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v1/contacts/{id}/briefing:
    get:
      tags:
      - Contacts
      summary: Get a contact briefing
      description: 'Everything Convo Memory has on one contact before your next call: the relationship summary, recent meetings, open action items and recent decisions. Requires a Professional or Enterprise plan with Convo Memory enabled. Without Memory, it returns 403. A contact from another account returns 404.'
      operationId: getContactBriefing
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Contact ID from List contacts
        example: contact_3f2b8c1e-7d4a-4c1b-9a6e-2b5d8f0c4e71
      - name: historyLimit
        in: query
        schema:
          type: integer
          default: 25
          minimum: 1
          maximum: 50
        description: How many recent meetings to read for the briefing
      responses:
        '200':
          description: The briefing
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ContactBriefing'
              example:
                data:
                  contact:
                    id: contact_3f2b8c1e-7d4a-4c1b-9a6e-2b5d8f0c4e71
                    email: sarah@northwind.com
                    displayName: Sarah Lee
                    companyDomain: northwind.com
                    meetingCount: 4
                    firstSeenAt: '2026-08-12T15:00:00Z'
                    lastSeenAt: '2026-09-29T14:00:00Z'
                  summary:
                    prose: Sarah leads operations at Northwind and is evaluating a three-month pilot.
                    topics: []
                    open_questions:
                    - Who signs off on the pilot budget?
                  summaryGeneratedAt: '2026-09-29T15:10:00Z'
                  recentMeetings:
                  - sessionId: session_1773842400000
                    title: Northwind pilot review
                    date: '2026-09-26T14:00:00Z'
                  openActionItems:
                  - item: Send the pilot pricing to Sarah
                    sessionId: session_1773842400000
                    hash: 9b2f6c0d4e8a1f3b5c7d9e0a2b4c6d8e
                    owner: Alex Kim
                    priority: high
                    meetingDate: '2026-09-26T14:00:00Z'
                    meetingTitle: Northwind pilot review
                  recentDecisions:
                  - Start the pilot with the support team
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Pagination:
      type: object
      properties:
        total:
          type: integer
          example: 42
        limit:
          type: integer
          example: 20
        offset:
          type: integer
          example: 0
    Contact:
      type: object
      properties:
        id:
          type: string
          example: contact_3f2b8c1e-7d4a-4c1b-9a6e-2b5d8f0c4e71
        email:
          type: string
          example: sarah@northwind.com
        displayName:
          type:
          - string
          - 'null'
          example: Sarah Lee
        companyDomain:
          type:
          - string
          - 'null'
          description: The email domain; null for personal email providers
          example: northwind.com
        meetingCount:
          type: integer
          example: 4
        firstSeenAt:
          type:
          - string
          - 'null'
          format: date-time
        lastSeenAt:
          type:
          - string
          - 'null'
          format: date-time
    BriefingActionItem:
      type: object
      properties:
        item:
          type: string
          example: Send the pilot pricing to Sarah
        sessionId:
          type: string
          example: session_1773842400000
        hash:
          type: string
          description: Identifies the action item within its conversation
        owner:
          type:
          - string
          - 'null'
        priority:
          type:
          - string
          - 'null'
          enum:
          - high
          - medium
          - low
          - null
        meetingDate:
          type: string
          format: date-time
        meetingTitle:
          type:
          - string
          - 'null'
    Error:
      type: object
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - unauthorized
              - forbidden
              - not_found
              - rate_limited
              - ai_limit_exceeded
              - validation_error
              - internal_error
            message:
              type: string
    UnresolvedThread:
      type: object
      properties:
        sessionId:
          type: string
          description: The conversation the action item came from
          example: session_1773842400000
        actionItem:
          type: string
          example: Send the pilot pricing to Sarah
        hash:
          type: string
          description: Identifies the action item within its conversation
        meetingTitle:
          type:
          - string
          - 'null'
          example: Northwind pilot review
        createdAt:
          type: string
          format: date-time
          description: When the meeting started
        stalenessDays:
          type: integer
          description: Days since the meeting
          example: 9
        contactId:
          type: string
          example: contact_3f2b8c1e-7d4a-4c1b-9a6e-2b5d8f0c4e71
        contactName:
          type:
          - string
          - 'null'
          example: Sarah Lee
        contactCompany:
          type:
          - string
          - 'null'
          description: The contact's company domain
          example: northwind.com
    ContactBriefing:
      type: object
      properties:
        contact:
          $ref: '#/components/schemas/Contact'
        summary:
          type:
          - object
          - 'null'
          description: What Convo Memory knows about this relationship, or null before a summary exists
          properties:
            prose:
              type: string
            topics:
              type: array
              items: {}
            open_questions:
              type: array
              items:
                type: string
        summaryGeneratedAt:
          type:
          - string
          - 'null'
          format: date-time
        recentMeetings:
          type: array
          description: The most recent meetings with this contact, newest first
          items:
            type: object
            properties:
              sessionId:
                type: string
              title:
                type:
                - string
                - 'null'
              date:
                type: string
                format: date-time
        openActionItems:
          type: array
          description: Up to 10 open action items from those meetings, newest meeting first
          items:
            $ref: '#/components/schemas/BriefingActionItem'
        recentDecisions:
          type: array
          description: Up to 10 decisions from those meetings, without repeats
          items:
            type: string
  headers:
    X-RateLimit-Remaining:
      schema:
        type: integer
      description: Requests left this hour
    X-RateLimit-Limit:
      schema:
        type: integer
      description: Requests allowed per hour on your plan
    X-RateLimit-Reset:
      schema:
        type: integer
      description: Unix time in seconds of the next full hour (UTC), when the count resets
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: Conversation not found
    Unauthorized:
      description: The Authorization header is missing, or the key is wrong or revoked
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: 'Missing or invalid Authorization header. Use: Bearer <api_key>'
    Forbidden:
      description: The plan doesn't allow this request, or the key only works with the MCP server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: forbidden
              message: API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing
    RateLimited:
      description: Over your hourly request limit
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          schema:
            type: integer
          description: Seconds until the next full hour, when the count resets
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded (100 requests per hour for starter plan)
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API.'