> ## Documentation Index > Fetch the complete documentation index at: https://docs.siro.ai/llms.txt > Use this file to discover all available pages before exploring further. # Sync an engagement > Sync an engagement ## OpenAPI ````yaml put /v1/integrations/sync/engagements openapi: 3.0.0 info: version: 1.0.0 title: Swagger API servers: - url: https://functions.siro.ai/api-externalApi description: Siro API external API endpoint security: [] externalDocs: description: View the raw OpenAPI Specification in JSON format url: /swagger.json paths: /v1/integrations/sync/engagements: put: summary: Sync an engagement description: Sync an engagement requestBody: content: application/json: schema: type: object properties: externalId: type: string description: The ID of the engagement in the external system direction: type: string nullable: true enum: - INBOUND - OUTBOUND description: The direction of the engagement (INBOUND/OUTBOUND) content: type: string nullable: true description: The content of the engagement subject: type: string nullable: true description: The subject of the engagement status: type: string nullable: true description: >- The status of the engagement in the external system, stored verbatim (eg. a Salesforce ServiceAppointment "Status" picklist label). Values are platform- and org-specific, so they are not normalized or comparable across connections. startTime: type: string nullable: true description: >- start dateTime of the engagement. Include a UTC offset or "Z" (e.g. 2026-09-20T14:00:00-04:00) to state the instant exactly. An offset-less value (e.g. 2026-09-20T14:00:00) is read as wall-clock time in the integration connection's defaultTimezone when one is set, otherwise as UTC. startTimeLocalized: type: string nullable: true description: >- Localized dateTime of the engagement, without timezone info. When present, the frontend will display this as-is without timezone conversion, overriding startTime for display purposes. Set automatically from the wall-clock value when the connection's defaultTimezone is applied. endTime: type: string nullable: true description: >- end dateTime of the engagement. Interpreted the same way as startTime. remoteCreatedAt: type: string nullable: true description: external engagement creation datetime remoteUpdatedAt: type: string nullable: true description: external engagement update datetime deletedAt: type: string nullable: true format: date-time description: >- The datetime when this record was deleted in the external system. Use to represent if an engagement was cancelled. engagementTypeId: type: string nullable: true description: >- Internal SIRO engagementTypeId override for this engagement. OPTIONAL -- only use if you know the internal value of the engagement type as it will override the engagementType object args. engagementType: type: object nullable: true properties: externalId: type: string description: >- The ID of the engagement type in the external system (if applicable) name: type: string description: The name of the engagementType activityType: type: string enum: - MEETING - CALL - APPOINTMENT - EMAIL - TEXT - EVENT - SIRO_EVENT - SIRO_BOT_RECORDING description: >- Type of activity. Note: SIRO will only consider certain types as "Appointments" for our appointment flows: [MEETING, EVENT, APPOINTMENT] required: - name - activityType description: The type of this engagement account: type: object nullable: true properties: externalId: type: string description: The ID of the account in the external system. name: type: string description: The name of the account latitude: type: number description: The latitude of the account longitude: type: number description: The longitude of the account addresses: type: array items: type: object properties: country: type: string street: type: string city: type: string state: type: string zip: type: string required: - country - street - city - state - zip description: The address(es) associated to the account phoneNumbers: type: array items: type: string description: The phone number(s) for the account emailAddresses: type: array items: type: string description: The email address(es) for the account lastActivityAt: type: string description: >- The datetime of the last activity on this record in the external system deletedAt: type: string nullable: true format: date-time description: >- The datetime when this record was deleted in the external system owner: type: object nullable: true properties: externalId: type: string required: - externalId description: >- The owner user of this record in the external system (optional) mergedToExternalId: type: string description: >- If this Account was merged into another, the surviving Account externalId. Will migrate all existing references from this Account to the surviving Account. mergedFromExternalIds: type: array items: type: string description: >- If other Accounts were merged into this one, their externalIds. Will migrate all existing references from those Accounts to this Account. description: >- The associated account for this engagement. Note: supplying just an externalId will resolve to an already-synced account engagementUsers: type: array items: type: object properties: externalId: type: string description: The user's externalId in the external system email: type: string description: The user's email, preferably their email in Siro shareOfSale: type: number description: >- The user's fractional share of the sale, e.g. 0.5 for 50% or 1 for 100% (Optional) name: type: string description: The name of the user, e.g. John Smith deletedAt: type: string nullable: true format: date-time description: >- The datetime when this record was deleted in the external system (Optional) required: - externalId description: The users associated with this engagement opportunity: type: object nullable: true properties: externalId: type: string description: The ID of the opportunity in the external system name: type: string description: The name of the opportunity amount: type: number description: The dollar amount of the opportunity closedAt: type: string description: The closure date of the opportunity remoteCreatedAt: type: string description: >- The datetime the opportunity was created in the external system lastActivityAt: type: string description: The datetime of the last activity on this opportunity disposition: type: string enum: - OPEN - LOST - WON description: The disposition of the opportunity (WON, LOST, or OPEN) copyEngagementRelationships: type: boolean description: >- When true, copies the available engagement relationships (contact, account, users) opportunityStage: type: object nullable: true properties: externalId: type: string description: >- The ID of the stage in the external system. Platforms whose opportunities reference a stage by name rather than by ID (e.g. Salesforce, where Opportunity.StageName holds the name) should send that name here. name: type: string description: >- The display name of the stage. Optional: platforms that only carry a stage ID on the record can omit it and let the schema sync fill it in. required: - externalId description: >- The pipeline stage of this opportunity. Note: supplying just an externalId will resolve to an already-synced stage required: - externalId description: >- The associated opportunity for this engagement. Note: supplying just an externalId will resolve to an already-synced opportunity lead: type: object nullable: true properties: externalId: type: string description: The ID of the lead in the external system firstName: type: string description: The first name of the lead lastName: type: string description: The last name of the lead latitude: type: number description: The latitude of the lead longitude: type: number description: The longitude of the lead addresses: type: array items: type: object properties: country: type: string street: type: string city: type: string state: type: string zip: type: string required: - country - street - city - state - zip description: The address(es) associated with this lead phoneNumbers: type: array items: type: string description: The phone number(s) associated with this lead emailAddresses: type: array items: type: string description: The email address(es) associated with this lead lastActivityAt: type: string description: >- The datetime of the last activity on this record in the external system deletedAt: type: string nullable: true format: date-time description: >- The datetime when this record was deleted in the external system owner: type: object nullable: true properties: externalId: type: string required: - externalId description: >- The owner of this record in the external system (optional) mergedToExternalId: type: string description: >- If this Lead was merged into another, the surviving Lead externalId. Will migrate all existing references from this Lead to the surviving Lead. mergedFromExternalIds: type: array items: type: string description: >- If other Leads were merged into this one, their externalIds. Will migrate all existing references from those Leads to this Lead. required: - externalId description: The associated lead for this engagement contact: type: object nullable: true properties: externalId: type: string description: The ID of the contact in the external system name: type: string description: The name of the contact latitude: type: number description: The latitude of the contact longitude: type: number description: The longitude of the contact account: type: object nullable: true properties: externalId: type: string description: The ID of the account in the external system. name: type: string description: The name of the account latitude: type: number description: The latitude of the account longitude: type: number description: The longitude of the account addresses: type: array items: type: object properties: country: type: string street: type: string city: type: string state: type: string zip: type: string required: - country - street - city - state - zip description: The address(es) associated to the account phoneNumbers: type: array items: type: string description: The phone number(s) for the account emailAddresses: type: array items: type: string description: The email address(es) for the account lastActivityAt: type: string description: >- The datetime of the last activity on this record in the external system deletedAt: type: string nullable: true format: date-time description: >- The datetime when this record was deleted in the external system owner: type: object nullable: true properties: externalId: type: string required: - externalId description: >- The owner user of this record in the external system (optional) mergedToExternalId: type: string description: >- If this Account was merged into another, the surviving Account externalId. Will migrate all existing references from this Account to the surviving Account. mergedFromExternalIds: type: array items: type: string description: >- If other Accounts were merged into this one, their externalIds. Will migrate all existing references from those Accounts to this Account. description: >- The associated account for this contact. Note: supplying just an externalId will resolve to an already-synced account addresses: type: array items: type: object properties: country: type: string street: type: string city: type: string state: type: string zip: type: string required: - country - street - city - state - zip description: The address(es) associated with this contact phoneNumbers: type: array items: type: string description: The phone number(s) associated with this contact emailAddresses: type: array items: type: string description: The email address(es) associated with this contact lastActivityAt: type: string description: >- The datetime of the last activity on this record in the external system deletedAt: type: string nullable: true format: date-time description: >- The datetime when this record was deleted in the external system owner: type: object nullable: true properties: externalId: type: string required: - externalId description: >- The owner of this record in the external system (optional) mergedToExternalId: type: string description: >- If this Contact was merged into another, the surviving Contact externalId. Will migrate all existing references from this Contact to the surviving Contact. mergedFromExternalIds: type: array items: type: string description: >- If other Contacts were merged into this one, their externalIds. Will migrate all existing references from those Contacts to this Contact. required: - externalId description: >- (DEPRECATED IN FAVOR OF engagementContacts ARRAY) The associated contact for this engagement. Note: supplying just an externalId will resolve to an already-synced contact engagementContacts: type: array nullable: true items: type: object properties: externalId: type: string description: The ID of the contact in the external system name: type: string description: The name of the contact latitude: type: number description: The latitude of the contact longitude: type: number description: The longitude of the contact account: type: object nullable: true properties: externalId: type: string description: The ID of the account in the external system. name: type: string description: The name of the account latitude: type: number description: The latitude of the account longitude: type: number description: The longitude of the account addresses: type: array items: type: object properties: country: type: string street: type: string city: type: string state: type: string zip: type: string required: - country - street - city - state - zip description: The address(es) associated to the account phoneNumbers: type: array items: type: string description: The phone number(s) for the account emailAddresses: type: array items: type: string description: The email address(es) for the account lastActivityAt: type: string description: >- The datetime of the last activity on this record in the external system deletedAt: type: string nullable: true format: date-time description: >- The datetime when this record was deleted in the external system owner: type: object nullable: true properties: externalId: type: string required: - externalId description: >- The owner user of this record in the external system (optional) mergedToExternalId: type: string description: >- If this Account was merged into another, the surviving Account externalId. Will migrate all existing references from this Account to the surviving Account. mergedFromExternalIds: type: array items: type: string description: >- If other Accounts were merged into this one, their externalIds. Will migrate all existing references from those Accounts to this Account. description: >- The associated account for this contact. Note: supplying just an externalId will resolve to an already-synced account addresses: type: array items: type: object properties: country: type: string street: type: string city: type: string state: type: string zip: type: string required: - country - street - city - state - zip description: The address(es) associated with this contact phoneNumbers: type: array items: type: string description: The phone number(s) associated with this contact emailAddresses: type: array items: type: string description: The email address(es) associated with this contact lastActivityAt: type: string description: >- The datetime of the last activity on this record in the external system deletedAt: type: string nullable: true format: date-time description: >- The datetime when this record was deleted in the external system owner: type: object nullable: true properties: externalId: type: string required: - externalId description: >- The owner of this record in the external system (optional) mergedToExternalId: type: string description: >- If this Contact was merged into another, the surviving Contact externalId. Will migrate all existing references from this Contact to the surviving Contact. mergedFromExternalIds: type: array items: type: string description: >- If other Contacts were merged into this one, their externalIds. Will migrate all existing references from those Contacts to this Contact. isPrimary: type: boolean required: - externalId description: >- The associated contacts for this engagement. Note: supplying just an externalId will resolve to an already-synced contact remoteData: anyOf: - type: object additionalProperties: type: string - type: string description: >- Platform-specific data with no column of its own, eg. identifiers writeback needs that the Siro links do not name. Prefer an object -- the column is jsonb, and the legacy string form stores a scalar that cannot be queried into. Omit to leave any stored value untouched. required: - externalId responses: '200': description: Sync an engagement content: application/json: schema: type: object properties: data: type: object properties: id: type: string externalId: type: string description: >- The ID of the engagement in the external system (e.g. Salesforce) engagementType: type: string description: The type of the engagement direction: type: string description: '"INBOUND" | "OUTBOUND"' subject: type: string description: The subject of the engagement content: type: string description: The content of the engagement status: type: string description: The status of the engagement in the external system, startTime: type: string description: The start time of the engagement startTimeLocalized: type: string description: >- Localized dateTime of the engagement, without timezone info endTime: type: string description: The end time of the engagement createdAt: type: string description: The date the engagement was created updatedAt: type: string description: The date the engagement was last updated recordingId: type: string description: The ID of the recording associated to the engagement opportunityId: type: string description: The ID of the opportunity associated to the engagement accountId: type: string organizationId: type: string account: nullable: true engagementUsers: type: array items: nullable: true required: - id - externalId - engagementType - createdAt - updatedAt - organizationId required: - data security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Access token description: >- Client app access token from POST https://auth.siro.ai/oauth2/token, or a legacy organization API token (Person icon → API Tokens). Send `Authorization: Bearer `. x-default: Bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.