> ## 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. # Set a call's outcome > Set a call's post-call outcome: what happened, a number for it, and data to attach. Send only the fields to change: `null` clears one, and `custom_metadata` replaces the whole object. A new `custom_outcome` joins the agent's list of post-call outcomes, which the web app's analytics and filters use. Answers with the updated call. The same calls can be updated as read with `GET /v1/calls/{id}`. To find a call by the customer's number, list the agent's calls with `customer_phone_number` and `limit=1`: the newest call comes first. ## OpenAPI ````yaml /api-reference/v1/openapi.json patch /v1/calls/{id} 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/calls/{id}: patch: tags: - Calls summary: Set a call's outcome description: >- Set a call's post-call outcome: what happened, a number for it, and data to attach. Send only the fields to change: `null` clears one, and `custom_metadata` replaces the whole object. A new `custom_outcome` joins the agent's list of post-call outcomes, which the web app's analytics and filters use. Answers with the updated call. The same calls can be updated as read with `GET /v1/calls/{id}`. To find a call by the customer's number, list the agent's calls with `customer_phone_number` and `limit=1`: the newest call comes first. operationId: update_call parameters: - description: The call's ID. in: path name: id required: true schema: description: The call's ID. title: Id type: string - 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/CallUpdate' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Call' description: Successful Response headers: 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. '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: CallUpdate: additionalProperties: false description: >- The post-call outcome to set. Send only the fields to change; `null` clears one. properties: custom_metadata: anyOf: - additionalProperties: true type: object - type: 'null' description: >- Any JSON object to attach to the call, up to 32 KB. It replaces the whole object stored before. An object the call can't store, such as one nested more than 20 levels deep or with a list directly inside a list, is a 400. title: Custom Metadata custom_outcome: anyOf: - maxLength: 255 minLength: 1 type: string - type: 'null' description: >- The outcome, in your own words, such as `Booked`. 1 to 255 characters. It's added to the agent's list of post-call outcomes. title: Custom Outcome custom_outcome_value: anyOf: - type: number - type: 'null' description: A number to go with the outcome, such as a deal value. title: Custom Outcome Value title: CallUpdate type: object Call: additionalProperties: false description: >- One call with its call analysis. The transcript and recording have their own endpoints. properties: action_items: anyOf: - items: type: string type: array - type: 'null' description: Action items the conversation left for the customer. title: Action Items agent_id: description: The agent that handled the call. title: Agent Id type: string business_phone_number: anyOf: - type: string - type: 'null' description: >- The Phonely number on the call, as recorded: usually E.164, such as `+14155550100`. title: Business Phone Number campaign_id: anyOf: - type: string - type: 'null' description: The outbound campaign that placed the call, if any. title: Campaign Id custom_metadata: anyOf: - additionalProperties: true type: object - type: 'null' description: >- Data your integration attached to the call, as sent. `null` when none. title: Custom Metadata custom_outcome: anyOf: - type: string - type: 'null' description: >- The post-call outcome your integration set, such as `Booked`. `null` when none. title: Custom Outcome custom_outcome_value: anyOf: - type: number - type: 'null' description: >- A number your integration set with the outcome, such as a deal value. `null` when none. title: Custom Outcome Value customer_name: anyOf: - type: string - type: 'null' description: The name the customer gave. `null` when they gave none. title: Customer Name customer_phone_number: anyOf: - type: string - type: 'null' description: >- The customer on the call, as recorded: usually E.164, but `Anonymous` or a SIP address when they withheld their number. `null` for web calls. title: Customer Phone Number duration_seconds: anyOf: - type: number - type: 'null' description: >- How long the call lasted. `null` when not recorded, as for a call that never connected. title: Duration Seconds ended_at: anyOf: - format: date-time type: string - type: 'null' description: When the call ended. `null` while it is still in progress. title: Ended At ended_reason: anyOf: - type: string - type: 'null' description: >- Why the call ended. `null` when it was not recorded. Known values: `assistant_ended_call`, `assistant_forwarded_call`, `customer_ended_call`, `hangup_during_warm_transfer`, `max_duration_reached`, `silence_timeout`, `no_answer`, `user_busy`, `call_failed`, `voicemail`, `no_one_engaged`, `pre_screen_hangup`, `greeting_hangup`, `pre_greeting_hangup`, `greeting_timeout`, `pre_call_rejected`, `pipeline_error`, `unknown_error`, `unsure`. More can be added, so handle values you don't recognize. title: Ended Reason x-extensible-enum: - assistant_ended_call - assistant_forwarded_call - customer_ended_call - hangup_during_warm_transfer - max_duration_reached - silence_timeout - no_answer - user_busy - call_failed - voicemail - no_one_engaged - pre_screen_hangup - greeting_hangup - pre_greeting_hangup - greeting_timeout - pre_call_rejected - pipeline_error - unknown_error - unsure follow_up_reason: anyOf: - type: string - type: 'null' description: Why a person should follow up, and who. title: Follow Up Reason id: description: The call's ID. title: Id type: string is_follow_up_needed: anyOf: - type: boolean - type: 'null' description: Whether a person should follow up with the customer. title: Is Follow Up Needed key_points: anyOf: - items: type: string type: array - type: 'null' description: Key points from the conversation. title: Key Points long_summary: anyOf: - type: string - type: 'null' description: A longer summary from call analysis, up to six sentences. title: Long Summary mentioned_date: anyOf: - format: date type: string - type: 'null' description: A date mentioned on the call, such as an appointment. title: Mentioned Date mentioned_email: anyOf: - type: string - type: 'null' description: An email address mentioned on the call. title: Mentioned Email mentioned_time: anyOf: - type: string - type: 'null' description: A time mentioned on the call, as `HH:mm` (24-hour). title: Mentioned Time object: const: call default: call description: The type of this object, always `call`. title: Object type: string outcome: anyOf: - type: string - type: 'null' description: The call's outcome, as the agent's call analysis labels it. title: Outcome purpose: anyOf: - type: string - type: 'null' description: The call's purpose, in a few words. title: Purpose sentiment: anyOf: - type: string - type: 'null' description: >- The customer's sentiment: from call analysis, unless someone changed it in the web app. Known values: `positive`, `negative`, `neutral`, `unsure`. More can be added, so handle values you don't recognize. title: Sentiment x-extensible-enum: - positive - negative - neutral - unsure started_at: anyOf: - format: date-time type: string - type: 'null' description: When the call started, or was queued if it never connected. title: Started At status: description: >- Where the call is in its lifecycle. Known values: `completed`, `ended`, `in_progress`, `in_warm_transfer`, `queued`, `queueing`, `redial_scheduled`, `cancelled`, `dnc`, `failed`, `transferred_sold`, `transferred_not_sold`, `transferred_pending_sale`, `rev_share_pending_qualification`, `transferred_busy`, `transferred_no_answer`, `transferred_failed`. More can be added, so handle values you don't recognize. title: Status type: string x-extensible-enum: - completed - ended - in_progress - in_warm_transfer - queued - queueing - redial_scheduled - cancelled - dnc - failed - transferred_sold - transferred_not_sold - transferred_pending_sale - rev_share_pending_qualification - transferred_busy - transferred_no_answer - transferred_failed summary: anyOf: - type: string - type: 'null' description: A short summary from call analysis. title: Summary type: anyOf: - type: string - type: 'null' description: >- How the call happened. Known values: `inbound_phone_call`, `outbound_phone_call`, `warm_transfer`, `web_call`, `web_chat`, `messaging_session`, `call_and_messaging`, `pay_per_call`, `unknown`. More can be added, so handle values you don't recognize. title: Type x-extensible-enum: - inbound_phone_call - outbound_phone_call - warm_transfer - web_call - web_chat - messaging_session - call_and_messaging - pay_per_call - unknown unanswered_questions: anyOf: - items: type: string type: array - type: 'null' description: Questions the agent didn't answer. title: Unanswered Questions warm_transfer_started_at: anyOf: - format: date-time type: string - type: 'null' description: When a warm transfer to a person began. `null` when there was none. title: Warm Transfer Started At required: - object - id - agent_id - type - status - ended_reason - business_phone_number - customer_phone_number - started_at - ended_at - duration_seconds - outcome - sentiment - summary - campaign_id - long_summary - purpose - key_points - action_items - unanswered_questions - is_follow_up_needed - follow_up_reason - customer_name - mentioned_email - mentioned_date - mentioned_time - warm_transfer_started_at - custom_outcome - custom_outcome_value - custom_metadata title: Call 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 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 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.