openapi: 3.0.3
info:
  title: Revert Unified Connection CRM Contacts API
  description: Revert is an open-source unified API for building product integrations. This specification describes the hosted REST surface at api.revert.dev, focused on the unified CRM category (contacts, leads, deals, companies, notes, tasks, events, users), the passthrough proxy, connection management, integration metadata, and webhooks. All CRM requests are authenticated with an `x-revert-api-token` (your Revert API key) and target a specific customer connection via `x-revert-t-id` (the tenant id captured when the customer linked their third-party tool through Revert's managed OAuth flow). Revert is AGPL-3.0 licensed and can be self-hosted.
  termsOfService: https://revert.dev
  contact:
    name: Revert
    url: https://revert.dev
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
  version: '1.0'
servers:
- url: https://api.revert.dev
  description: Revert hosted API
security:
- revertApiToken: []
tags:
- name: CRM Contacts
paths:
  /crm/contacts:
    get:
      tags:
      - CRM Contacts
      operationId: getContacts
      summary: List contacts from the connected CRM.
      parameters:
      - $ref: '#/components/parameters/TenantId'
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A page of contacts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnifiedListResponse'
    post:
      tags:
      - CRM Contacts
      operationId: createContact
      summary: Create a contact in the connected CRM.
      parameters:
      - $ref: '#/components/parameters/TenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '201':
          description: Contact created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnifiedResponse'
  /crm/contacts/{id}:
    get:
      tags:
      - CRM Contacts
      operationId: getContact
      summary: Get a single contact by id.
      parameters:
      - $ref: '#/components/parameters/Id'
      - $ref: '#/components/parameters/TenantId'
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: The contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnifiedResponse'
    patch:
      tags:
      - CRM Contacts
      operationId: updateContact
      summary: Update a contact by id.
      parameters:
      - $ref: '#/components/parameters/Id'
      - $ref: '#/components/parameters/TenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '200':
          description: Contact updated.
  /crm/contacts/search:
    post:
      tags:
      - CRM Contacts
      operationId: searchContacts
      summary: Search contacts in the connected CRM.
      parameters:
      - $ref: '#/components/parameters/TenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                searchCriteria:
                  type: object
      responses:
        '200':
          description: Matching contacts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnifiedListResponse'
components:
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The unified record id.
      schema:
        type: string
    Fields:
      name: fields
      in: query
      required: false
      description: Comma-separated list of additional provider fields to return.
      schema:
        type: string
    Cursor:
      name: cursor
      in: query
      required: false
      description: Pagination cursor returned by a previous list response.
      schema:
        type: string
    PageSize:
      name: pageSize
      in: query
      required: false
      description: Number of records to return per page.
      schema:
        type: integer
    ApiVersion:
      name: x-api-version
      in: header
      required: false
      description: Optional Revert API version. Latest is used when omitted.
      schema:
        type: string
    TenantId:
      name: x-revert-t-id
      in: header
      required: true
      description: The unique customer/tenant id used when the customer linked their account.
      schema:
        type: string
  schemas:
    UnifiedResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        result:
          type: object
    UnifiedListResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        next:
          type: string
          nullable: true
          description: Cursor for the next page, or null when there are no more records.
        previous:
          type: string
          nullable: true
        results:
          type: array
          items:
            type: object
    Contact:
      type: object
      properties:
        id:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        phone:
          type: string
        additional:
          type: object
          description: Provider-specific fields passthrough.
  securitySchemes:
    revertApiToken:
      type: apiKey
      in: header
      name: x-revert-api-token
      description: Your Revert API key (private token used from your backend).