# Get a contact briefing

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.

Source: https://docs.itsconvo.com/api-reference/contacts/get-contact-briefing

API Base URL: https://www.itsconvo.com/api/v1

## GET /api/v1/contacts/{id}/briefing

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/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": {
    "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."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "ContactBriefing": {
        "type": "object",
        "properties": {
          "contact": {
            "$ref": "#/components/schemas/Contact"
          },
          "summary": {
            "type": "object",
            "nullable": true,
            "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",
            "format": "date-time",
            "nullable": true
          },
          "recentMeetings": {
            "type": "array",
            "description": "The most recent meetings with this contact, newest first",
            "items": {
              "type": "object",
              "properties": {
                "sessionId": {
                  "type": "string"
                },
                "title": {
                  "type": "string",
                  "nullable": true
                },
                "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"
            }
          }
        }
      },
      "Contact": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "contact_3f2b8c1e-7d4a-4c1b-9a6e-2b5d8f0c4e71"
          },
          "email": {
            "type": "string",
            "example": "sarah@northwind.com"
          },
          "displayName": {
            "type": "string",
            "nullable": true,
            "example": "Sarah Lee"
          },
          "companyDomain": {
            "type": "string",
            "nullable": true,
            "description": "The email domain; null for personal email providers",
            "example": "northwind.com"
          },
          "meetingCount": {
            "type": "integer",
            "example": 4
          },
          "firstSeenAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "lastSeenAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "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",
            "nullable": true
          },
          "priority": {
            "type": "string",
            "nullable": true,
            "enum": [
              "high",
              "medium",
              "low"
            ]
          },
          "meetingDate": {
            "type": "string",
            "format": "date-time"
          },
          "meetingTitle": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "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"
              }
            }
          }
        }
      }
    },
    "responses": {
      "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"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "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)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```