Microsoft Dynamics 365 Dataverse Web API

openapi: 3.0.3
info:
  title: Microsoft Dynamics 365 Dataverse Web API
  description: >-
    The Microsoft Dynamics 365 Dataverse Web API provides a RESTful endpoint
    for interacting with Dataverse data used by Dynamics 365 Sales, Customer
    Service, Field Service, and other customer engagement applications. It
    implements OData v4 and supports CRUD operations on core CRM entities
    including accounts, contacts, leads, and opportunities. Authentication
    is handled via Microsoft Entra ID (Azure AD).
  version: "9.2"
  contact:
    name: Microsoft
    url: https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/overview
  license:
    name: Microsoft APIs Terms of Use
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
servers:
  - url: https://{organization}.api.crm.dynamics.com/api/data/v9.2
    description: Dynamics 365 Online (North America)
    variables:
      organization:
        default: org
        description: The unique name of your Dataverse organization.
  - url: https://{baseUrl}/api/data/v9.2
    description: Dynamics 365 On-Premises
    variables:
      baseUrl:
        default: localhost
security:
  - oauth2: []
paths:
  /accounts:
    get:
      summary: Microsoft Dynamics List accounts
      description: Retrieves a collection of account records.
      operationId: listAccounts
      tags:
        - Accounts
      parameters:
        - $ref: "#/components/parameters/top"
        - $ref: "#/components/parameters/skip"
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/select"
        - $ref: "#/components/parameters/orderby"
        - $ref: "#/components/parameters/expand"
      responses:
        "200":
          description: A collection of accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: "#/components/schemas/Account"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      summary: Microsoft Dynamics Create an account
      description: Creates a new account record.
      operationId: createAccount
      tags:
        - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Account"
      responses:
        "204":
          description: Account created successfully.
          headers:
            OData-EntityId:
              description: URI of the created record.
              schema:
                type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
  /accounts({accountid}):
    get:
      summary: Microsoft Dynamics Get an account
      description: Retrieves a single account by ID.
      operationId: getAccount
      tags:
        - Accounts
      parameters:
        - name: accountid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/select"
        - $ref: "#/components/parameters/expand"
      responses:
        "200":
          description: An account record.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      summary: Microsoft Dynamics Update an account
      description: Updates an existing account record.
      operationId: updateAccount
      tags:
        - Accounts
      parameters:
        - name: accountid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/ifMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Account"
      responses:
        "204":
          description: Account updated successfully.
    delete:
      summary: Microsoft Dynamics Delete an account
      description: Deletes an account record.
      operationId: deleteAccount
      tags:
        - Accounts
      parameters:
        - name: accountid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Account deleted successfully.
  /contacts:
    get:
      summary: Microsoft Dynamics List contacts
      description: Retrieves a collection of contact records.
      operationId: listContacts
      tags:
        - Contacts
      parameters:
        - $ref: "#/components/parameters/top"
        - $ref: "#/components/parameters/skip"
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/select"
        - $ref: "#/components/parameters/orderby"
        - $ref: "#/components/parameters/expand"
      responses:
        "200":
          description: A collection of contacts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: "#/components/schemas/Contact"
    post:
      summary: Microsoft Dynamics Create a contact
      description: Creates a new contact record.
      operationId: createContact
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Contact"
      responses:
        "204":
          description: Contact created successfully.
          headers:
            OData-EntityId:
              description: URI of the created record.
              schema:
                type: string
  /contacts({contactid}):
    get:
      summary: Microsoft Dynamics Get a contact
      description: Retrieves a single contact by ID.
      operationId: getContact
      tags:
        - Contacts
      parameters:
        - name: contactid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/select"
        - $ref: "#/components/parameters/expand"
      responses:
        "200":
          description: A contact record.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Contact"
    patch:
      summary: Microsoft Dynamics Update a contact
      description: Updates an existing contact record.
      operationId: updateContact
      tags:
        - Contacts
      parameters:
        - name: contactid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/ifMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Contact"
      responses:
        "204":
          description: Contact updated successfully.
    delete:
      summary: Microsoft Dynamics Delete a contact
      description: Deletes a contact record.
      operationId: deleteContact
      tags:
        - Contacts
      parameters:
        - name: contactid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Contact deleted successfully.
  /leads:
    get:
      summary: Microsoft Dynamics List leads
      description: Retrieves a collection of lead records.
      operationId: listLeads
      tags:
        - Leads
      parameters:
        - $ref: "#/components/parameters/top"
        - $ref: "#/components/parameters/skip"
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/select"
        - $ref: "#/components/parameters/orderby"
        - $ref: "#/components/parameters/expand"
      responses:
        "200":
          description: A collection of leads.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: "#/components/schemas/Lead"
    post:
      summary: Microsoft Dynamics Create a lead
      description: Creates a new lead record.
      operationId: createLead
      tags:
        - Leads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Lead"
      responses:
        "204":
          description: Lead created successfully.
          headers:
            OData-EntityId:
              description: URI of the created record.
              schema:
                type: string
  /leads({leadid}):
    get:
      summary: Microsoft Dynamics Get a lead
      description: Retrieves a single lead by ID.
      operationId: getLead
      tags:
        - Leads
      parameters:
        - name: leadid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/select"
        - $ref: "#/components/parameters/expand"
      responses:
        "200":
          description: A lead record.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Lead"
    patch:
      summary: Microsoft Dynamics Update a lead
      description: Updates an existing lead record.
      operationId: updateLead
      tags:
        - Leads
      parameters:
        - name: leadid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/ifMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Lead"
      responses:
        "204":
          description: Lead updated successfully.
    delete:
      summary: Microsoft Dynamics Delete a lead
      description: Deletes a lead record.
      operationId: deleteLead
      tags:
        - Leads
      parameters:
        - name: leadid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Lead deleted successfully.
  /opportunities:
    get:
      summary: Microsoft Dynamics List opportunities
      description: Retrieves a collection of opportunity records.
      operationId: listOpportunities
      tags:
        - Opportunities
      parameters:
        - $ref: "#/components/parameters/top"
        - $ref: "#/components/parameters/skip"
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/select"
        - $ref: "#/components/parameters/orderby"
        - $ref: "#/components/parameters/expand"
      responses:
        "200":
          description: A collection of opportunities.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: "#/components/schemas/Opportunity"
    post:
      summary: Microsoft Dynamics Create an opportunity
      description: Creates a new opportunity record.
      operationId: createOpportunity
      tags:
        - Opportunities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Opportunity"
      responses:
        "204":
          description: Opportunity created successfully.
          headers:
            OData-EntityId:
              description: URI of the created record.
              schema:
                type: string
  /opportunities({opportunityid}):
    get:
      summary: Microsoft Dynamics Get an opportunity
      description: Retrieves a single opportunity by ID.
      operationId: getOpportunity
      tags:
        - Opportunities
      parameters:
        - name: opportunityid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/select"
        - $ref: "#/components/parameters/expand"
      responses:
        "200":
          description: An opportunity record.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Opportunity"
    patch:
      summary: Microsoft Dynamics Update an opportunity
      description: Updates an existing opportunity record.
      operationId: updateOpportunity
      tags:
        - Opportunities
      parameters:
        - name: opportunityid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/ifMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Opportunity"
      responses:
        "204":
          description: Opportunity updated successfully.
    delete:
      summary: Microsoft Dynamics Delete an opportunity
      description: Deletes an opportunity record.
      operationId: deleteOpportunity
      tags:
        - Opportunities
      parameters:
        - name: opportunityid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Opportunity deleted successfully.
  /incidents:
    get:
      summary: Microsoft Dynamics List cases
      description: Retrieves a collection of case (incident) records.
      operationId: listCases
      tags:
        - Cases
      parameters:
        - $ref: "#/components/parameters/top"
        - $ref: "#/components/parameters/skip"
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/select"
        - $ref: "#/components/parameters/orderby"
        - $ref: "#/components/parameters/expand"
      responses:
        "200":
          description: A collection of cases.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: "#/components/schemas/Incident"
    post:
      summary: Microsoft Dynamics Create a case
      description: Creates a new case (incident) record.
      operationId: createCase
      tags:
        - Cases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Incident"
      responses:
        "204":
          description: Case created successfully.
  /activities:
    get:
      summary: Microsoft Dynamics List activities
      description: Retrieves a collection of activity records.
      operationId: listActivities
      tags:
        - Activities
      parameters:
        - $ref: "#/components/parameters/top"
        - $ref: "#/components/parameters/skip"
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/select"
        - $ref: "#/components/parameters/orderby"
      responses:
        "200":
          description: A collection of activities.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: "#/components/schemas/Activity"
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: Microsoft Entra ID (Azure AD) OAuth 2.0 authentication.
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            https://org.crm.dynamics.com/.default: Access Dataverse API
  parameters:
    top:
      name: $top
      in: query
      description: Maximum number of records to return.
      schema:
        type: integer
    skip:
      name: $skip
      in: query
      description: Number of records to skip.
      schema:
        type: integer
    filter:
      name: $filter
      in: query
      description: OData filter expression.
      schema:
        type: string
    select:
      name: $select
      in: query
      description: Comma-separated list of properties to include.
      schema:
        type: string
    orderby:
      name: $orderby
      in: query
      description: Comma-separated list of properties to sort by.
      schema:
        type: string
    expand:
      name: $expand
      in: query
      description: Related entities to expand inline.
      schema:
        type: string
    ifMatch:
      name: If-Match
      in: header
      description: ETag value for optimistic concurrency.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Authentication required or token is invalid.
    NotFound:
      description: The requested resource was not found.
  schemas:
    Account:
      type: object
      properties:
        accountid:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
        accountnumber:
          type: string
        description:
          type: string
        revenue:
          type: number
          format: decimal
        numberofemployees:
          type: integer
        industrycode:
          type: integer
        address1_line1:
          type: string
        address1_line2:
          type: string
        address1_city:
          type: string
        address1_stateorprovince:
          type: string
        address1_postalcode:
          type: string
        address1_country:
          type: string
        telephone1:
          type: string
        emailaddress1:
          type: string
        websiteurl:
          type: string
        statecode:
          type: integer
          description: "0 = Active, 1 = Inactive"
        statuscode:
          type: integer
        createdon:
          type: string
          format: date-time
          readOnly: true
        modifiedon:
          type: string
          format: date-time
          readOnly: true
    Contact:
      type: object
      properties:
        contactid:
          type: string
          format: uuid
          readOnly: true
        firstname:
          type: string
        lastname:
          type: string
        fullname:
          type: string
          readOnly: true
        jobtitle:
          type: string
        emailaddress1:
          type: string
        telephone1:
          type: string
        mobilephone:
          type: string
        address1_line1:
          type: string
        address1_city:
          type: string
        address1_stateorprovince:
          type: string
        address1_postalcode:
          type: string
        address1_country:
          type: string
        birthdate:
          type: string
          format: date
        statecode:
          type: integer
          description: "0 = Active, 1 = Inactive"
        statuscode:
          type: integer
        createdon:
          type: string
          format: date-time
          readOnly: true
        modifiedon:
          type: string
          format: date-time
          readOnly: true
    Lead:
      type: object
      properties:
        leadid:
          type: string
          format: uuid
          readOnly: true
        subject:
          type: string
        firstname:
          type: string
        lastname:
          type: string
        fullname:
          type: string
          readOnly: true
        companyname:
          type: string
        jobtitle:
          type: string
        emailaddress1:
          type: string
        telephone1:
          type: string
        address1_line1:
          type: string
        address1_city:
          type: string
        address1_stateorprovince:
          type: string
        address1_postalcode:
          type: string
        address1_country:
          type: string
        leadsourcecode:
          type: integer
        estimatedvalue:
          type: number
          format: decimal
        estimatedclosedate:
          type: string
          format: date
        statecode:
          type: integer
          description: "0 = Open, 1 = Qualified, 2 = Disqualified"
        statuscode:
          type: integer
        createdon:
          type: string
          format: date-time
          readOnly: true
        modifiedon:
          type: string
          format: date-time
          readOnly: true
    Opportunity:
      type: object
      properties:
        opportunityid:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
        description:
          type: string
        estimatedvalue:
          type: number
          format: decimal
        estimatedclosedate:
          type: string
          format: date
        actualvalue:
          type: number
          format: decimal
        actualclosedate:
          type: string
          format: date
        closeprobability:
          type: integer
        currentsituation:
          type: string
        customerneed:
          type: string
        proposedsolution:
          type: string
        stepname:
          type: string
        statecode:
          type: integer
          description: "0 = Open, 1 = Won, 2 = Lost"
        statuscode:
          type: integer
        createdon:
          type: string
          format: date-time
          readOnly: true
        modifiedon:
          type: string
          format: date-time
          readOnly: true
    Incident:
      type: object
      properties:
        incidentid:
          type: string
          format: uuid
          readOnly: true
        title:
          type: string
        description:
          type: string
        ticketnumber:
          type: string
          readOnly: true
        casetypecode:
          type: integer
          description: "1 = Question, 2 = Problem, 3 = Request"
        prioritycode:
          type: integer
          description: "1 = High, 2 = Normal, 3 = Low"
        severitycode:
          type: integer
          description: "1 = Default"
        statecode:
          type: integer
          description: "0 = Active, 1 = Resolved, 2 = Cancelled"
        statuscode:
          type: integer
        createdon:
          type: string
          format: date-time
          readOnly: true
        modifiedon:
          type: string
          format: date-time
          readOnly: true
    Activity:
      type: object
      properties:
        activityid:
          type: string
          format: uuid
          readOnly: true
        subject:
          type: string
        description:
          type: string
        activitytypecode:
          type: string
          readOnly: true
        scheduledstart:
          type: string
          format: date-time
        scheduledend:
          type: string
          format: date-time
        actualdurationminutes:
          type: integer
        prioritycode:
          type: integer
          description: "0 = Low, 1 = Normal, 2 = High"
        statecode:
          type: integer
        statuscode:
          type: integer
        createdon:
          type: string
          format: date-time
          readOnly: true
        modifiedon:
          type: string
          format: date-time
          readOnly: true
tags:
  - name: Accounts
  - name: Activities
  - name: Cases
  - name: Contacts
  - name: Leads
  - name: Opportunities