Microsoft Dynamics 365 Contacts API

openapi: 3.1.0
info:
  title: Microsoft Dynamics 365 Dataverse Web Accounts Contacts API
  description: RESTful web service implementing OData v4.0 for interacting with data in Microsoft Dataverse, the underlying data platform for Dynamics 365 and Power Platform applications. This specification covers core CRM entities including accounts, contacts, and opportunities.
  version: 9.2.0
  contact:
    name: Microsoft Support
    url: https://support.microsoft.com/dynamics365
    email: support@microsoft.com
  license:
    name: Microsoft API License
    url: https://www.microsoft.com/licensing/terms/
  termsOfService: https://www.microsoft.com/licensing/terms/
servers:
- url: https://{org}.api.crm.dynamics.com/api/data/v9.2
  description: Dynamics 365 Dataverse Web API (Production)
  variables:
    org:
      default: yourorg
      description: The unique name of your Dynamics 365 organization.
security:
- oauth2: []
tags:
- name: Contacts
  description: Person with whom a business unit has a relationship, such as a customer, supplier, or colleague.
  externalDocs:
    url: https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/reference/contact
paths:
  /contacts:
    get:
      operationId: listContacts
      summary: Microsoft Dynamics 365 List contacts
      description: Retrieve a list of contact entity records. Supports OData query options including $select, $filter, $orderby, $top, $skip, and $expand.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/Select'
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/OrderBy'
      - $ref: '#/components/parameters/Top'
      - $ref: '#/components/parameters/Skip'
      - $ref: '#/components/parameters/Expand'
      - $ref: '#/components/parameters/Count'
      - $ref: '#/components/parameters/Prefer'
      responses:
        '200':
          description: Successfully retrieved contacts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                  '@odata.count':
                    type: integer
                  '@odata.nextLink':
                    type: string
                    format: uri
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createContact
      summary: Microsoft Dynamics 365 Create a contact
      description: Create a new contact entity record.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/Prefer'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      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 (when Prefer return=representation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /contacts({contactid}):
    get:
      operationId: getContact
      summary: Microsoft Dynamics 365 Retrieve a contact
      description: Retrieve a single contact entity record by its unique identifier.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/ContactId'
      - $ref: '#/components/parameters/Select'
      - $ref: '#/components/parameters/Expand'
      responses:
        '200':
          description: Successfully retrieved the contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateContact
      summary: Microsoft Dynamics 365 Update a contact
      description: Update an existing contact entity record.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/ContactId'
      - $ref: '#/components/parameters/Prefer'
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactUpdate'
      responses:
        '204':
          description: Contact updated successfully.
        '201':
          description: Contact updated successfully (when Prefer return=representation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
    delete:
      operationId: deleteContact
      summary: Microsoft Dynamics 365 Delete a contact
      description: Delete a contact entity record.
      tags:
      - Contacts
      parameters:
      - $ref: '#/components/parameters/ContactId'
      responses:
        '204':
          description: Contact deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    OrderBy:
      name: $orderby
      in: query
      required: false
      description: Comma-separated list of properties to sort by, with optional asc or desc.
      schema:
        type: string
    Count:
      name: $count
      in: query
      required: false
      description: Include a count of matching records in the response.
      schema:
        type: boolean
    ContactId:
      name: contactid
      in: path
      required: true
      description: Unique identifier of the contact record (GUID).
      schema:
        type: string
        format: uuid
    Expand:
      name: $expand
      in: query
      required: false
      description: Comma-separated list of navigation properties to expand.
      schema:
        type: string
    Filter:
      name: $filter
      in: query
      required: false
      description: OData filter expression to restrict results.
      schema:
        type: string
    IfMatch:
      name: If-Match
      in: header
      required: false
      description: ETag value for optimistic concurrency control. Use * to match any version.
      schema:
        type: string
    Skip:
      name: $skip
      in: query
      required: false
      description: Number of records to skip before returning results.
      schema:
        type: integer
        minimum: 0
    Select:
      name: $select
      in: query
      required: false
      description: Comma-separated list of properties to return.
      schema:
        type: string
    Top:
      name: $top
      in: query
      required: false
      description: Maximum number of records to return.
      schema:
        type: integer
        minimum: 1
        maximum: 5000
    Prefer:
      name: Prefer
      in: header
      required: false
      description: OData preference header. Use odata.include-annotations to request formatted values, or return=representation to return the created/updated record.
      schema:
        type: string
        examples:
        - return=representation
        - odata.include-annotations="*"
        - odata.maxpagesize=100
  responses:
    Forbidden:
      description: The authenticated user does not have permission to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    PreconditionFailed:
      description: The ETag value provided in the If-Match header does not match the current version of the record.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
  schemas:
    ContactUpdate:
      type: object
      description: Properties for updating an existing contact.
      properties:
        firstname:
          type: string
          maxLength: 50
          description: First name of the contact.
        middlename:
          type: string
          maxLength: 50
          description: Middle name of the contact.
        lastname:
          type: string
          maxLength: 50
          description: Last name of the contact.
        suffix:
          type: string
          maxLength: 10
          description: Suffix used in the contact name.
        salutation:
          type: string
          maxLength: 100
          description: Salutation for correspondence.
        nickname:
          type: string
          maxLength: 100
          description: Nickname of the contact.
        jobtitle:
          type: string
          maxLength: 100
          description: Job title of the contact.
        department:
          type: string
          maxLength: 100
          description: Department or business unit.
        emailaddress1:
          type: string
          format: email
          maxLength: 100
          description: Primary email address.
        emailaddress2:
          type: string
          format: email
          maxLength: 100
          description: Secondary email address.
        telephone1:
          type: string
          maxLength: 50
          description: Main phone number (business).
        telephone2:
          type: string
          maxLength: 50
          description: Second phone number (home).
        mobilephone:
          type: string
          maxLength: 50
          description: Mobile phone number.
        fax:
          type: string
          maxLength: 50
          description: Fax number.
        websiteurl:
          type: string
          format: uri
          maxLength: 200
          description: Website URL.
        description:
          type: string
          description: Additional information to describe the contact.
        gendercode:
          type: integer
          description: Gender code.
        familystatuscode:
          type: integer
          description: Marital status code.
        birthday:
          type: string
          format: date
          description: Birthday.
        preferredcontactmethodcode:
          type: integer
          description: Preferred method of contact code.
        donotemail:
          type: boolean
          description: Whether to allow direct email.
        donotphone:
          type: boolean
          description: Whether to allow phone calls.
        donotfax:
          type: boolean
          description: Whether to allow faxes.
        donotpostalmail:
          type: boolean
          description: Whether to allow direct mail.
        donotbulkemail:
          type: boolean
          description: Whether to allow bulk email.
        address1_name:
          type: string
          maxLength: 200
        address1_line1:
          type: string
          maxLength: 250
        address1_line2:
          type: string
          maxLength: 250
        address1_line3:
          type: string
          maxLength: 250
        address1_city:
          type: string
          maxLength: 80
        address1_stateorprovince:
          type: string
          maxLength: 50
        address1_postalcode:
          type: string
          maxLength: 20
        address1_country:
          type: string
          maxLength: 80
        address1_telephone1:
          type: string
          maxLength: 50
        address1_latitude:
          type: number
          format: double
        address1_longitude:
          type: number
          format: double
        statecode:
          type: integer
        statuscode:
          type: integer
        annualincome:
          type: number
          description: Annual income of the contact.
        parentcustomerid_account@odata.bind:
          type: string
          description: 'Bind reference to a parent account. Format: /accounts(GUID).'
        parentcustomerid_contact@odata.bind:
          type: string
          description: 'Bind reference to a parent contact. Format: /contacts(GUID).'
    ODataError:
      type: object
      description: OData error response from the Dataverse Web API.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code.
            message:
              type: string
              description: Human-readable error message.
            innererror:
              type: object
              properties:
                message:
                  type: string
                  description: Detailed error message.
                type:
                  type: string
                  description: Exception type.
                stacktrace:
                  type: string
                  description: Stack trace (available in non-production environments).
    Contact:
      type: object
      description: Person with whom a business unit has a relationship, such as customer, supplier, and colleague.
      properties:
        '@odata.etag':
          type: string
          description: ETag value for concurrency control.
          readOnly: true
        contactid:
          type: string
          format: uuid
          description: Unique identifier of the contact.
          readOnly: true
        firstname:
          type: string
          maxLength: 50
          description: First name of the contact.
        middlename:
          type: string
          maxLength: 50
          description: Middle name of the contact.
        lastname:
          type: string
          maxLength: 50
          description: Last name of the contact.
        fullname:
          type: string
          maxLength: 160
          description: Combined first name, middle name, and last name. Read-only, automatically generated.
          readOnly: true
        nickname:
          type: string
          maxLength: 100
          description: Nickname of the contact.
        salutation:
          type: string
          maxLength: 100
          description: Salutation for correspondence with the contact.
        suffix:
          type: string
          maxLength: 10
          description: Suffix used in the contact name, such as Jr. or Sr.
        jobtitle:
          type: string
          maxLength: 100
          description: Job title of the contact.
        department:
          type: string
          maxLength: 100
          description: Department or business unit where the contact works.
        managername:
          type: string
          maxLength: 100
          description: Name of the contact manager.
        assistantname:
          type: string
          maxLength: 100
          description: Name of the contact assistant.
        assistantphone:
          type: string
          maxLength: 50
          description: Phone number for the contact assistant.
        emailaddress1:
          type: string
          format: email
          maxLength: 100
          description: Primary email address for the contact.
        emailaddress2:
          type: string
          format: email
          maxLength: 100
          description: Secondary email address for the contact.
        emailaddress3:
          type: string
          format: email
          maxLength: 100
          description: Alternate email address for the contact.
        telephone1:
          type: string
          maxLength: 50
          description: Main phone number for the contact (business phone).
        telephone2:
          type: string
          maxLength: 50
          description: Second phone number for the contact (home phone).
        telephone3:
          type: string
          maxLength: 50
          description: Third phone number for the contact.
        mobilephone:
          type: string
          maxLength: 50
          description: Mobile phone number for the contact.
        fax:
          type: string
          maxLength: 50
          description: Fax number for the contact.
        pager:
          type: string
          maxLength: 50
          description: Pager number for the contact.
        websiteurl:
          type: string
          format: uri
          maxLength: 200
          description: Website URL for the contact.
        description:
          type: string
          description: Additional information to describe the contact.
        gendercode:
          type: integer
          description: 'Gender. Values: 1 (Male), 2 (Female).'
        familystatuscode:
          type: integer
          description: 'Marital status. Values: 1 (Single), 2 (Married), 3 (Divorced), 4 (Widowed).'
        spousesname:
          type: string
          maxLength: 100
          description: Name of the contact spouse or partner.
        birthday:
          type: string
          format: date
          description: Birthday of the contact.
        anniversary:
          type: string
          format: date
          description: Wedding anniversary date.
        preferredcontactmethodcode:
          type: integer
          description: 'Preferred method of contact. Values: 1 (Any), 2 (Email), 3 (Phone), 4 (Fax), 5 (Mail).'
        donotemail:
          type: boolean
          description: Whether the contact allows direct email.
        donotphone:
          type: boolean
          description: Whether the contact allows phone calls.
        donotfax:
          type: boolean
          description: Whether the contact allows faxes.
        donotpostalmail:
          type: boolean
          description: Whether the contact allows direct mail.
        donotbulkemail:
          type: boolean
          description: Whether the contact allows bulk email.
        donotsendmm:
          type: boolean
          description: Whether the contact accepts marketing materials.
        followemail:
          type: boolean
          description: Whether to allow following email activity.
        address1_name:
          type: string
          maxLength: 200
          description: Descriptive name for the primary address.
        address1_line1:
          type: string
          maxLength: 250
          description: First line of the primary address.
        address1_line2:
          type: string
          maxLength: 250
          description: Second line of the primary address.
        address1_line3:
          type: string
          maxLength: 250
          description: Third line of the primary address.
        address1_city:
          type: string
          maxLength: 80
          description: City for the primary address.
        address1_stateorprovince:
          type: string
          maxLength: 50
          description: State or province of the primary address.
        address1_postalcode:
          type: string
          maxLength: 20
          description: ZIP Code or postal code for the primary address.
        address1_country:
          type: string
          maxLength: 80
          description: Country or region for the primary address.
        address1_county:
          type: string
          maxLength: 50
          description: County for the primary address.
        address1_telephone1:
          type: string
          maxLength: 50
          description: Main phone number associated with the primary address.
        address1_fax:
          type: string
          maxLength: 50
          description: Fax number associated with the primary address.
        address1_latitude:
          type: number
          format: double
          description: Latitude value for the primary address.
        address1_longitude:
          type: number
          format: double
          description: Longitude value for the primary address.
        address1_addresstypecode:
          type: integer
          description: Primary address type code.
        address1_composite:
          type: string
          description: Complete primary address.
          readOnly: true
        address2_name:
          type: string
          maxLength: 200
          description: Descriptive name for the secondary address.
        address2_line1:
          type: string
          maxLength: 250
          description: First line of the secondary address.
        address2_line2:
          type: string
          maxLength: 250
          description: Second line of the secondary address.
        address2_city:
          type: string
          maxLength: 80
          description: City for the secondary address.
        address2_stateorprovince:
          type: string
          maxLength: 50
          description: State or province of the secondary address.
        address2_postalcode:
          type: string
          maxLength: 20
          description: ZIP Code or postal code for the secondary address.
        address2_country:
          type: string
          maxLength: 80
          description: Country or region for the secondary address.
        statecode:
          type: integer
          description: 'Whether the contact is active or inactive. Values: 0 (Active), 1 (Inactive).'
        statuscode:
          type: integer
          description: 'Contact status reason. Values: 1 (Active), 2 (Inactive).'
        annualincome:
          type: number
          description: Annual income of the contact.
        creditlimit:
          type: number
          description: Credit limit of the contact.
        creditonhold:
          type: boolean
          description: Whether credit is on hold for the contact.
        _parentcustomerid_value:
          type: string
          format: uuid
          description: Parent customer (account or contact) for the contact.
          readOnly: true
        _ownerid_value:
          type: string
          format: uuid
          description: Owner of the record.
          readOnly: true
        _createdby_value:
          type: string
          format: uuid
          description: User who created the record.
          readOnly: true
        _modifiedby_value:
          type: string
          format: uuid
          description: User who last updated the record.
          readOnly: true
        createdon:
          type: string
          format: date-time
          description: Date and time when the record was created.
          readOnly: true
        modifiedon:
          type: string
          format: date-time
          description: Date and time when the record was last updated.
          readOnly: true
        versionnumber:
          type: integer
          format: int64
          description: Version number of the contact.
          readOnly: true
        yomifirstname:
          type: string
          maxLength: 150
          description: Phonetic spelling of the first name (Japanese).
        yomilastname:
          type: string
          maxLength: 150
          description: Phonetic spelling of the last name (Japanese).
        yomimiddlename:
          type: string
          maxLength: 150
          description: Phonetic spelling of the middle name (Japanese).
        yomifullname:
          type: string
          maxLength: 450
          description: Combined phonetic full name (Japanese).
          readOnly: true
    ContactCreate:
      type: object
      description: Properties for creating a new contact.
      required:
      - lastname
      allOf:
      - $ref: '#/components/schemas/ContactUpdate'
      - type: object
        properties:
          lastname:
            type: string
            maxLength: 50
            description: Last name of the contact.
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication using Microsoft Entra ID (Azure Active Directory). Applications must be registered in Microsoft Entra ID and granted the appropriate Dynamics 365 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://{org}.api.crm.dynamics.com/.default: Full access to Dataverse Web API.
externalDocs:
  description: Microsoft Dataverse Web API Documentation
  url: https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/overview