Microsoft Power Apps Contacts API

openapi: 3.1.0
info:
  title: Microsoft Power Apps Microsoft Dataverse Web Accounts Contacts API
  description: RESTful API for interacting with Microsoft Dataverse (formerly Common Data Service), the underlying data platform for Microsoft Power Apps. This API follows OData v4.0 conventions and provides CRUD operations on Dataverse tables including accounts, contacts, and entity definitions. Each Dataverse environment has a unique organization URL and may include custom tables and operations specific to that environment.
  version: '9.2'
  termsOfService: https://www.microsoft.com/licensing/terms/productoffering/MicrosoftPowerApps
  contact:
    name: Microsoft Power Apps Developer Support
    url: https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/overview
  license:
    name: Microsoft Software License
    url: https://www.microsoft.com/licensing/terms/productoffering/MicrosoftPowerApps
  x-namespace: Microsoft.Dynamics.CRM
servers:
- url: https://{organization}.api.crm.dynamics.com/api/data/v9.2
  description: Dataverse Web API v9.2 endpoint (North America)
  variables:
    organization:
      default: yourorg
      description: The unique organization name for your Dataverse environment. Find this in the Power Platform admin center under environment details.
- url: https://{organization}.api.crm2.dynamics.com/api/data/v9.2
  description: Dataverse Web API v9.2 endpoint (South America)
  variables:
    organization:
      default: yourorg
      description: The unique organization name for your Dataverse environment.
- url: https://{organization}.api.crm4.dynamics.com/api/data/v9.2
  description: Dataverse Web API v9.2 endpoint (Europe)
  variables:
    organization:
      default: yourorg
      description: The unique organization name for your Dataverse environment.
- url: https://{organization}.api.crm5.dynamics.com/api/data/v9.2
  description: Dataverse Web API v9.2 endpoint (Asia Pacific)
  variables:
    organization:
      default: yourorg
      description: The unique organization name for your Dataverse environment.
security:
- oauth2: []
tags:
- name: Contacts
  description: Operations on the contact entity set. A contact represents a person with whom a business unit has a relationship, such as a customer, supplier, or colleague.
  externalDocs:
    description: Contact EntityType Reference
    url: https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/reference/contact
