> ## Documentation Index > Fetch the complete documentation index at: https://docs.phonely.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update call analysis > Change what is worked out from an agent's calls after they end. Only the parts sent change. `analytics_fields` and `opportunities` are replaced whole, so a request with either needs `If-Match`; options post-call analysis names automatically change the `ETag` too. Answers with the agent's whole call analysis. Applies to calls that end from then on. ## OpenAPI ````yaml /api-reference/v1/openapi.json patch /v1/agents/{id}/call-analysis openapi: 3.1.0 info: description: >- Authenticate every request with an org API key: `Authorization: Bearer phk_…`. title: Phonely API version: '1' servers: - description: US url: https://api.us.phonely.ai - description: AU url: https://api.au.phonely.ai security: [] paths: /v1/agents/{id}/call-analysis: patch: tags: - Agents summary: Update call analysis description: >- Change what is worked out from an agent's calls after they end. Only the parts sent change. `analytics_fields` and `opportunities` are replaced whole, so a request with either needs `If-Match`; options post-call analysis names automatically change the `ETag` too. Answers with the agent's whole call analysis. Applies to calls that end from then on. operationId: update_agent_call_analysis parameters: - description: The agent's ID. in: path name: id required: true schema: description: The agent's ID. title: Id type: string - description: >- The `ETag` from your last read: the change is made only if the resource still has it, otherwise `412`. Optional, except that a change replacing a list needs it (`428` without it). in: header name: If-Match required: false schema: anyOf: - type: string - type: 'null' description: >- The `ETag` from your last read: the change is made only if the resource still has it, otherwise `412`. Optional, except that a change replacing a list needs it (`428` without it). title: If-Match - description: Optional. Must be the key's org. in: header name: Phonely-Organization required: false schema: anyOf: - type: string - type: 'null' description: Optional. Must be the key's org. title: Phonely-Organization requestBody: content: application/json: schema: $ref: '#/components/schemas/AgentCallAnalysisUpdate' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AgentCallAnalysis' description: Successful Response headers: ETag: description: >- The resource's current version. Send it as `If-Match` to change it only if it's unchanged. schema: type: string Phonely-Organization: description: The authorized organization for this request. schema: type: string '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The request is invalid: a malformed body, a bad or unknown field, or an unknown query parameter. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: The API key is missing, invalid or revoked. headers: WWW-Authenticate: description: Always `Bearer`. schema: type: string '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The key can't do this: a read-only key writing, or `Phonely-Organization` naming another org. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: The resource doesn't exist, or belongs to another organization. '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- `opportunity_analysis_not_set_up`: Opportunity Analysis settings changed before it was ever turned on. Send `opportunity_analysis.is_enabled: true` to set it up. '412': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- `If-Match` isn't the resource's current `ETag`: it changed since you read it. '428': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The change replaces a list and came without `If-Match`. Read the resource, then send its `ETag`. '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limited. Retry after the number of seconds in `Retry-After`. headers: Retry-After: description: Seconds until the request can be retried. schema: type: integer '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: An unexpected error. Contact support with the request ID. '503': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Authentication, authorization or another required service is temporarily unavailable. security: - HTTPBearer: [] components: schemas: AgentCallAnalysisUpdate: additionalProperties: false description: >- What to change. Only the parts sent change; a list sent replaces the stored one, so send `If-Match`. properties: analytics_fields: description: >- All the custom fields: ones left out are removed. Up to 20, with Opportunity Analysis counted when it is set up. items: $ref: '#/components/schemas/AnalyticsFieldUpdate' maxItems: 20 title: Analytics Fields type: array opportunity_analysis: $ref: '#/components/schemas/OpportunityAnalysisUpdate' description: Opportunity Analysis settings to change. sentiment_definitions: $ref: '#/components/schemas/SentimentDefinitionsUpdate' description: Sentiment definitions to change. title: AgentCallAnalysisUpdate type: object AgentCallAnalysis: additionalProperties: false description: What is worked out from each of an agent's calls after it ends. properties: agent_id: description: The agent's ID. title: Agent Id type: string analytics_fields: description: The custom fields filled in for each call. items: $ref: '#/components/schemas/AnalyticsField' title: Analytics Fields type: array object: const: agent_call_analysis default: agent_call_analysis description: The type of this object, always `agent_call_analysis`. title: Object type: string opportunity_analysis: anyOf: - $ref: '#/components/schemas/OpportunityAnalysis' - type: 'null' description: >- What callers were after when they dropped off. `null` when it was never turned on. sentiment_definitions: $ref: '#/components/schemas/SentimentDefinitions' description: How call sentiment is judged. required: - object - agent_id - analytics_fields - opportunity_analysis - sentiment_definitions title: AgentCallAnalysis type: object ErrorResponse: additionalProperties: false description: The body of every `/v1` error. properties: error: $ref: '#/components/schemas/Error' description: What went wrong. required: - error title: ErrorResponse type: object AnalyticsFieldUpdate: additionalProperties: false properties: description: anyOf: - type: string - type: 'null' description: >- What the field captures, up to 500 characters, used to fill it in for each call. title: Description id: anyOf: - type: string - type: 'null' description: >- The field's ID: lowercase letters, digits and underscores. Leave it out for a new field to get one made from its label. Keep an existing field's ID, or it becomes a new field. title: Id is_enabled: default: true description: Whether the field is filled in for new calls. title: Is Enabled type: boolean label: description: >- The name shown in the web app, up to 80 characters, unique among the fields. title: Label type: string options: description: The options to pick from, up to 50. None for `number`. items: $ref: '#/components/schemas/AnalyticsFieldOptionUpdate' maxItems: 50 title: Options type: array type: description: >- `category` picks one option, `multi_category` picks any number, and `number` is a value. Known values: `category`, `multi_category`, `number`. More can be added, so handle values you don't recognize. title: Type type: string x-extensible-enum: - category - multi_category - number required: - label - type title: AnalyticsFieldUpdate type: object OpportunityAnalysisUpdate: additionalProperties: false properties: is_ai_naming_enabled: anyOf: - type: boolean - type: 'null' description: Whether new opportunities are named automatically as they come up. title: Is Ai Naming Enabled is_enabled: anyOf: - type: boolean - type: 'null' description: >- Whether calls that end before the conversation reaches its goal are analyzed. Turning it on the first time sets it up with every call analyzed and new opportunities named automatically. title: Is Enabled opportunities: anyOf: - items: $ref: '#/components/schemas/AnalyticsFieldOptionUpdate' maxItems: 50 type: array - type: 'null' description: >- All the opportunities, up to 50: ones left out are removed. Opportunities named automatically since your last read make your `ETag` stale (`412`): read again and resend. title: Opportunities sample_rate: anyOf: - type: number - type: 'null' description: >- The share of those calls analyzed: `0.1`, `0.25`, `0.5`, `0.75` or `1`. title: Sample Rate title: OpportunityAnalysisUpdate type: object SentimentDefinitionsUpdate: additionalProperties: false properties: negative: anyOf: - type: string - type: 'null' description: >- What makes a call negative. `null` goes back to the standard definition. title: Negative neutral: anyOf: - type: string - type: 'null' description: >- What makes a call neutral. `null` goes back to the standard definition. title: Neutral positive: anyOf: - type: string - type: 'null' description: >- What makes a call positive. `null` goes back to the standard definition. title: Positive title: SentimentDefinitionsUpdate type: object AnalyticsField: additionalProperties: false properties: description: anyOf: - type: string - type: 'null' description: >- What the field captures, used to fill it in for each call. `null` when there is none. title: Description id: description: The field's ID, as it appears in a call's analysis. title: Id type: string is_enabled: description: Whether the field is filled in for new calls. title: Is Enabled type: boolean label: description: The name shown in the web app. title: Label type: string options: description: The options to pick from. Empty for `number`. items: $ref: '#/components/schemas/AnalyticsFieldOption' title: Options type: array type: description: >- `category` picks one option, `multi_category` picks any number, and `number` is a value. Known values: `category`, `multi_category`, `number`. More can be added, so handle values you don't recognize. title: Type type: string x-extensible-enum: - category - multi_category - number required: - id - label - description - type - is_enabled - options title: AnalyticsField type: object OpportunityAnalysis: additionalProperties: false properties: is_ai_naming_enabled: description: Whether new opportunities are named automatically as they come up. title: Is Ai Naming Enabled type: boolean is_enabled: description: >- Whether calls that end before the conversation reaches its goal are analyzed. title: Is Enabled type: boolean opportunities: description: The opportunities found so far. items: $ref: '#/components/schemas/AnalyticsFieldOption' title: Opportunities type: array sample_rate: description: The share of those calls analyzed, from 0 to 1. title: Sample Rate type: number required: - is_enabled - sample_rate - is_ai_naming_enabled - opportunities title: OpportunityAnalysis type: object SentimentDefinitions: additionalProperties: false properties: negative: anyOf: - type: string - type: 'null' description: What makes a call negative. `null` uses the standard definition. title: Negative neutral: anyOf: - type: string - type: 'null' description: What makes a call neutral. `null` uses the standard definition. title: Neutral positive: anyOf: - type: string - type: 'null' description: What makes a call positive. `null` uses the standard definition. title: Positive required: - positive - neutral - negative title: SentimentDefinitions type: object Error: additionalProperties: false properties: code: description: >- What went wrong, stable and machine-readable. Known values: `validation_failed`, `invalid_cursor`, `invalid_api_key`, `invalid_user_token`, `user_unavailable`, `insufficient_access`, `organization_mismatch`, `forbidden`, `not_found`, `method_not_allowed`, `conflict`, `agent_limit_reached`, `agent_too_large`, `sms_setup_required`, `opportunity_analysis_not_set_up`, `precondition_failed`, `payload_too_large`, `unsupported_media_type`, `precondition_required`, `rate_limited`, `internal_error`, `knowledge_processing_failed`, `bad_gateway`, `service_unavailable`, `gateway_timeout`. More can be added, so handle values you don't recognize. title: Code type: string x-extensible-enum: - validation_failed - invalid_cursor - invalid_api_key - invalid_user_token - user_unavailable - insufficient_access - organization_mismatch - forbidden - not_found - method_not_allowed - conflict - agent_limit_reached - agent_too_large - sms_setup_required - opportunity_analysis_not_set_up - precondition_failed - payload_too_large - unsupported_media_type - precondition_required - rate_limited - internal_error - knowledge_processing_failed - bad_gateway - service_unavailable - gateway_timeout details: description: One entry per problem field. Empty when the error has none. items: $ref: '#/components/schemas/ErrorDetail' title: Details type: array message: description: For people. Wording can change; branch on `code`. title: Message type: string request_id: anyOf: - type: string - type: 'null' description: Also in the `X-Request-Id` header. Quote it to support. title: Request Id required: - code - message - details - request_id title: Error type: object AnalyticsFieldOptionUpdate: additionalProperties: false properties: description: anyOf: - type: string - type: 'null' description: >- What the option means, up to 1024 characters, used to decide whether a call matches it. title: Description id: anyOf: - type: string - type: 'null' description: >- The option's ID: lowercase letters, digits and underscores. Leave it out for a new option to get one made from its label. Keep an existing option's ID, or it becomes a new option. title: Id is_enabled: default: true description: Whether calls are matched against this option. title: Is Enabled type: boolean label: description: >- The name shown in the web app, up to 80 characters, unique among the options. title: Label type: string required: - label title: AnalyticsFieldOptionUpdate type: object AnalyticsFieldOption: additionalProperties: false properties: description: anyOf: - type: string - type: 'null' description: >- What the option means, used to decide whether a call matches it. `null` when there is none. title: Description id: description: The option's ID, as it appears in a call's analysis. title: Id type: string is_enabled: description: Whether calls are matched against this option. title: Is Enabled type: boolean label: description: The name shown in the web app. title: Label type: string required: - id - label - description - is_enabled title: AnalyticsFieldOption type: object ErrorDetail: additionalProperties: false properties: field: description: >- The field the issue is about, as sent: `agent_id`, `limit`. Empty when none. title: Field type: string issue: description: >- What is wrong with the field. Known values: `required`, `unknown_field`, `invalid_json`, `invalid_type`, `invalid_value`, `out_of_range`, `invalid_cursor`, `read_only_field`. More can be added, so handle values you don't recognize. title: Issue type: string x-extensible-enum: - required - unknown_field - invalid_json - invalid_type - invalid_value - out_of_range - invalid_cursor - read_only_field message: description: 'For people: what is wrong with this field.' title: Message type: string required: - field - issue - message title: ErrorDetail type: object securitySchemes: HTTPBearer: description: 'An org API key: `Authorization: Bearer phk_…`' scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.