Salesforce Contacts API

openapi: 3.2.0
info:
  title: Salesforce Marketing Cloud REST Contacts API
  description: The Salesforce Marketing Cloud REST API provides access to Marketing Cloud resources including contacts, journeys, data extensions, triggered sends, and transactional messaging. It uses OAuth 2.0 for authentication and is the primary interface for programmatic Marketing Cloud integrations.
  version: v1
  contact:
    name: Salesforce Marketing Cloud Developers
    url: https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/rest-api.html
  license:
    name: Salesforce Developer Terms
    url: https://www.salesforce.com/company/legal/agreements/
servers:
- url: https://{subdomain}.rest.marketingcloudapis.com
  description: 'Marketing Cloud REST API endpoint. The subdomain is the tenant-specific subdomain for the Marketing Cloud account.

    '
  variables:
    subdomain:
      default: YOUR_SUBDOMAIN
      description: 'The Marketing Cloud tenant subdomain (also known as the MID-specific subdomain). Obtain this from the Marketing Cloud Setup > Company Settings > Account Info.

        '
security:
- BearerAuth: []
tags:
- name: Contacts
  description: Operations for listing, retrieving, and deleting Marketing Cloud contact records.
paths:
  /contacts/v1/contacts:
    get:
      operationId: listContacts
      summary: List contacts
      description: Returns a paginated list of contacts in the Marketing Cloud account. Contacts are the core subscriber entities that can be subscribed to email, SMS, or other channels. Use the page and pageSize parameters to paginate through large contact lists.
      tags:
      - Contacts
      parameters:
      - name: page
        in: query
        required: false
        description: The page number to retrieve. Defaults to 1.
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: pageSize
        in: query
        required: false
        description: The number of contacts to return per page. Defaults to 50.
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 200
      responses:
        '200':
          description: Paginated list of contacts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: Array of contact records.
                    items:
                      $ref: '#/components/schemas/Contact'
                  count:
                    type: integer
                    description: Total number of contacts matching the request.
                  page:
                    type: integer
                    description: The current page number.
                  pageSize:
                    type: integer
                    description: The number of items per page.
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteContacts
      summary: Delete contacts
      description: Deletes one or more contacts from Marketing Cloud. Deletion is asynchronous; the response indicates the operation was accepted. Contact deletion removes the contact and their data across all business units in the account.
      tags:
      - Contacts
      requestBody:
        required: true
        description: Contact keys identifying the contacts to delete.
        content:
          application/json:
            schema:
              type: object
              required:
              - contactKeys
              properties:
                contactKeys:
                  type: array
                  description: Array of contact keys (subscriber keys) to delete.
                  items:
                    type: string
                deleteOperationType:
                  type: string
                  enum:
                  - ContactAndAttributes
                  - BusinessUnit
                  - Enterprise
                  description: 'The scope of the deletion operation. ContactAndAttributes deletes the contact and all attribute data. BusinessUnit deletes the contact from the current business unit. Enterprise deletes from all business units.

                    '
      responses:
        '200':
          description: Contact deletion request accepted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestServiceMessageID:
                    type: string
                    description: 'Unique ID for the deletion request. Use this to track the deletion status.

                      '
                  resultMessages:
                    type: array
                    description: Result messages for the deletion request.
                    items:
                      type: string
        '400':
          description: Bad request. Invalid contact keys or deletion type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /contacts/v1/contacts/{contactKey}:
    get:
      operationId: getContact
      summary: Get a contact by contact key
      description: Retrieves a single Marketing Cloud contact by their contact key. The contact key is a unique identifier for the contact, typically the subscriber key or email address used when the contact was created.
      tags:
      - Contacts
      parameters:
      - name: contactKey
        in: path
        required: true
        description: 'The unique contact key (subscriber key) of the Marketing Cloud contact to retrieve.

          '
        schema:
          type: string
      responses:
        '200':
          description: The requested Marketing Cloud contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Contact not found for the specified contact key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Contact:
      type: object
      description: 'A Marketing Cloud contact record representing a subscriber or customer who can receive communications across email, SMS, and other channels.

        '
      properties:
        contactKey:
          type: string
          description: 'The unique identifier for this contact. Typically the subscriber key or email address.

            '
        contactId:
          type: integer
          description: The internal numeric ID assigned to the contact by Marketing Cloud.
        contactStatus:
          type: string
          description: 'The current status of the contact (e.g., Active, Unsubscribed, Held, Bounced).

            '
        isAnonymous:
          type: boolean
          description: Whether the contact is an anonymous (cookie-tracked) contact.
        attributeSets:
          type: array
          description: 'Array of attribute sets containing the contact''s profile data organized by Data Extension or attribute group.

            '
          items:
            type: object
            properties:
              name:
                type: string
                description: The name of the attribute set.
              items:
                type: array
                description: Array of attribute values in this set.
                items:
                  type: object
                  additionalProperties: true
    Error:
      type: object
      description: An error response from the Marketing Cloud REST API.
      properties:
        message:
          type: string
          description: Human-readable description of the error.
        errorcode:
          type: integer
          description: Marketing Cloud numeric error code.
        documentation:
          type: string
          description: URL to documentation about this error.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'OAuth 2.0 Bearer token obtained from the /v2/token endpoint. Include this token in the Authorization header as "Bearer {access_token}".

        '