Feedback

When the API, an MCP tool, or these docs get in your way, tell us. Your integration or AI agent can report a confusing error, wrong or missing docs, or a capability it needs, right from the moment it gets stuck. We read every report, and once we've fixed the API or the docs, we mark it resolved so your agent knows when to try again.

The feedback model

  • Name
    id
    Type
    string
    Description
    Stable public UUID.
  • Name
    category
    Type
    string
    Description
    Required. One of bug (the API behaved differently from its documentation), documentation (docs or a tool description are wrong, missing, or unclear), unclear_error (an error didn't explain how to recover), missing_feature (the API can't do what you need), or other.
  • Name
    summary
    Type
    string
    Description
    Required. One sentence describing the problem, up to 200 characters.
  • Name
    details
    Type
    string
    Description
    Required, up to 5,000 characters. What you tried, what happened, and what you expected.
  • Name
    operation
    Type
    string | null
    Description
    Optional, up to 200 characters. The endpoint or MCP tool involved, such as POST /api/v1/calls/{id}/transfers or start_call_transfer.
  • Name
    request_id
    Type
    string | null
    Description
    Optional, up to 100 characters. The X-Request-Id response header of a failing request, so we can find it in our logs.
  • Name
    status
    Type
    string
    Description
    open until we've dealt with it. resolved means we fixed the API or the docs, so try again. closed means we closed it without a change, for example because it duplicates another report or the API already works as intended.
  • Name
    created_at
    Type
    string
    Description
    ISO 8601 timestamp of the report.
  • Name
    closed_at
    Type
    string | null
    Description
    When the report was resolved or closed. null while open.

Leave API keys, tokens, and personal data such as caller phone numbers out of reports. We don't need them to fix the problem.

Reports belong to the account. Any API key or OAuth token for the account can list and read them. Tokens issued to company-owned applications can't use these endpoints and receive 403. API and MCP submissions share a limit of 20 reports per account per hour; after that, submitting returns 429 with a Retry-After header.

The list can also include technical reports from your AI receptionist. These contain fixed problem codes and tool names, not caller words or contact details. Their call association stays internal and is not returned by the API or sent to Linear. Receptionist reports have a separate limit of 20 per account per hour and do not use your API submission allowance.

GET/v1/feedback

List feedback

Returns the account's 100 most recent reports, newest first. Check here before retrying something you reported.

Request

GET
/v1/feedback
curl https://app.phone.inc/api/v1/feedback -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{"feedback":[{"id":"019daef1-085e-7000-aaaa-000000000009","category":"unclear_error","operation":"POST /api/v1/calls/{id}/transfers","summary":"The 422 does not say which field is wrong","details":"Sent employee_id and got an empty errors object. Expected the response to name the missing field.","request_id":"5c1f2a7e-9b3d-4e8a-a1c2-3f4d5e6a7b8c","status":"resolved","created_at":"2026-11-09T14:03:12.481920Z","closed_at":"2026-11-10T09:41:05.120334Z"}]}

POST/v1/feedback

Submit feedback

Send category, summary, and details, plus operation and request_id when you have them. Submit once per problem, after trying the documented approach. Returns the report with status 201. Invalid or missing fields return 422.

Request

POST
/v1/feedback
curl https://app.phone.inc/api/v1/feedback -H "X-Api-Key: $PHONE_INC_API_KEY" -H 'Content-Type: application/json' -d '{"category":"unclear_error","operation":"POST /api/v1/calls/{id}/transfers","summary":"The 422 does not say which field is wrong","details":"Sent employee_id and got an empty errors object. Expected the response to name the missing field.","request_id":"5c1f2a7e-9b3d-4e8a-a1c2-3f4d5e6a7b8c"}'

Response

{"id":"019daef1-085e-7000-aaaa-000000000009","category":"unclear_error","operation":"POST /api/v1/calls/{id}/transfers","summary":"The 422 does not say which field is wrong","details":"Sent employee_id and got an empty errors object. Expected the response to name the missing field.","request_id":"5c1f2a7e-9b3d-4e8a-a1c2-3f4d5e6a7b8c","status":"open","created_at":"2026-11-09T14:03:12.481920Z","closed_at":null}

GET/v1/feedback/:id

Retrieve feedback

Returns one report and its current status. Reports from other accounts return 404.

Request

GET
/v1/feedback/:id
curl "https://app.phone.inc/api/v1/feedback/$FEEDBACK_ID" -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{"id":"019daef1-085e-7000-aaaa-000000000009","category":"unclear_error","operation":"POST /api/v1/calls/{id}/transfers","summary":"The 422 does not say which field is wrong","details":"Sent employee_id and got an empty errors object. Expected the response to name the missing field.","request_id":"5c1f2a7e-9b3d-4e8a-a1c2-3f4d5e6a7b8c","status":"resolved","created_at":"2026-11-09T14:03:12.481920Z","closed_at":"2026-11-10T09:41:05.120334Z"}