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

# Create or update by a unique property

> Finds the record whose `id_property` (a property marked as unique) equals `properties[id_property]`; updates it if it exists, creates it otherwise. The response includes `created`.



## OpenAPI

````yaml https://api.apyconnect.io/v1/openapi.json post /v1/objects/{key}/records/upsert
openapi: 3.1.0
info:
  title: ApyConnect API
  version: 1.0.0
  description: >-
    ApyConnect public API. OAuth 2.0 authentication (client_credentials grant)
    with opaque Bearer tokens. Wrapped responses ({data, meta} / {object:'list',
    data, pagination, meta}); typed errors with trace_id; cursor pagination;
    snake_case throughout the JSON. Rate limit per Application.


    Best practices: send an `Idempotency-Key` header on writes to make retries
    safe (the same key replays the stored response for 24h; reusing a key with a
    different body returns 409). Use `?expand=contact` (and `expand=company` on
    deals) to embed related resources and save round-trips. Deprecated endpoints
    carry RFC 8594 `Deprecation`/`Sunset` headers. Inspect usage at `/v1/usage`
    and the write audit trail at `/v1/audit-logs`.
  contact:
    name: ApyConnect
    url: https://docs.apyconnect.io
servers:
  - url: https://api.apyconnect.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: OAuth
  - name: Contacts
  - name: Conversations
  - name: Messages
  - name: Channels
  - name: Inboxes
  - name: Campaigns
  - name: Analytics
  - name: Webhooks
  - name: Deals
  - name: Tasks
  - name: Companies
  - name: Tickets
  - name: Custom objects
    description: >-
      Objects each workspace defines (policies, vehicles, properties…) and their
      records. Address an object by its key (e.g. `policies`) or id.
  - name: Notes
  - name: Segments
  - name: Macros
  - name: Settings
  - name: Jobs
  - name: Observability
paths:
  /v1/objects/{key}/records/upsert:
    parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
        description: Object key (e.g. `policies`) or id.
    post:
      tags:
        - Custom objects
      summary: Create or update by a unique property
      description: >-
        Finds the record whose `id_property` (a property marked as unique)
        equals `properties[id_property]`; updates it if it exists, creates it
        otherwise. The response includes `created`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RecordCreate'
                - type: object
                  properties:
                    id_property:
                      type: string
                  required:
                    - id_property
                    - properties
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Record'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                  - data
                  - meta
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Record'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                  - data
                  - meta
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: authentication_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: permission_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: rate_limit_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    RecordCreate:
      type: object
      properties:
        properties:
          type: object
          additionalProperties: true
        stage:
          type: string
          description: Stage key (defaults to the first stage).
        owner_id:
          type: string
        links:
          type: array
          items:
            $ref: '#/components/schemas/RecordLinkCreate'
    Record:
      type: object
      properties:
        object:
          const: record
        id:
          type: string
        object_key:
          type: string
        number:
          type:
            - integer
            - 'null'
        display_number:
          type:
            - string
            - 'null'
          description: Number with the object's prefix (e.g. POL-12).
        name:
          type: string
        stage:
          type:
            - string
            - 'null'
        owner_id:
          type:
            - string
            - 'null'
        properties:
          type: object
          additionalProperties: true
          description: >-
            Values by property key. Select values are choice values; user
            properties hold a user id; reference properties hold a record id.
        links:
          type: array
          items:
            $ref: '#/components/schemas/RecordLink'
          description: Only with ?expand=links.
        created_at:
          type: string
        updated_at:
          type: string
        stage_changed_at:
          type:
            - string
            - 'null'
    Meta:
      type: object
      properties:
        request_id:
          type: string
      required:
        - request_id
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - rate_limit_error
                - not_found_error
                - conflict_error
                - api_error
            code:
              type: string
            message:
              type: string
            trace_id:
              type: string
            details: {}
          required:
            - type
            - code
            - message
            - trace_id
    RecordLinkCreate:
      type: object
      properties:
        association_id:
          type: string
        target_id:
          type: string
      required:
        - association_id
        - target_id
    RecordLink:
      type: object
      properties:
        object:
          const: record_link
        id:
          type: string
        association_id:
          type: string
        target_type:
          type: string
          enum:
            - contact
            - company
            - deal
            - ticket
            - object
        target_id:
          type: string
        target_name:
          type: string
        target_object_key:
          type:
            - string
            - 'null'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Opaque token issued by /oauth/token.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.