paths:
  /contacts:
    get:
      operationId: getContacts
      summary: Microsoft Power Apps Retrieve Multiple Contacts
      description: Retrieves a collection of contact records from Dataverse. Supports OData query options for filtering, sorting, selecting fields, expanding navigation properties, and pagination.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/ODataSelect'
      - $ref: '#/components/parameters/ODataFilter'
      - $ref: '#/components/parameters/ODataOrderBy'
      - $ref: '#/components/parameters/ODataTop'
      - $ref: '#/components/parameters/ODataSkip'
      - $ref: '#/components/parameters/ODataExpand'
      - $ref: '#/components/parameters/ODataCount'
      - $ref: '#/components/parameters/Prefer'
      - $ref: '#/components/parameters/ODataMaxPageSize'
      responses:
        '200':
          description: Successfully retrieved contact collection.
          headers:
            OData-Version:
              description: OData protocol version.
              schema:
                type: string
                example: '4.0'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createContact
      summary: Microsoft Power Apps Create a New Contact
      description: Creates a new contact record in Dataverse. Returns the created record when the Prefer header is set to return=representation.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/Prefer'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '204':
          description: Contact created successfully.
          headers:
            OData-EntityId:
              description: URI of the newly created contact record.
              schema:
                type: string
                format: uri
        '201':
          description: 'Contact created successfully with representation returned (when Prefer: return=representation is specified).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /contacts({contactid}):
    get:
      operationId: getContact
      summary: Microsoft Power Apps Retrieve a Single Contact
      description: Retrieves a single contact record by its unique identifier.
      tags:
      - Contacts
      parameters:
      - name: contactid
        in: path
        required: true
        description: Unique identifier (GUID) of the contact record.
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ODataSelect'
      - $ref: '#/components/parameters/ODataExpand'
      - $ref: '#/components/parameters/Prefer'
      responses:
        '200':
          description: Successfully retrieved contact record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateContact
      summary: Microsoft Power Apps Update an Existing Contact
      description: Updates an existing contact record using PATCH (merge update). Only the properties included in the request body are updated.
      tags:
      - Contacts
      parameters:
      - name: contactid
        in: path
        required: true
        description: Unique identifier (GUID) of the contact record.
        schema:
          type: string
          format: uuid
      - name: If-Match
        in: header
        description: Used for optimistic concurrency control. Set to the ETag value of the record to ensure you are updating the latest version.
        schema:
          type: string
      - $ref: '#/components/parameters/Prefer'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '204':
          description: Contact updated successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteContact
      summary: Microsoft Power Apps Delete a Contact
      description: Deletes an existing contact record from Dataverse.
      tags:
      - Contacts
      parameters:
      - name: contactid
        in: path
        required: true
        description: Unique identifier (GUID) of the contact record.
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Contact deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    Forbidden:
      description: The authenticated user does not have sufficient permissions to perform this operation. Check Dataverse security roles and privileges.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    NotFound:
      description: The requested record was not found. Verify the record identifier is correct and the record exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    BadRequest:
      description: The request was malformed or contained invalid data. Check the request body and query parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Unauthorized:
      description: Authentication failed. Ensure a valid OAuth 2.0 bearer token is included in the Authorization header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    PreconditionFailed:
      description: The If-Match header value does not match the current ETag of the record, indicating the record has been modified since it was last retrieved. Retrieve the latest version and retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
  schemas:
    ODataError:
      type: object
      description: Standard OData error response from the Dataverse Web API.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable error message.
            innererror:
              type: object
              properties:
                message:
                  type: string
                  description: Detailed inner error message.
                type:
                  type: string
                  description: Error type identifier.
                stacktrace:
                  type: string
                  description: Server-side stack trace for debugging.
          example: example_value
    Contact:
      type: object
      description: Person with whom a business unit has a relationship, such as a customer, supplier, or colleague. Corresponds to the contact entity type in the Microsoft.Dynamics.CRM namespace.
      properties:
        contactid:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier of the contact.
          example: '500123'
        firstname:
          type: string
          maxLength: 50
          description: First name of the contact.
          example: example_value
        lastname:
          type: string
          maxLength: 50
          description: Last name of the contact.
          example: example_value
        fullname:
          type: string
          maxLength: 160
          readOnly: true
          description: Full name of the contact, combining first name, middle name, and last name.
          example: example_value
        middlename:
          type: string
          maxLength: 50
          description: Middle name or initial of the contact.
          example: example_value
        nickname:
          type: string
          maxLength: 100
          description: Nickname of the contact.
          example: example_value
        salutation:
          type: string
          maxLength: 100
          description: Salutation for correspondence with the contact.
          example: example_value
        suffix:
          type: string
          maxLength: 10
          description: Suffix used in the contact's name.
          example: example_value
        jobtitle:
          type: string
          maxLength: 100
          description: Job title of the contact.
          example: example_value
        department:
          type: string
          maxLength: 100
          description: Department or business unit where the contact works.
          example: example_value
        emailaddress1:
          type: string
          format: email
          maxLength: 100
          description: Primary email address for the contact.
          example: user@example.com
        emailaddress2:
          type: string
          format: email
          maxLength: 100
          description: Secondary email address for the contact.
          example: user@example.com
        emailaddress3:
          type: string
          format: email
          maxLength: 100
          description: Alternate email address for the contact.
          example: user@example.com
        telephone1:
          type: string
          maxLength: 50
          description: Main phone number for the contact.
          example: example_value
        telephone2:
          type: string
          maxLength: 50
          description: Second phone number for the contact.
          example: example_value
        telephone3:
          type: string
          maxLength: 50
          description: Third phone number for the contact.
          example: example_value
        mobilephone:
          type: string
          maxLength: 50
          description: Mobile phone number for the contact.
          example: example_value
        fax:
          type: string
          maxLength: 50
          description: Fax number for the contact.
          example: example_value
        websiteurl:
          type: string
          format: uri
          maxLength: 200
          description: Website URL for the contact.
          example: https://www.example.com
        description:
          type: string
          maxLength: 2000
          description: Additional information to describe the contact.
          example: A sample description.
        gendercode:
          type: integer
          description: Gender of the contact. 1 = Male, 2 = Female.
          enum:
          - 1
          - 2
          example: 1
        familystatuscode:
          type: integer
          description: Marital status of the contact. 1 = Single, 2 = Married, 3 = Divorced, 4 = Widowed.
          enum:
          - 1
          - 2
          - 3
          - 4
          example: 1
        birthdate:
          type: string
          format: date
          description: Birthday of the contact.
          example: '2026-01-15'
        anniversary:
          type: string
          format: date
          description: Anniversary date of the contact.
          example: '2026-01-15'
        spousesname:
          type: string
          maxLength: 100
          description: Name of the contact's spouse or partner.
          example: example_value
        numberofchildren:
          type: integer
          description: Number of children the contact has.
          example: 10
        address1_name:
          type: string
          maxLength: 200
          description: Descriptive name for the primary address.
          example: example_value
        address1_line1:
          type: string
          maxLength: 250
          description: First line of the primary address.
          example: example_value
        address1_line2:
          type: string
          maxLength: 250
          description: Second line of the primary address.
          example: example_value
        address1_line3:
          type: string
          maxLength: 250
          description: Third line of the primary address.
          example: example_value
        address1_city:
          type: string
          maxLength: 80
          description: City for the primary address.
          example: example_value
        address1_stateorprovince:
          type: string
          maxLength: 50
          description: State or province for the primary address.
          example: example_value
        address1_postalcode:
          type: string
          maxLength: 20
          description: ZIP code or postal code for the primary address.
          example: example_value
        address1_country:
          type: string
          maxLength: 80
          description: Country or region for the primary address.
          example: example_value
        address1_county:
          type: string
          maxLength: 50
          description: County for the primary address.
          example: example_value
        address1_telephone1:
          type: string
          maxLength: 50
          description: Main phone number for the primary address.
          example: example_value
        address1_fax:
          type: string
          maxLength: 50
          description: Fax number for the primary address.
          example: example_value
        address1_latitude:
          type: number
          format: double
          description: Latitude value for the primary address.
          example: 42.5
        address1_longitude:
          type: number
          format: double
          description: Longitude value for the primary address.
          example: 42.5
        address2_name:
          type: string
          maxLength: 200
          description: Descriptive name for the secondary address.
          example: example_value
        address2_line1:
          type: string
          maxLength: 250
          description: First line of the secondary address.
          example: example_value
        address2_line2:
          type: string
          maxLength: 250
          description: Second line of the secondary address.
          example: example_value
        address2_line3:
          type: string
          maxLength: 250
          description: Third line of the secondary address.
          example: example_value
        address2_city:
          type: string
          maxLength: 80
          description: City for the secondary address.
          example: example_value
        address2_stateorprovince:
          type: string
          maxLength: 50
          description: State or province for the secondary address.
          example: example_value
        address2_postalcode:
          type: string
          maxLength: 20
          description: ZIP code or postal code for the secondary address.
          example: example_value
        address2_country:
          type: string
          maxLength: 80
          description: Country or region for the secondary address.
          example: example_value
        preferredcontactmethodcode:
          type: integer
          description: Preferred method of contact. 1 = Any, 2 = Email, 3 = Phone, 4 = Fax, 5 = Mail.
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
          example: 1
        donotemail:
          type: boolean
          description: Whether the contact allows direct email.
          example: user@example.com
        donotphone:
          type: boolean
          description: Whether the contact allows phone calls.
          example: true
        donotfax:
          type: boolean
          description: Whether the contact allows faxes.
          example: true
        donotpostalmail:
          type: boolean
          description: Whether the contact allows direct mail.
          example: true
        donotbulkemail:
          type: boolean
          description: Whether the contact allows bulk email through campaigns.
          example: user@example.com
        donotsendmm:
          type: boolean
          description: Whether the contact accepts marketing materials.
          example: true
        creditlimit:
          type: number
          format: decimal
          description: Credit limit of the contact.
          example: 42.5
        creditonhold:
          type: boolean
          description: Whether the credit for the contact is on hold.
          example: true
        statecode:
          type: integer
          description: Status of the contact. 0 = Active, 1 = Inactive. Inactive contacts are read-only.
          enum:
          - 0
          - 1
          readOnly: true
          example: 0
        statuscode:
          type: integer
          description: Status reason for the contact. 1 = Active, 2 = Inactive.
          enum:
          - 1
          - 2
          example: 1
        createdon:
          type: string
          format: date-time
          readOnly: true
          description: Date and time when the contact record was created.
          example: '2026-01-15T10:30:00Z'
        modifiedon:
          type: string
          format: date-time
          readOnly: true
          description: Date and time when the contact record was last updated.
          example: '2026-01-15T10:30:00Z'
        versionnumber:
          type: integer
          format: int64
          readOnly: true
          description: Version number of the contact record.
          example: 10
        _parentcustomerid_value:
          type: string
          format: uuid
          readOnly: true
          description: Lookup property for the parent customer (account or contact) associated with this contact.
          example: example_value
        _ownerid_value:
          type: string
          format: uuid
          readOnly: true
          description: Lookup property for the user or team assigned to manage the record.
          example: example_value
        _transactioncurrencyid_value:
          type: string
          format: uuid
          readOnly: true
          description: Lookup property for the currency associated with the record.
          example: example_value
        yomifirstname:
          type: string
          maxLength: 150
          description: Phonetic spelling of the first name (Japanese).
          example: example_value
        yomilastname:
          type: string
          maxLength: 150
          description: Phonetic spelling of the last name (Japanese).
          example: example_value
        yomimiddlename:
          type: string
          maxLength: 150
          description: Phonetic spelling of the middle name (Japanese).
          example: example_value
        yomifullname:
          type: string
          maxLength: 450
          readOnly: true
          description: Phonetic spelling of the full name (Japanese).
          example: example_value
      x-ms-dynamics-entity:
        entitySetName: contacts
        primaryKey: contactid
        primaryNameColumn: fullname
        namespace: Microsoft.Dynamics.CRM
        baseType: crmbaseentity
    ContactCollection:
      type: object
      description: OData collection response containing contact records.
      properties:
        '@odata.context':
          type: string
          format: uri
          description: OData context URL describing the collection.
          example: https://www.example.com
        '@odata.count':
          type: integer
          description: Total count of matching records (when $count=true).
          example: 10
        '@odata.nextLink':
          type: string
          format: uri
          description: URL to retrieve the next page of results.
          example: https://www.example.com
        value:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
          description: Array of contact records.
          example: []
  parameters:
    ODataCount:
      name: $count
      in: query
      description: Set to true to include a count of matching records in the response.
      schema:
        type: boolean
      example: true
    ODataExpand:
      name: $expand
      in: query
      description: Comma-separated list of navigation properties to expand inline in the response. Supports nested $select and $filter on expanded entities.
      schema:
        type: string
      example: primarycontactid($select=fullname,emailaddress1)
    ODataMaxPageSize:
      name: Prefer
      in: header
      description: Set the maximum page size for paginated results using odata.maxpagesize preference. Default is 5000 records.
      schema:
        type: string
      example: odata.maxpagesize=100
    Prefer:
      name: Prefer
      in: header
      description: OData preference header. Common values include return=representation (return created/updated record), odata.include-annotations="*" (include formatted values), and odata.maxpagesize=N (set page size).
      schema:
        type: string
      example: return=representation,odata.include-annotations="*"
    ODataFilter:
      name: $filter
      in: query
      description: OData filter expression to restrict the set of records returned. Supports standard OData comparison, logical, and function operators.
      schema:
        type: string
      example: statecode eq 0
    ODataOrderBy:
      name: $orderby
      in: query
      description: Comma-separated list of properties to sort results by, each optionally followed by asc or desc.
      schema:
        type: string
      example: name asc
    ODataSkip:
      name: $skip
      in: query
      description: Number of records to skip before returning results.
      schema:
        type: integer
        minimum: 0
    ODataSelect:
      name: $select
      in: query
      description: Comma-separated list of property names to include in the response. Use to limit the properties returned and improve performance.
      schema:
        type: string
      example: name,accountnumber,emailaddress1
    ODataTop:
      name: $top
      in: query
      description: Maximum number of records to return.
      schema:
        type: integer
        minimum: 1
      example: 50
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication using Microsoft Entra ID (formerly Azure Active Directory). Applications must be registered in Microsoft Entra ID and granted appropriate Dataverse permissions.
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
          scopes:
            https://{organization}.crm.dynamics.com/.default: Full access to Dataverse environment
            https://{organization}.crm.dynamics.com/user_impersonation: Access Dataverse as the signed-in user
externalDocs:
  description: Microsoft Dataverse Web API Reference
  url: https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/reference/about