openapi: 3.0.3
info:
  title: SAP Business ByDesign OData Analytics CRM API
  description: OData v2 REST API for SAP Business ByDesign — a cloud ERP solution for midmarket companies. Provides access to business objects and analytics across financials, CRM, procurement, supply chain, project management, and HR. Supports CRUD operations and custom OData services via the /sap/byd/odata/cust/v1/ namespace, plus pre-built analytics services via /sap/byd/odata/{service_name}.svc/.
  version: 1.0.0
  contact:
    name: SAP Support
    url: https://support.sap.com
  externalDocs:
    description: SAP Business ByDesign OData API Examples
    url: https://community.sap.com/t5/enterprise-resource-planning-blog-posts-by-sap/sap-business-bydesign-odata-api-examples/ba-p/13400614
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{tenant}.bydesign.cloud.sap
  description: SAP Business ByDesign tenant
  variables:
    tenant:
      default: my-tenant
      description: Your SAP Business ByDesign tenant hostname
security:
- basicAuth: []
- oAuth2: []
tags:
- name: CRM
  description: Manage leads, opportunities, and customer relationship data.
paths:
  /sap/byd/odata/cust/v1/khlead/LeadCollection:
    get:
      summary: Query leads
      description: Query CRM lead records with optional OData filter parameters.
      operationId: queryLeads
      tags:
      - CRM
      parameters:
      - $ref: '#/components/parameters/FilterParam'
      - $ref: '#/components/parameters/SelectParam'
      - $ref: '#/components/parameters/TopParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/FormatParam'
      responses:
        '200':
          description: Collection of lead records.
          content:
            application/json:
              schema:
                type: object
                properties:
                  d:
                    type: object
                    properties:
                      results:
                        type: array
                        items:
                          $ref: '#/components/schemas/Lead'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sap/byd/odata/cust/v1/khopportunity/OpportunityCollection:
    get:
      summary: Query opportunities
      description: Query CRM opportunity records.
      operationId: queryOpportunities
      tags:
      - CRM
      parameters:
      - $ref: '#/components/parameters/FilterParam'
      - $ref: '#/components/parameters/SelectParam'
      - $ref: '#/components/parameters/TopParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/FormatParam'
      responses:
        '200':
          description: Collection of opportunity records.
          content:
            application/json:
              schema:
                type: object
                properties:
                  d:
                    type: object
                    properties:
                      results:
                        type: array
                        items:
                          $ref: '#/components/schemas/Opportunity'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    FormatParam:
      name: $format
      in: query
      required: false
      description: Response format. Use 'json' for JSON output.
      schema:
        type: string
        enum:
        - json
        - xml
        default: json
    SelectParam:
      name: $select
      in: query
      required: false
      description: Comma-separated list of properties to include in the response.
      schema:
        type: string
    TopParam:
      name: $top
      in: query
      required: false
      description: Maximum number of records to return.
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 20
    FilterParam:
      name: $filter
      in: query
      required: false
      description: OData filter expression (e.g., Status eq 'Released' and PostingDate ge datetime'2024-01-01T00:00:00').
      schema:
        type: string
    SkipParam:
      name: $skip
      in: query
      required: false
      description: Number of records to skip for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
  schemas:
    Opportunity:
      type: object
      description: SAP Business ByDesign CRM opportunity.
      properties:
        ObjectID:
          type: string
        ID:
          type: string
        ProspectPartyName:
          type: string
        StatusCode:
          type: string
        SalesCyclePhaseCode:
          type: string
        ExpectedRevenueAmount:
          type: string
        CurrencyCode:
          type: string
        CloseDate:
          type: string
          format: date
    ODataError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: object
              properties:
                lang:
                  type: string
                value:
                  type: string
    Lead:
      type: object
      description: SAP Business ByDesign CRM lead.
      properties:
        ObjectID:
          type: string
        ID:
          type: string
        ProspectPartyName:
          type: string
        StatusCode:
          type: string
        QualificationLevelCode:
          type: string
        OwnerEmployeeID:
          type: string
  responses:
    Unauthorized:
      description: Unauthorized — invalid or missing credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using SAP Business ByDesign user credentials.
    oAuth2:
      type: oauth2
      description: OAuth 2.0 authentication for SAP Business ByDesign.
      flows:
        clientCredentials:
          tokenUrl: https://{tenant}.bydesign.cloud.sap/sap/bc/sec/oauth2/token
          scopes: {}