> ## Documentation Index > Fetch the complete documentation index at: https://docs.moonbase.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create or Update a Call > Find and update an existing phone call, or create a new one. ## OpenAPI ````yaml POST /calls/upsert openapi: 3.1.0 info: title: Moonbase REST API version: v0 servers: - url: https://api.moonbase.ai/v0 security: - bearer: [] tags: - name: Inboxes description: Manage your inboxes, conversations, and messages - name: Collections description: Manage your collections and items - name: Marketing description: Manage your marketing campaigns and forms - name: Activities description: View activities and capture calls - name: Library description: Manage your meetings, files, and notes paths: /calls/upsert: post: tags: - Activities summary: Create or update a call description: Find and update an existing phone call, or create a new one. parameters: [] requestBody: description: The `Call` object to be created or updated. required: true content: application/json: schema: $ref: '#/components/schemas/CallUpsertParams' examples: Update: summary: Update value: direction: incoming start_at: '2025-02-17T15:00:00.000Z' answered_at: '2025-02-17T15:01:00Z' end_at: '2025-02-17T15:30:00.000Z' provider: openphone provider_id: openphone_id_000000000006 provider_status: completed provider_metadata: answered_by: UShjUatqtF user_id: UShjUatqtF phone_number_id: PN72zMikBJ conversation_id: CN3b48bcc423e772aeba377414a4fa6a06 participants: - phone: '+14155551212' role: caller - phone: '+16505551212' role: callee Create: summary: Create value: direction: incoming start_at: '2025-02-17T15:00:00.000Z' answered_at: '2025-02-17T15:01:00Z' end_at: '2025-02-17T15:30:00.000Z' provider: openphone provider_id: openphone_id_00000000000e provider_status: completed provider_metadata: answered_by: UShjUatqtF user_id: UShjUatqtF phone_number_id: PN72zMikBJ conversation_id: CN3b48bcc423e772aeba377414a4fa6a06 participants: - phone: '+14155551212' role: caller - phone: '+16505551212' role: callee tags: - id: 1CLJt2v8Yy2ZAfJZKmXhtn type: tag responses: '200': description: Successful response. content: application/json: schema: $ref: '#/components/schemas/Call' examples: Update: summary: Update value: id: 1CLJt2v5pkpkAnvdgXfEcF type: call participants: - id: 1CLJt2v6KXDyzDuM57pQqo type: call_participant role: caller phone: '+14155551212' person: id: 1CLJt2v6pHdDoet4Thyb5M type: item collection: id: 1CLJt2ubZ7zAZFBxUxeBHo type: collection ref: people - id: 1CLJt2v6ZuRbtwPhmQtzxa type: call_participant role: callee phone: '+16505551212' person: id: 1CLJt2v8Yy2ZAfJZKmXhtn type: item collection: id: 1CLJt2ubZ7zAZFBxUxeBHo type: collection ref: people tags: [] created_at: '2025-02-17T16:00:00.000Z' updated_at: '2025-02-17T16:00:00.000Z' direction: incoming start_at: '2025-02-17T15:00:00.000Z' answered_at: '2025-02-17T15:01:00.000Z' end_at: '2025-02-17T15:30:00.000Z' provider: openphone provider_id: openphone_id_000000000006 provider_status: completed provider_metadata: answered_by: UShjUatqtF user_id: UShjUatqtF phone_number_id: PN72zMikBJ conversation_id: CN3b48bcc423e772aeba377414a4fa6a06 '201': description: Creation succeeded. content: application/json: schema: $ref: '#/components/schemas/Call' examples: Create: summary: Create value: id: 1CLJt2v93jRnz6HGiMgt8L type: call participants: - id: 1CLJt2v9YVq2oXFz6wr4Mt type: call_participant role: caller phone: '+14155551212' - id: 1CLJt2v9nt2eiEkLoEveUf type: call_participant role: callee phone: '+16505551212' tags: - id: 1CLJt2v8Yy2ZAfJZKmXhtn type: tag name: Intro color: lunar created_at: '2025-02-17T16:00:00.000Z' updated_at: '2025-02-17T16:00:00.000Z' direction: incoming start_at: '2025-02-17T15:00:00.000Z' answered_at: '2025-02-17T15:01:00.000Z' end_at: '2025-02-17T15:30:00.000Z' provider: openphone provider_id: openphone_id_00000000000e provider_status: completed provider_metadata: answered_by: UShjUatqtF user_id: UShjUatqtF phone_number_id: PN72zMikBJ conversation_id: CN3b48bcc423e772aeba377414a4fa6a06 '400': description: '' content: application/json: schema: $ref: '#/components/schemas/Errors' examples: Bad Request: summary: Bad Request value: type: errors errors: - type: error status: '400' title: Bad Request detail: Call must have a caller and a callee source: pointer: /participants '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Errors' examples: Default: summary: Default value: type: errors errors: - type: error status: '401' title: Unauthorized detail: >- Invalid or missing API key or JWT. You should provide your Moonbase API Key or JWT in the authorization header, in the format: "Authorization: Bearer MOONBASE_API_KEY" '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Errors' examples: Default: summary: Default value: type: errors errors: - type: error status: '403' title: Forbidden '422': description: Invalid tags. content: application/json: schema: $ref: '#/components/schemas/Errors' examples: Invalid tags: summary: Invalid tags value: type: errors errors: - type: error status: '422' title: Unprocessable Entity detail: Tag ID 'invalid_tag_id' is invalid. source: pointer: /tags/0/id '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/Errors' examples: Default: summary: Default value: type: errors errors: - type: error status: '429' title: Too Many Requests '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Errors' examples: Default: summary: Default value: type: errors errors: - type: error status: '500' title: Internal Server Error '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/Errors' examples: Default: summary: Default value: type: errors errors: - type: error status: '503' title: Service Unavailable detail: >- The service is temporarily unavailable, please try again later. x-codeSamples: - lang: JavaScript source: |- import Moonbase from '@moonbaseai/sdk'; const client = new Moonbase({ apiKey: process.env['MOONBASE_API_KEY'], // This is the default and can be omitted }); const call = await client.calls.upsert({ direction: 'incoming', participants: [ { phone: '+14155551212', role: 'caller' }, { phone: '+16505551212', role: 'callee' }, ], provider: 'openphone', provider_id: 'openphone_id_000000000006', provider_status: 'completed', start_at: '2025-02-17T15:00:00.000Z', answered_at: '2025-02-17T15:01:00Z', end_at: '2025-02-17T15:30:00.000Z', provider_metadata: { answered_by: 'UShjUatqtF', user_id: 'UShjUatqtF', phone_number_id: 'PN72zMikBJ', conversation_id: 'CN3b48bcc423e772aeba377414a4fa6a06', }, }); console.log(call.id); - lang: Python source: |- import os from datetime import datetime from moonbase import Moonbase client = Moonbase( api_key=os.environ.get("MOONBASE_API_KEY"), # This is the default and can be omitted ) call = client.calls.upsert( direction="incoming", participants=[{ "phone": "+14155551212", "role": "caller", }, { "phone": "+16505551212", "role": "callee", }], provider="openphone", provider_id="openphone_id_000000000006", provider_status="completed", start_at=datetime.fromisoformat("2025-02-17T15:00:00.000"), answered_at=datetime.fromisoformat("2025-02-17T15:01:00"), end_at=datetime.fromisoformat("2025-02-17T15:30:00.000"), provider_metadata={ "answered_by": "UShjUatqtF", "user_id": "UShjUatqtF", "phone_number_id": "PN72zMikBJ", "conversation_id": "CN3b48bcc423e772aeba377414a4fa6a06", }, ) print(call.id) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"time\"\n\n\t\"github.com/moonbaseai/moonbase-sdk-go\"\n\t\"github.com/moonbaseai/moonbase-sdk-go/option\"\n)\n\nfunc main() {\n\tclient := moonbase.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tcall, err := client.Calls.Upsert(context.TODO(), moonbase.CallUpsertParams{\n\t\tDirection: moonbase.CallUpsertParamsDirectionIncoming,\n\t\tParticipants: []moonbase.CallUpsertParamsParticipant{{\n\t\t\tPhone: \"+14155551212\",\n\t\t\tRole: \"caller\",\n\t\t}, {\n\t\t\tPhone: \"+16505551212\",\n\t\t\tRole: \"callee\",\n\t\t}},\n\t\tProvider: moonbase.CallUpsertParamsProviderOpenphone,\n\t\tProviderID: \"openphone_id_000000000006\",\n\t\tProviderStatus: \"completed\",\n\t\tStartAt: time.Now(),\n\t\tAnsweredAt: moonbase.Time(time.Now()),\n\t\tEndAt: moonbase.Time(time.Now()),\n\t\tProviderMetadata: map[string]any{\n\t\t\t\"answered_by\": \"UShjUatqtF\",\n\t\t\t\"user_id\": \"UShjUatqtF\",\n\t\t\t\"phone_number_id\": \"PN72zMikBJ\",\n\t\t\t\"conversation_id\": \"CN3b48bcc423e772aeba377414a4fa6a06\",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", call.ID)\n}\n" - lang: Ruby source: |- require "moonbase" moonbase = Moonbase::Client.new(api_key: "My API Key") call = moonbase.calls.upsert( direction: :incoming, participants: [{phone: "+14155551212", role: :caller}, {phone: "+16505551212", role: :callee}], provider: :openphone, provider_id: "openphone_id_000000000006", provider_status: "completed", start_at: "2025-02-17T15:00:00.000Z" ) puts(call) components: schemas: CallUpsertParams: title: CallUpsertParams description: Parameters for creating or updating a `Call` object. type: object properties: direction: description: The direction of the call, either `incoming` or `outgoing`. type: string enum: - incoming - outgoing start_at: description: The time the call started, as an ISO 8601 timestamp in UTC. type: string format: date-time answered_at: description: The time the call was answered, as an ISO 8601 timestamp in UTC. type: string format: date-time end_at: description: The time the call ended, as an ISO 8601 timestamp in UTC. type: string format: date-time provider: description: >- The name of the phone provider that handled the call (e.g., `openphone`). type: string enum: - openphone - user - zoom_phone provider_id: description: The unique identifier for the call from the provider's system. type: string provider_status: description: The status of the call. type: string provider_metadata: description: A hash of additional metadata from the provider. type: object additionalProperties: true participants: description: An array of participants involved in the call. type: array items: $ref: '#/components/schemas/CallParticipantCreateParams' recordings: description: Any recordings associated with the call. type: array items: $ref: '#/components/schemas/CallRecordingCreateParams' tags: description: >- Optional list of tag pointers to assign to the call. If omitted, existing tags are unchanged. Pass an empty array to clear tags. type: array items: $ref: '#/components/schemas/TagPointerParam' transcript: $ref: '#/components/schemas/CallTranscriptCreateParams' description: A transcript of the call. required: - provider_id - provider_status - direction - start_at - provider - participants Call: title: Call description: >- The Call object represents a phone call that has been logged in the system. It contains details about the participants, timing, and outcome of the call. type: object properties: type: description: >- String representing the object’s type. Always `call` for this object. type: string const: call id: description: Unique identifier for the object. type: string direction: description: The direction of the call, either `incoming` or `outgoing`. type: string enum: - incoming - outgoing start_at: description: The time the call started, as an ISO 8601 timestamp in UTC. type: string format: date-time answered_at: description: >- The time the call was answered, if available, as an ISO 8601 timestamp in UTC. type: string format: date-time end_at: description: >- The time the call ended, if available, as an ISO 8601 timestamp in UTC. type: string format: date-time provider: description: The name of the phone provider that handled the call. type: string enum: - openphone - user - zoom_phone provider_id: description: The unique identifier for the call from the provider's system. type: string provider_status: description: The current status of the call. type: string provider_metadata: description: A hash of additional metadata from the provider. type: object additionalProperties: true participants: description: The participants involved in the call. type: array items: $ref: '#/components/schemas/CallParticipant' tags: description: The tags currently applied to this call. type: array items: $ref: '#/components/schemas/Tag' transcript: oneOf: - type: 'null' - $ref: '#/components/schemas/CallTranscript' note: description: > Any notes taken during or after the call. Returns `null` if no note exists. **Note:** Only present when requested using the `include` query parameter. oneOf: - type: 'null' - $ref: '#/components/schemas/Note' summary: description: > A summary of the call, or `null` if no summary has been generated yet. **Note:** Only present when requested using the `include` query parameter. oneOf: - type: 'null' - $ref: '#/components/schemas/Note' created_at: description: >- Time at which the object was created, as an ISO 8601 timestamp in UTC. type: string format: date-time updated_at: description: >- Time at which the object was last updated, as an ISO 8601 timestamp in UTC. type: string format: date-time required: - provider_id - provider_status - direction - start_at - provider - type - id - participants - tags - created_at - updated_at Errors: title: Errors description: >- The Errors object is a container that holds multiple Error objects when an API request encounters several validation or processing issues. This allows the API to return comprehensive feedback about all problems encountered in a single response. type: object properties: type: type: string const: errors errors: description: A list of `Error` objects. type: array items: $ref: '#/components/schemas/Error' required: - type CallParticipantCreateParams: title: CallParticipantCreateParams description: Parameters for creating a `Participant` object. type: object properties: role: description: >- The role of the participant in the call. Can be `caller`, `callee`, or `other`. type: string enum: - caller - callee - other phone: description: The E.164 formatted phone number of the participant. type: string required: - phone - role CallRecordingCreateParams: title: CallRecordingCreateParams description: Parameters for creating a `CallRecording` object. type: object properties: provider_id: description: The unique identifier for the recording from the provider's system. type: string content_type: description: >- The content type of the recording. Note that only `audio/mpeg` is supported at this time. type: string enum: - audio/mpeg url: description: The URL pointing to the recording. type: string format: uri required: - provider_id - content_type - url TagPointerParam: title: TagPointerParam description: A lightweight reference to a `Tag` used in request bodies. type: object properties: type: description: String representing the object’s type. Always `tag` for this object. type: string const: tag id: description: Unique identifier of the tag. type: string required: - type - id CallTranscriptCreateParams: title: CallTranscriptCreateParams description: >- Parameters for creating a `CallTranscript` object to capture the transcript of a call. type: object properties: cues: description: >- A list of cues that identify the text spoken in specific time slices of the call. type: array items: $ref: '#/components/schemas/CallTranscriptCueCreateParams' required: - cues CallParticipant: title: CallParticipant description: Represents a participant in a call. type: object properties: type: description: >- String representing the object’s type. Always `call_participant` for this object. type: string const: call_participant id: description: Unique identifier for the object. type: string role: description: >- The role of the participant in the call. Can be `caller`, `callee`, or `other`. type: string enum: - caller - callee - other phone: description: The E.164 formatted phone number of the participant. type: string person: $ref: '#/components/schemas/ItemPointer' organization: $ref: '#/components/schemas/ItemPointer' required: - phone - role - type - id Tag: title: Tag description: >- A Tag is a label that can be applied to supported resources (such as conversations, calls, and meetings) for organization and filtering. type: object properties: type: description: String representing the object’s type. Always `tag` for this object. type: string const: tag id: description: Unique identifier for the object. type: string name: description: The name of the tag. type: string color: $ref: '#/components/schemas/NamedColor' description: The color for the tag. required: - name - type - id - color CallTranscript: title: CallTranscript description: '' type: object properties: cues: type: array items: $ref: '#/components/schemas/CallTranscriptCue' required: - cues Note: title: Note description: >- The Note object represents a block of text content, often used for meeting notes or summaries. type: object properties: type: description: >- String representing the object’s type. Always `note` for this object. type: string const: note id: description: Unique identifier for the object. type: string lock_version: description: >- The current lock version of the note for optimistic concurrency control. type: integer body: $ref: '#/components/schemas/FormattedText' description: The main content of the note. created_at: description: >- Time at which the object was created, as an ISO 8601 timestamp in UTC. type: string format: date-time updated_at: description: >- Time at which the object was last updated, as an ISO 8601 timestamp in UTC. type: string format: date-time title: description: An optional title for the note. type: string summary: description: A short, system-generated summary of the note's content. type: string creator: description: The person that created the note. oneOf: - type: 'null' - $ref: '#/components/schemas/ItemPointer' associations: description: A list of items, meetings or calls this note is associated with. type: array items: $ref: '#/components/schemas/NoteAssociationPointer' required: - type - id - lock_version - body - created_at - updated_at - associations Error: title: Error description: >- The Error object represents a single error that occurred during API request processing. It provides detailed information about what went wrong, including a unique identifier, status code, and human-readable descriptions to help developers understand and resolve the issue. type: object properties: type: type: string const: error id: description: A unique identifier for this specific error instance. type: string status: description: The HTTP status code for this problem, as a string. type: string code: description: An application-specific error code string. type: string title: description: A short, human-readable summary of the problem. type: string detail: description: A human-readable explanation of this specific error. type: string source: $ref: '#/components/schemas/ErrorSource' description: >- An object containing more specific information about the part of the request that caused the error. meta: type: object additionalProperties: true required: - type CallTranscriptCueCreateParams: title: CallTranscriptCueCreateParams description: >- Parameters for creating a `CallTranscriptCue` object to capture the text spoken in a specific time slice. type: object properties: from: description: >- The start time of the slice, in fractional seconds from the start of the call. type: number to: description: >- The end time of the slice, in fractional seconds from the start of the call. type: number text: description: The text spoken during the slice. type: string speaker: description: The E.164 formatted phone number of the speaker. type: string required: - from - to - text - speaker ItemPointer: title: ItemPointer description: >- A reference to an `Item` within a specific `Collection`, providing the context needed to locate the item. type: object properties: type: description: >- String representing the object’s type. Always `item` for this object. type: string const: item id: description: Unique identifier of the item. type: string collection: $ref: '#/components/schemas/CollectionPointer' description: A reference to the `Collection` containing this item. required: - collection - type - id NamedColor: type: string enum: - amber - blue - cyan - emerald - fuchsia - green - indigo - lime - lunar - orange - pink - purple - red - rose - sky - teal - violet - yellow description: >- One of Moonbase's standard color names. Moonbase renders these consistently across light and dark modes. CallTranscriptCue: title: CallTranscriptCue description: '' type: object properties: from: type: number to: type: number text: type: string speaker: $ref: '#/components/schemas/CallTranscriptSpeaker' required: - from - to - text - speaker FormattedText: title: FormattedText description: >- Structured content that can be rendered in multiple formats, currently supporting Markdown. type: object properties: markdown: description: The content formatted as Markdown text. type: string required: [] NoteAssociationPointer: title: NoteAssociationPointer description: A reference to a call, meeting, or item associated with the note. oneOf: - $ref: '#/components/schemas/CallPointer' - $ref: '#/components/schemas/ItemPointer' - $ref: '#/components/schemas/MeetingPointer' discriminator: propertyName: type mapping: call: $ref: '#/components/schemas/CallPointer' item: $ref: '#/components/schemas/ItemPointer' meeting: $ref: '#/components/schemas/MeetingPointer' ErrorSource: title: ErrorSource description: >- The ErrorSource object provides additional context about the specific part of an API request that caused an error. It can point to either a field in the request document or a query parameter that contains invalid data. type: object properties: pointer: description: >- A JSON Pointer [RFC6901] to the associated entity in the request document. type: string parameter: description: A string indicating which URI query parameter caused the error. type: string required: [] CollectionPointer: title: CollectionPointer description: >- A lightweight reference to a `Collection`, containing the minimal information needed to identify it. type: object properties: type: description: >- String representing the object’s type. Always `collection` for this object. type: string const: collection id: description: Unique identifier of the collection. type: string ref: description: The stable, machine-readable reference identifier of the collection. type: string required: - type - id - ref CallTranscriptSpeaker: title: CallTranscriptSpeaker description: '' type: object properties: label: type: string attendee_id: type: string required: [] CallPointer: title: CallPointer type: object properties: type: type: string const: call id: type: string required: - type - id MeetingPointer: title: MeetingPointer type: object properties: type: type: string const: meeting id: type: string required: - type - id securitySchemes: bearer: type: http scheme: bearer description: Your Moonbase API key. ````