> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lonescale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CRM Sync

> Push contacts and/or companies directly into your connected CRM. LoneScale creates or updates the records asynchronously, applying the team-level integration field mappings already configured in LoneScale (create/update fields and unicity criteria). No workflow is involved.

Record keys must match the LoneScale field keys referenced by your configured mappings (for example `lonescale_first_name`, `lonescale_company_domain`, or any custom key you mapped). Set `account_crm_id` on a record to target an existing CRM company by id instead of matching by unicity criteria.

Poll `GET /trigger/crm-sync/{id}` with the returned `id`, or pass a `webhook_url` to be called once with the run summary when every record has been processed.



## OpenAPI

````yaml POST /trigger/crm-sync
openapi: 3.1.0
info:
  title: OpenAPI Lonescale
  description: A sample API for Lonescale
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://public-api.lonescale.com
security:
  - ApiKeyAuth: []
paths:
  /trigger/crm-sync:
    post:
      description: >-
        Push contacts and/or companies directly into your connected CRM.
        LoneScale creates or updates the records asynchronously, applying the
        team-level integration field mappings already configured in LoneScale
        (create/update fields and unicity criteria). No workflow is involved.


        Record keys must match the LoneScale field keys referenced by your
        configured mappings (for example `lonescale_first_name`,
        `lonescale_company_domain`, or any custom key you mapped). Set
        `account_crm_id` on a record to target an existing CRM company by id
        instead of matching by unicity criteria.


        Poll `GET /trigger/crm-sync/{id}` with the returned `id`, or pass a
        `webhook_url` to be called once with the run summary when every record
        has been processed.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrmSyncRequest'
        required: true
      responses:
        '201':
          description: CRM sync run accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrmSyncRun'
        '401':
          description: Invalid or missing authentication credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
              example:
                message: Invalid API Key
                error: Unauthorized
                statusCode: 401
        '409':
          description: >-
            Ambiguous configuration: several CRMs (or several settings records)
            match; pass `crm` and/or `settings_type`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: >-
                  Multiple CRMs have mapping settings (hubspot, salesforce);
                  pass "crm" to pick one
                error: Conflict
                statusCode: 409
        '422':
          description: No mapping settings configured for the CRM, or empty payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: >-
                  No hubspot integration mapping settings found; configure the
                  hubspot integration in LoneScale first
                error: Unprocessable Entity
                statusCode: 422
components:
  schemas:
    CrmSyncRequest:
      type: object
      properties:
        crm:
          type: string
          enum:
            - hubspot
            - salesforce
            - pipedrive
            - sellsy
          description: >-
            Target CRM. Required only when more than one connected CRM has
            mapping settings.
        settings_type:
          type: string
          description: >-
            Which team-level settings record to sync with when several exist
            (settings are stored per use-case: contact_sourcing, job_changes,
            ...). Defaults to the contact_sourcing record, or the only existing
            record.
        contacts:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/CrmSyncRecord'
          description: >-
            Contacts to create/update (company fields may be embedded on each
            contact).
        companies:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/CrmSyncRecord'
          description: Companies to create/update, without contacts.
        webhook_url:
          type: string
          description: >-
            Called once with the run summary when every record has been
            processed.
        idempotency_key:
          type: string
          description: >-
            Reuse the same key to make client retries return the existing run
            instead of double-writing.
        trigger_by:
          type: string
    CrmSyncRun:
      type: object
      properties:
        id:
          type: string
          description: Run id, used to poll the status endpoint
        status:
          type: string
          example: processing
        createdAt:
          type: string
          format: date-time
        records_received:
          type: integer
        crm:
          type: string
          example: hubspot
    AuthError:
      required:
        - message
        - error
        - statusCode
      type: object
      properties:
        message:
          type: string
          example: Invalid API Key
        error:
          type: string
          example: Unauthorized
        statusCode:
          type: integer
          example: 401
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
    CrmSyncRecord:
      type: object
      additionalProperties: true
      description: >-
        Free-form record: keys must match the LoneScale field keys referenced by
        the configured mappings.
      properties:
        account_crm_id:
          type: string
          description: >-
            Optional CRM company id: targets that company directly instead of
            matching by unicity criteria.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Provide your API key in the x-api-key header.

````