> ## Documentation Index > Fetch the complete documentation index at: https://docs.roark.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update the properties of a call > Add, overwrite or remove custom properties on an already-existing call. Use this for data that becomes available after the call was created, e.g. an outcome your system validates a few minutes later. Merge semantics: a value adds or overwrites the property, null removes it, and properties left out are untouched. The patch is applied whole or not at all: a property Roark sets itself, or a value whose type differs from the type the project already stores that property as, rejects the request with a 400 and nothing is written. A 409 means another request created one of the properties with a different value type at the same moment; nothing was written. Optionally pass `metrics` to (re)score metrics over the updated properties, which triggers a billed metric collection job and requires the `metric:create` permission. ## OpenAPI ````yaml /api-reference/openapi.documented.json patch /v1/call/{callId}/properties openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Agent Endpoint - name: Call - name: Chat - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Customer Flow - name: Customer Flow Edge Case - name: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Template - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Autoimprove - name: Agent Config - name: Knowledge Base - name: Config - name: Organization Project - name: Organization Project Member - name: Organization Project API Key - name: Organization Config - name: CLI Auth - name: Me - name: Project - name: Usage - name: Benchmark - name: Health - name: Prospect Simulation paths: /v1/call/{callId}/properties: patch: tags: - Call summary: Update the properties of a call description: >- Add, overwrite or remove custom properties on an already-existing call. Use this for data that becomes available after the call was created, e.g. an outcome your system validates a few minutes later. Merge semantics: a value adds or overwrites the property, null removes it, and properties left out are untouched. The patch is applied whole or not at all: a property Roark sets itself, or a value whose type differs from the type the project already stores that property as, rejects the request with a 400 and nothing is written. A 409 means another request created one of the properties with a different value type at the same moment; nothing was written. Optionally pass `metrics` to (re)score metrics over the updated properties, which triggers a billed metric collection job and requires the `metric:create` permission. operationId: patchV1CallByCallIdProperties parameters: - in: path name: callId schema: type: string format: uuid required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateCallPropertiesRequest' responses: '200': description: Properties updated on the call content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/UpdateCallPropertiesResponse' required: - data '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error example: type: validation code: invalid_parameter message: The request was invalid param: email description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission error example: type: forbidden code: permission_denied message: You do not have permission to access this resource description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not found error example: type: not_found code: resource_not_found message: The requested resource could not be found description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Conflict error example: type: conflict code: resource_in_use message: The resource is in use and cannot be deleted description: Conflict '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limit error example: type: rate_limit code: too_many_requests message: Rate limit exceeded description: Too Many Requests '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: >- import Roark from '@roarkanalytics/sdk'; const client = new Roark({ bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted }); const response = await client.call.updateProperties('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { properties: { partner_outcome: 'apr_returned', delivered_apr: '21.99' }, }); console.log(response.data); - lang: Python source: |- import os from roark_analytics import Roark client = Roark( bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"), # This is the default and can be omitted ) response = client.call.update_properties( call_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", properties={ "delivered_apr": "21.99", "partner_outcome": "apr_returned", }, ) print(response.data) components: schemas: UpdateCallPropertiesRequest: type: object properties: properties: type: object propertyNames: type: string minLength: 1 additionalProperties: anyOf: - type: string - type: number - type: boolean - type: 'null' description: >- Properties to change on the call. A string, number or boolean value adds the property or overwrites it; null removes it. Properties left out are untouched. Keys are stored in snake_case, as on POST /v1/call. A property keeps the value type it was first stored with in the project, so a value of another type is rejected. Properties Roark sets itself (direction, duration_seconds, agent_id, ...) can't be changed. Max 100 per request. example: partner_outcome: apr_returned delivered_apr: '21.99' metrics: type: array items: type: object properties: id: type: string format: uuid required: - id minItems: 1 maxItems: 20 description: >- Optional. Metric definitions to (re)score on this call once the properties are written, e.g. metrics that read the call's properties. Triggers a metric collection job (billed, credit-gated) and requires the 'metric:create' permission. Omit to update properties without scoring. Max 20. required: - properties description: >- Add, overwrite or remove custom properties on an existing call, optionally (re)scoring metrics. UpdateCallPropertiesResponse: type: object properties: callId: type: string format: uuid description: The call whose properties were updated updated: type: array items: type: string description: >- Stored (snake_case) names of the properties written by this request, including ones sent with the value they already had removed: type: array items: type: string description: >- Stored names of the properties removed by this request. A property sent as null that was not on the call is not listed. properties: type: object additionalProperties: type: string description: >- All of the call's properties after the update, including the ones Roark sets, when the key also has the 'call:read' permission. A key without it gets back only the properties this request wrote. Values are returned as strings, as on GET /v1/call/:callId. metricCollectionJob: oneOf: - $ref: '#/components/schemas/MetricCollectionJobResponse' - type: 'null' description: >- The metric collection job triggered to (re)score the requested metrics, or null when no metrics were requested (or when scoring failed, see metricCollectionError). Track its id to fetch results from GET /v1/metric/collection-jobs/:jobId. metricCollectionError: type: - string - 'null' description: >- Present (non-null) only when `metrics` were requested but the collection job could not be started (e.g. insufficient credits, or an unknown metric id). The properties were still written. Retry scoring via POST /v1/metric/collection-jobs, or re-send this request (writing the same values again is harmless). Null on success or when no metrics were requested. required: - callId - updated - removed - properties - metricCollectionJob - metricCollectionError description: Result of updating the properties of a call. ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - payment_required - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message MetricCollectionJobResponse: type: object properties: id: type: string format: uuid description: Unique identifier of the metric collection job status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - CANCELED description: Current status of the job triggeredBy: type: string enum: - USER_MANUAL - USER_API - METRIC_POLICY - SIMULATION description: What triggered this job totalItems: type: integer description: Total number of call-metric pairs to process completedItems: type: integer description: Number of successfully completed items failedItems: type: integer description: Number of failed items startedAt: type: - string - 'null' description: When the job started processing completedAt: type: - string - 'null' description: When the job completed errorMessage: type: - string - 'null' description: Error message if the job failed policyIds: type: array items: type: string format: uuid description: IDs of the metric policies that triggered this job createdAt: type: string description: When the job was created updatedAt: type: string description: When the job was last updated required: - id - status - triggeredBy - totalItems - completedItems - failedItems - startedAt - completedAt - errorMessage - policyIds - createdAt - updatedAt description: A metric collection job that processes metrics for calls or chats securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.